With the deprecation announcement surrounding XML Application Integration (XAI), it is possible to convert to using Inbound Web Services (IWS) manually or using a simple script. This article will outline the process of building a script to bulk transfer the definitions over from XAI to IWS.
Ideally, it is recommended that you migrate each XAI Inbound Service to Inbound Web Services manually so that you can take the opportunity to rationalize your services and reduce your maintenance costs but if you want to simply transfer over to the new facility in bulk this can be done via a service script to migrate the information.
This can be done using a number of techniques:
In this article I will outline the latter example to illustrate the migration as well as highlight how to build a Plug In Batch process using configuration alone.
Note: Code and Design in this article are provided for illustrative purposes and only cover the basic functionality needed for the article. Variations on this design are possible through the flexibility of the extensible of the product. These are not examined in any detail except to illustrate the basic process.
Note: The names of the objects in this article are just examples. Alternative values can be used, if desired.
The design for this is as follows:
The following diagram illustrates the overall process:
The design of the Plug In Batch will only work for Oracle Utilities Application Framework V188.8.131.52.0 and above but the Service Script used for the conversion can be used with any implementation of Oracle Utilities Application Framework V184.108.40.206.0 and above. On older versions you can hook the script into another script such as BPA or drive it from a query zone.
Note: This process should ONLY be used to migrate XAI Inbound Services that are Customer Modifications. Services owned by the product itself should not be migrated to respect record ownership rules.
The first part of the process is to build a service script that establishes an Inbound Web Service for an XML Application Integration Inbound Service. To build the script the following process should be used:
|Setting||XAI Inbound Service BO Values||IWS Service BO Values|
|Description||XAI Service Conversion BO||IWS Service Conversion BO|
|Detailed Description||Conversion BO for XML Application Integration||Conversion BO for Inbound Web Services|
|Maintenance Object||XAI SERVICE||F1-IWSSVC|
|Instance Control||Allow New Instances||Allow New Instances|
|Description||Convert an XAI Service to IWS Service|
Script that converts the passed in XAI Service Id into an Inbound Web Service.
- Reads the XAI Inbound Service definition
|Script Type||Service Script|
|Script Engine Version||3.0|
|Data Area||CMIWSService - Data Area Name IWSService|
|Data Area||CMXAIService - Data Area Name XAIService|
|Schema (this is the input value and some temporary variables)||
The Data Area section looks like this:
Note: The code below is very basic and there are optimizations that can be done to make it smaller and more efficient. This is just some sample code to illustrate the process.
10: edit data
// Jump out if the inbound service Id is blank
if ("string(parm/xaiInboundService) = $BLANK")
20: edit data
// populate the key value from the input parameter
move "parm/xaiInboundService" to "XAIService/xaiServiceId";
// invoke the XAI Service BO to read the service definition
invokeBO 'CMXAIService' using "XAIService" for read;
// Check that the Service Name is populated at a minimum
if ("XAIService/xaiInServiceName = $BLANK")
// Check that the Service type is correct
if ("XAIService/xaiAdapter != BusinessAdaptor")
// Check that the owner flag is CM
if ("XAIService/customizationOwner != CM")
30: edit data
// Copy the key attributes from XAI to IWS
move "XAIService/xaiInServiceName" to "IWSService/iwsName";
move "XAIService/description" to "IWSService/description";
move "XAIService/longDescription" to "IWSService/longDescription";
move "XAIService/isTracing" to "IWSService/isTracing";
move "XAIService/postError" to "IWSService/postError";
move "XAIService/shouldDebug" to "IWSService/shouldDebug";
move "XAIService/xaiInServiceName" to "IWSService/defaultOperation";
// Assume the service will be Active (this can be altered)
// For example, set this to false to allow for manual checking of the
// setting. That way you can confirm the service is set correctly and then
// manually set Active to true in the user interface.
move 'true' to "IWSService/isActive";
// Process the list for the operation to the temporary variables in the schema
move "XAIService/xaiInServiceName" to "parm/operations/iwsName";
move "XAIService/xaiInServiceName" to "parm/operations/operationName";
move "XAIService/requestSchema" to "parm/operations/requestSchema";
move "XAIService/responseSchema" to "parm/operations/responseSchema";
move "XAIService/inputXSL" to "parm/operations/requestXSL";
move "XAIService/responseXSL" to "parm/operations/responseXSL";
move "XAIService/schemaName" to "parm/operations/schemaName";
move "XAIService/schemaType" to "parm/operations/schemaType";
// move "XAIService/transactionType" to "parm/operations/transactionType";
move "XAI/searchType" to "parm/operations/searchType";
// Add the parameters to the operation list object
move "parm/operations" to "IWSService/+iwsServiceOperation";
40: edit data
// Invoke BO for Add
invokeBO 'CMIWSService' using "IWSService" for add;
Note: The code example above does not add annotations to the Inbound Web Service to attach policies for true backward compatibility. It is assumed that policies are set globally rather than on individual services. If you want to add annotation logic to the script it is recommended to add an annotations group to the script internal data area and add annotations list in logic in the script.
One thing to point out for XAI. To use the same payload for an XAI service in Inbound Web Services, a single operation must exist with the same name as the Service Name. This is the design pattern for a one to one conversion. It is possible to vary from that if you manually convert from XAI to IWS as it is possible to reduce the number of services in IWS using multiple operations. Refer to Migrating from XAI to IWS (Doc Id: 1644914.1) and Web Services Best Practices (Doc Id: 2214375.1) from My Oracle Support for a discussion of the various techniques available. The attribute mapping looks like this:
The Service Script has now been completed. All it needs is to pass the XAI Inbound Service Identifier (not the name) to parm/xaiInboundService structure.
In past releases, the only way to build a Batch process that is controlled via a Batch Control was to use the Oracle Utilities SDK using Java. It is now possible to define what is termed a Plug In based Batch Control which allows you to use ConfigTools and some configuration to build your batch process. The fundamental principle is that batch is basically selecting a set of records to process and then passing those records into something to process them. In our case, we will provide an SQL statement to subset the services to convert from XAI to pass to the service we just built in the previous step.
The first part of the Plug In Batch process is to define the Select Records algorithm that defines the parameters for the Batch process, the commit strategy and the SQL used to pump the records into the process. The first step is to create a script to be used for the Algorithm Type of Select Records to define the parameters and the commit strategy. For this example I created a script with the following parameters:
|Description||XAI Select Record Script - Parameters|
|Detailed Description||This script is the driver for the Select Records algorithm for the XAI to IWS conversion|
|Script Type||Plug In Script|
|Algorithm Entity||Batch Control - Select Records|
Note: I have NO parameters for this job. If you wish to add processing for parameters, take a look at some examples of this algorithm type to see the processing necessary for bind variables.
The next step is to create an algorithm type. This will be used by the algorithm itself to define the process. Typically, an algorithm type is the definition of the physical aspects of the algorithm and its parameters. For the select algorithm the following algorithm type was created:
|Description||XAI Selection Algorithm|
|Detailed Description||This algorithm Type is a generic wrapper to set the job parameters|
|Algorithm Entity||Batch Control - Select Records|
|Program Type||Plug In Script|
|Plug In Script||CMXAISEL|
|Parameter||SQL (Sequence 1 - Required) - This is the SQL to pass into the process|
The last step is to create the Algorithm to be used in the Batch Control. This will use the Algorithm Type created earlier. Create the algorithm definition as follows:
|Description||XAI Conversion Selection|
|Effective Date||Any valid date in the past is acceptable|
You might notice the SQL used in the driver. It passes the XAI_IN_SVC_ID's for XAI Inbound Services that use the Business Adaptor, are not already converted (for restart) and are owned by Customer Modification.
The next step is to link the script created earlier to the Process Records algorithm. As with the Select Records algorithm, a script, an algorithm type and algorithm entries need to be created.
The first part of the process is to build a Plug-In Script to pass the data from the Select Records Algorithm to the Service Script that does the conversion. The parameters are as follows:
|Description||Process XAI Records in Batch|
|Detailed Description||This script reads the parameters from the Select records and passes them to the XAI Conversion script|
|Script Type||Plug-In Script|
|Algorithm Entity||Batch Control - Process Record|
|Data Area||Service Script - CMConvertXAI - Data Area Name ConvertXAI|
The script above basically takes the parameters passed to the algorithm and then passes them to the Service Script for processing
The next step is to define this script as an Algorithm Type:
|Description||XAI Conversion Algorithm|
|Detailed Description||This algorithm type links the algorithm to the service script to drive the process.|
|Algorithm Entity||Batch Control - Process Record|
|Program Type||Plug-In Script|
The last step in the algorithm process is to create the Algorithm entry itself:
|Description||XAI Conversion Process Record|
The last part of the process is to bring all the configuration into a single place, the Batch Control. This will pull in the algorithms into a configuration ready for use.
|Description||Convert XAI Services to IWS|
This batch control converts the XAI Inbound Services to Inbound Web Services to aid in the mass migration of the meta data to the new facility.
- XAI Services that are owned by Customer Modification to respect record ownership.
|Batch Control Type||Not Timed|
|Algorithm - Select Records||CMXAISEL|
|Algorithm - Process Records||CMXAIPROCESS|
The Plug-in batch process is now defined.
The conversion process can be summarized as follows: