XAPI Service

The XAPI service enables use of any XAPI provided with the application in a business process.

The following table provides an overview of the XAPI service:

Category Description
System Name XAPI
Graphical Process Modeler (GPM) categories) All Services, System Services
Description Enables use of any XAPI in a business process.
Business usage Enables the business process writer to access any of the XAPIs and their functionality and exploit it in a business process.
Usage example You want to see how many ACH translation maps are on your system; use the getMaplist API to find and return a list of all the maps that have “ACH” in the name. Subsequent steps in the business process might move the list to a document and export it to a folder on a server or e-mail it to the user.
Preconfigured? No
Requires third-party files? Yes. Must refer to a XAPI included with the Application.
Platform availability All supported Sterling B2B Integrator platforms
Related services None
Application requirements Must have access to XAPIs
Initiates business processes? No
Invocation From a business process
Business process context considerations After invoking a XAPI, the results are stored in the WFC so that a subsequent step in the business process can use the results.
Returned status values
Returned status values:
  • Success
  • Error
Restrictions None
Persistence level Default
Testing considerations Test by using in a business process.

How the XAPI Service Works

The XAPI service enables you to call any of the application XAPIs and return results which can then be used by a later step in the business process.

Implementing the XAPI Service

To implement the XAPI service, complete the following tasks:
  1. Create a configuration of the XAPI service. See Managing Services and Adapters. For information about the fields specific to this service, see Configuring the XAPI Service.
  2. Specify field settings in the GPM as necessary.

Configuring the XAPI Service

You must specify field settings at the business process level, using the GPM. Use the field definitions in the following table to set up the service configuration in the GPM:

Field Description
Config Select the name of the service configuration from the list.
api The name of the XAPI to be invoked. Required. This is for the name of the API you want to call. The XAPI framework will fail if the xapi is bad. If this parameter is not specified, then this business process must fail and an error message “Required xapi parameter is missing.” must be written to the status report. Required.
xml This is the xml content that needs to be passed to the API. If this parameter is not available then input document must be treated as the input XML. If input document is also not available, then this business process must fail and the error message "Missing Data" must be written to the status report. If the input XML is not a well formed Document object, write an error message "Invalid input" to the business process status report and this business process must fail. Required.
split The xpath to split a document to several parts. You can use this parameter to specify several inputs to the API in the xml. You specify the split to get the different inputs. See the example above for how to use it. The resulting outputs of the call will be saved into Document-1,.... , Document-n. Optional.
template Pass on this parameter to the xapi framework if specified. When specified, if the template XML is not a well formed Document object, write an error message "Invalid Template" to the business process status report and this business process must fail. Optional.
Note: Some APIs ignore the template.
UserId Pass on this parameter to the xapi framework. If not provided, a default value will be given. Optional.
ProgId Pass on this parameter to the xapi framework. If it is not provided, a default value will be given. Optional.

Business Process Example

The following example illustrates how the XAPI service can be used in a business process: 

<process name="XAPITest">
  <sequence>
    <operation> 
      <participant name="XAPIService"/> 
      <output message="XAPIServiceInputMesage">
        <assign to="api">getServiceInstanceDetails</assign>
        <assign to="xml"><![CDATA[<root>
          <test>
            <ServiceInstance OrgKey="" ServiceName="AssignService"/>
          </test>
          <test>
            <ServiceInstance OrgKey="" ServiceName="AssociateBPsToDocs"/>
          </test></root>]]>
        </assign> 
        <assign to="split">/root/test/ServiceInstance</assign> 
        <assign to="UserId">admin</assign>
        <assign to="ProgId">foo</assign> 
      </output>
      <input message="XAPIServiceOutputMessage">    
        <assign to="." from="*"></assign> 
      </input>
    </operation> 
  </sequence>
</process>

Parameters Passed From Service to Business Process

The following table contains the parameters passed from the XAPI service to the business process:

Parameter Description
api The name of the XAPI to be invoked. Required. This is for the name of the API you want to call. The XAPI framework will fail if the xapi is bad. If this parameter is not specified, then this business process must fail and an error message "Required xapi parameter is missing." must be written to the status report. Required.
xml This is the xml content that needs to be passed to the API. If this parameter is not available then input document must be treated as the input XML. If input document is also not available, then this business process must fail and the error message "Missing Data" must be written to the status report. If the input XML is not a well formed Document object, write an error message "Invalid input" to the business process status report and this business process must fail. Required.
split The xpath to split a document to several parts. You can use this parameter to specify several inputs to the API in the xml. You specify the split to get the different inputs. See the example above for how to use it. The resulting outputs of the call will be saved into Document-1, ...., Document-n. Optional.
template Pass on this parameter to the xapi framework if specified. When specified, if the template XML is not a well formed Document object, write an error message "Invalid Template" to the business process status report and this business process must fail. Optional.
Note: Some APIs ignore the template.
UserId Pass on this parameter to the xapi framework. If not provided, a default value will be given. Optional.
ProgId Pass on this parameter to the xapi framework. If it is not provided, a default value will be given. Optional.

Parameters Passed From Business Process to Service

The following table contains the parameters passed from the business process to the XAPI service:

Parameter Description
api The name of the XAPI to be invoked. Required. This is for the name of the API you want to call. The XAPI framework will fail if the xapi is bad. If this parameter is not specified, then this business process must fail and an error message "Required xapi parameter is missing." must be written to the status report. Required.
xml This is the xml content that needs to be passed to the API. If this parameter is not available then input document must be treated as the input XML. If input document is also not available, then this business process must fail and the error message "Missing Data" must be written to the status report. If the input XML is not a well formed Document object, write an error message "Invalid input" to the business process status report and this business process must fail. Required.
split The xpath to split a document to several parts. You can use this parameter to specify several inputs to the API in the xml. You specify the split to get the different inputs. See the example above for how to use it. The resulting outputs of the call will be saved into Document-1, ...., Document-n. Optional.
template Pass on this parameter to the xapi framework if specified. When specified, if the template XML is not a well formed Document object, write an error message "Invalid Template" to the business process status report and this business process must fail. Optional.
Note: Some APIs ignore the template.
UserId Pass on this parameter to the xapi framework. If not provided, a default value will be given. Optional.
ProgId Pass on this parameter to the xapi framework. If it is not provided, a default value will be given. Optional.