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:
- You can drive the migration via a query portal that can be called via a Business Service from a BPA or batch process.
- You can use the Plug-In Batch to pump the services through a script to save time.
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.
Design
The design for this is as follows:
- Build a Service script that will take the XAI Inbound Service identifier to migrate and perform the following
- Read the XAI Inbound Service definition to load the variables for the migration
- Check that the XAI Inbound Service is valid to be migrated. This means it must be owned by Customer Modification and uses the Business Adaptor XAI Adapter.
- Transfer the XAI Inbound Service definition to the relevant fields in the Inbound Web Service and add the service. Optionally activate the service ready for deployment. The deployment activity itself should not be part of the script as it is not a per service activity usually.
- By default the following is transferred:
- The Web Service name would be the Service Name on the XAI Inbound Service not the identifier as that is randomly generated.
- Common attributes are transferred across from the existing definition
- A single operation, with the same name as the Inbound Web Service, is created as a minimalist migration option.
- Build a Plug In Batch definition to include the following:
- The Select Record algorithm will identify the list of services to migrate. It should be noted that only services that are owned by the Customer Modification (CM) owner should be migrated as ownership should be respected.
- The script for the above will be used in the Process Record algorithm.
The following diagram illustrates the overall process:
![Plug In Development Process]()
The design of the Plug In Batch will only work for Oracle Utilities Application Framework V4.3.0.4.0 and above but the Service Script used for the conversion can be used with any implementation of Oracle Utilities Application Framework V4.2.0.2.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.
XAI Inbound Service Conversion Service Script
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:
- Create Business Objects - Create a Business Object, using Business Object maintenance, based upon XAI SERVICE (XAI Inbound Service) and F1-IWSSVC (Inbound Web Service) to be used as Data Areas in your script. You can leave the schema's as generated with all the elements defined or remove the elements you do not need (as this is only a transient piece of functionality). I will assume that the schema will be as the default generation using the Schema generator in the Dashboard. Remember to allocate the Application Service for security purposes (I used F1-DFLTS as that is provided in the base meta data). The settings for the Business Objects are summarized as follows:
SettingXAI Inbound Service BO ValuesIWS Service BO ValuesBusiness Object
CMXAIService
CMIWSService
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
Application Service
F1-DFLTS
F1-DFLTS
Instance Control
Allow New Instances
Allow New Instances
- Build Script - Build a Service Script with the following attributes:
SettingValueScript
CMConvertXAI
Description
Convert an XAI Service to IWS Service
Detailed DescriptionScript that converts the passed in XAI Service Id into an Inbound Web Service.
- Reads the XAI Inbound Service definition
- Copies the relevant attributes to the Inbound Web Service
- Add the Inbound Web Service
Script Type
Service Script
Application Service
F1-DFLTAPS
Script Engine Version
3.0
Data Area
CMIWSService - Data Area Name
IWSServiceData Area
CMXAIService - Data Area Name
XAIServiceSchema (this is the input value and some temporary variables)
<schema>
<xaiInboundService mdField="XAI_IN_SVC_ID"/>
<operations type="group">
<iwsName/>
<operationName/>
<requestSchema/>
<responseSchema/>
<requestXSL/>
<responseXSL/>
<schemaName/>
<schemaType/>
<transactionType/>
<searchType/>
</operations>
</schema>
The Data Area section looks like this:
![]()
- Add the following code to your script (this is in individual edit-data steps):
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")
terminate;
end-if;
end-edit;
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")
terminate;
end-if;
// Check that the Service type is correct
if ("XAIService/xaiAdapter != BusinessAdaptor")
terminate;
end-if;
// Check that the owner flag is CM
if ("XAIService/customizationOwner != CM")
terminate;
end-if;
end-edit;
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";
end-edit;
40: edit data
// Invoke BO for Add
invokeBO 'CMIWSService' using "IWSService" for add;
end-edit;
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:
![Mapping of objects]()
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.
Building The Plug In Batch Control
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.
Select Records Algorithm
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:
SettingValueScript
CMXAISEL
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
Script Version
3.0
Script Step
10: edit data
// Set strategy and key field
// Strategy values are dictated by BATCH_STRATEGY_FLG lookup
// Set JOBS strategy as this is a single threaded process
// I could use THDS strategy but then would have to put in logic for
// restart in the SQL. The current SQL has that logic already implied.
move '
JOBS' to "parm/hard/batchStrategy";
move '
XAI_IN_SVC_ID' to "parm/hard/keyField";
end-edit;
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:
SettingValueAlgorithm Type
CMXAISEL
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:
SettingValueAlgorithm Code
CMXAISEL
Description
XAI Conversion Selection
Algorithm Type
CMXAISEL
Effective Date
Any valid date in the past is acceptable
SQL ParameterSELECT xai_in_svc_id FROM ci_xai_in_svc
WHERE xai_adapter_id = 'BusinessAdaptor'
AND
xai_in_svc_name NOT IN ( SELECT in_svc_name FROM f1_iws_svc)
AND
owner_flg = 'CM'
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.
Process Records Algorithm
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:
SettingRecommended ValueScript
CMXAIProcess
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
Script Version
3.0
Data Area
Service Script -
CMConvertXAI - Data Area Name
ConvertXAIScript Step
if ("parm/hard/selectedFields/Field[name='XAI_IN_SVC_ID']/value != $BLANK")
move "parm/hard/selectedFields/Field[name='XAI_IN_SVC_ID']/value" to "ConvertXAI/xaiInboundService";
invokeSS 'CMConvertXAI' using "ConvertXAI" ;
end-if;
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:
SettingValueAlgorithm Type
CMXAIPROC
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
Plug-In Script
CMXAIProcess
The last step in the algorithm process is to create the Algorithm entry itself:
SettingValueAlgorithm Code
CMXAIPROCESS
Description
XAI Conversion Process Record
Algorithm Type
CMXAIPROC
Plug In Batch Control Configuration
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.
SettingValueBatch Control
CMXAICNV
Description
Convert XAI Services to IWS
Detailed DescriptionThis 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.
This batch job only converts the following:
- XAI Services that are owned by Customer Modification to respect record ownership.
- XAI Services that use the Business Adaptor XAI Adapter. Other types are auto converted in IWS
- XAI Services that are not already defined as Inbound Web Services
Application Service
F1-DFLTAPS
Batch Control Type
Not Timed
Batch Category
Adhoc
Algorithm - Select Records
CMXAISEL
Algorithm - Process Records
CMXAIPROCESS
The Plug-in batch process is now defined.
Summary
The conversion process can be summarized as follows:
- A Service Script is required to transfer the data from the XAI Inbound Web Service to the Inbound Web Service definition. This converts only services owned by Customer Modification, have not been migrated already and use the Business Adaptor XAI Adapter. The script sets the same parameters as the XAI Service for backward compatibility and creates a SINGLE operation Web Service with the same payload as the original.
- The Select Records Algorithm is defined which defines the subset of records to process with a script that defines the job properties, an algorithm entry to define the script to the framework and an algorithm, with the SQL to use, to link to the Batch Control.
- The Process Records Algorithm is defined which defines the processing from the Select Records and links in the Service Script from the first step. As with any algorithm, the code is built, in this case in Plug-In Script to link the data to the script, an algorithm type entry defines the script and then an algorithm definition is created to link to the batch control.
- The last step is to create the Batch Control that links the Select Records and Process Records algorithms.
