Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack
11g Release 1 (11.1.1.7)

Part Number E17364-07
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

16 Constructing the ABCS

This chapter describes how to construct an Application Business Connector Service (ABCS). It lists the prerequisites that are necessary before you set out to construct an ABCS and briefly introduces you to the concepts of SOA composite application. It provides information about constructing an ABCS using AIA Service Constructor and constructing one using Oracle JDeveloper and lists the tasks that a developer should manually complete after creating an ABCS composite using AIA Service Constructor. Regardless of whether the ABCS is developed either using AIA Service Constructor or entirely using JDeveloper, you should review the relevant sections depending upon the capabilities to be implemented in the ABCS.

Note:

Composite Business Processes (CBP) will be deprecated from next release. Oracle advises you to use BPM for modeling human/system interactions.

This chapter includes the following sections:

16.1 Constructing an ABCS

Table 16-1 lists the common tasks for constructing an ABCS and provides links to detailed information:

Table 16-1 Summary of Tasks for Constructing an ABCS

If Refer to

You are implementing the Fire-and-Forget Message Exchange Pattern (MEP)

Section 15.3.2.2, "When to Use the Asynchronous Request Only (Fire-and Forget) MEP"

Section 16.4, "Implementing the Fire-and-Forget MEP"

To implement the MEP in EBS, see Section 14.6, "Implementing the Fire-and-Forget Message Exchange Pattern."

You are implementing the Asynchronous Request Delayed Response MEP

Section 15.3.2.3, "When to Use the Asynchronous Request Delayed Response MEP"

Section 16.5, "Implementing the Asynchronous Request Delayed Response MEP"

To implement the MEP in EBS, see Section 14.8, "Implementing the Asynchronous Request-Delayed Response Message Exchange Pattern."

You are implementing the Synchronous Request - Response MEP

Section 15.3.2.1, "When to Use the Synchronous Request-Response MEP"

Section 16.7, "Implementing Synchronous Request-Response Message Exchange Scenario"

To implement the MEP in EBS, see Section 14.7, "Implementing the Synchronous Request-Response Message Exchange Pattern."

Your ABCS is invoking an Enterprise Business Service (EBS) operation

Chapter 14, "Designing and Developing Enterprise Business Services," for the guidelines for working with operations of an EBS

You need details about transforming a message from one format to another

Chapter 26, "Working with Message Transformations."

You need information about how ABCS can be connected with the participating applications both inbound and outbound

Chapter 24, "Establishing Resource Connectivity."

You must know how clients such as applications and other services can invoke the ABCS you are developing

Section 16.9, "Invoking the ABCS"

You are securing an ABCS

Section 17.5, "Securing the ABCS"

You are enabling ABCS to handle errors and faults

Section 17.2, "Handling Errors and Faults"

You want to allow ABCS to be extended by customers

Section 17.1, "Developing Extensible ABCS"

You need guidelines on Composite Application Validation System (CAVS)-enabling the ABCS

Section 17.4, "Developing ABCS for CAVS Enablement"

You need guidelines on how to annotate the SOA composites to facilitate the harvesting of metadata into Oracle Enterprise Repository and for deployment of the service

Chapter 13, "Annotating Composites."

You want to harvest design-time composites into Oracle Enterprise Repository

Section 5.2, "Harvesting Design-Time Composites into Project Lifecycle Workbench and Oracle Enterprise Repository"

You want to deploy the ABCS you are developing using AIA Installation Driver

Chapter 2, "Building AIA Integration Flows."

Chapter 3, "Working with Project Lifecycle Workbench."

You want to access AIA Configuration Properties from within an ABCS

Section 2.1.3.9, "How to Work with AIAConfigurationProperties.xml in $AIA_HOME/aia_instances/$INSTANCE_NAME/AIAMetaData/config."


16.1.1 Prerequisites

Before you begin constructing an ABCS, ensure that:

  • The relevant AIA Workstation with Oracle AIA Foundation Pack is installed and the development SOA server is up and running.

    Refer to Section 2.1.3, "How to Set Up AIA Workstation."

  • The application entities' schemas (Application Business Message [ABM] schemas) are accessible from Metadata Service (MDS) repository. They should not be part of each ABCS project.

    Refer to Section 2.1.3.4, "Using MDS in AIA."

  • Enterprise Object Library containing Enterprise Business Objects (EBOs) and Enterprise Business Messages (EBMs) are accessible in the MDS Repository. EBOs and EBMs should not be part of each ABCS project.

    Refer to Section 2.1.3.4, "Using MDS in AIA."

  • All the abstract WSDLs of EBS or participating applications should be accessible from the MDS Repository.

    Tip:

    The abstract WSDL of an ABCS that is being developed should be accessed from MDS. The exceptions to this rule are:

    • The EBS references WSDLs that define PartnerLink types

    • Participating applications reference WSDLs that define PartnerLink types

    • The adapter WSDLs that are generated by JDeveloper

    • Abstract WSDLs of the services defined at ABCS extension points

    When AIA Service Constructor is used for constructing ABCS, abstract WSDLs of the ABCS generated by AIA Service Constructor must be pushed into MDS.

    For more information, see Section 2.1.3.4, "Using MDS in AIA."

  • Requester and provider participating applications have been identified.

  • EBOs and EBMs have been identified.

  • Functionality mapping between EBS and participating applications is complete. This mapping should include:

    • Data element spreadsheet mapping between the EBO and participating application messages.

    • Operations mapping between the EBS and participating applications.

  • The style of interaction (MEP: request-response, fire and forget, asynchronous request, and delayed response) is defined.

    See Section 15.3.2, "Choosing the Appropriate MEP."

  • The communication protocols with the participating applications are identified.

    For more information about how an ABCS interacts with participating applications, see Chapter 24, "Establishing Resource Connectivity."

  • Any participating application-specific requirements such as error handling or security have been identified.

16.1.2 ABCS as a Composite Application

AIA services (ABCSs and EBSs) can be developed as a composite application built using SCA building blocks. Four SCA elements apply to these services:

  • Service

    Represents an entry point into the SCA component or a composite.

  • Reference

    Represents a pointer to an external service outside the scope of the given SCA component.

  • Implementation type

    Defines the type of implementation code for a given SCA component that is used for coding the business logic. Example implementation types include BPEL and Mediator.

  • Wire

    Represents the mechanism by which two components can be connected to each other. Usually a reference of one component is connected to a service exposed by another component.

An SCA component may expose one or more services, may use one or more references, may have one or more properties defining some specific characteristics, and may be connected to one or more components using SCA wiring.

The building blocks of SCA can be combined and assembled to create composite applications. A composite application can be thought of as a composition of related SCA components that collectively provide a coarse-grained business function.

16.1.3 How Many Components Must Be Built

A composite application can be thought of as a composition of related SCA components that collectively provide a coarse-grained business function. A composite may contain certain components that might be required only for the internal implementation of the composite and for which interfaces might not be required outside the scope of the composite in context.

Components may exist that can be used just for the internal implementation of the composite and are thus not required to expose services, references, or both.

A requester ABCS composite as shown in Figure 16-1 can be built using a single component that is exposed as service.

The component can use one reference representing an EBS or more references representing the outbound interactions with other applications.

Figure 16-1 Example of a Requester ABCS Composite

The image is described in the surrounding text

Similarly, a Provider ABCS composite as shown in Figure 16-2 can be built using a single component that is exposed as service.

The component can use one or more references representing the outbound interactions with the applications.

Figure 16-2 Example of a Provider ABCS Composite

The image is described in the surrounding text

16.2 Constructing an ABCS Using Service Constructor

AIA Service Constructor is an application that helps jump-start ABCS development by pregenerating AIA artifacts complying with architectural recommendations. It generates artifacts according to the AIA architecture naming recommendations and relieves developers of performing repeatable mundane tasks, making them focus more on value-added business scenario-specific tasks.

For more information about the Service Constructor, see Chapter 4, "Working with Service Constructor."

This section includes the following topics:

16.2.1 How to Create the ABCS in the Service Constructor

See Chapter 4, "Working with Service Constructor."

16.2.2 How to Complete ABCS Development for the AIA Service Constructor

After the ABCS is created in the Service Constructor, the following post-ABCS construction tasks must be performed manually.

Complete the following manual post-ABCS construction tasks:

Tip:

Ensure that the required AOL schemas are available in the MDS on the server.

  1. Move abstract WSDLs of Application Business Service Connector to the MDS.

    Refer to Section 2.1.3.4, "Using MDS in AIA."

  2. Configure the JDeveloper to access the MDS repository.

    Refer to Section 2.1.3.4, "Using MDS in AIA."

To complete ABCS development for the AIA Service Constructor:

  1. Rearrange service invocations, if necessary.

    The AIA Service Constructor generates relevant definitions for all external service invocations in a sequence in the order that you specify while using the wizard. If your ABCS requires that the invocations be done either in parallel or based on certain other conditions, rearrange the services as needed using Oracle BPEL Designer.

  2. Complete the business payload transformation.

    The AIA Service Constructor generates transformations only if the target document is an Enterprise Business Message and generates root element business transformations only. It generates the transformation mapping pertaining to most of the header elements, and the XSL code pertaining to the business payload that is common to all of the ABCSs.

    Use Oracle BPEL Designer to develop the transformation code for transforming remaining parts of the message document to complete the business payload and header transformation.

  3. Configure correlation properties for asynchronous application service invocation.

    The AIA Service Constructor does not generate correlation properties for any application target service that is being invoked using an asynchronous request-response MEP.

    Use Oracle BPEL Designer to configure the correlation upon the invoke activity and subsequent receive activity.

  4. Create invocations for other operations when a service is called multiple times.

    If a service is called multiple times, the AIA Service Constructor does not generate code for multiple invocations. Copy and paste the invocation code generated for the first service invocation from the same process and rename operations and variables.

  5. Populate attributes of binding.ws element of the reference services in the composite.xml file.

    Tip:

    Always use the abstract WSDL to refer to the services that must be invoked. The reference binding component should always use the abstract WSDL.

    Do not use the concrete WSDLs directly in your consuming artifacts.

    Do not reference the deployed concrete WSDL of a Service Provider

    The following paragraphs describe how you can accomplish this.

    For a better understanding of why this is recommended, see Section 30.1.6, "Separation of Concerns."

    In the composite.xml file, under the element <reference>, the AIA Service Constructor generates empty attributes, port, and location for the element <binding.ws>.

    Populate the attributes with relevant values as specified in the following list.

    1. When the referenced service is BPEL-based, the binding.ws element should be populated as shown in Example 16-1.

      Example 16-1 Binding.ws Element for BPEL-Based Service

      <binding.ws port="[Namespace of the Service as defined in the 
      wsdl]#wsdl.endpoint([Name of the Service as given in the WSDL]/[ Name of the 
      Porttype as given in the WSDL>)"  location="< URL of the concrete WSDL]"/>
      

      Tip:

      The name of the Service is the value of the attribute definitions/name in the abstract WSDL.

      This follows from naming conventions for the Service name in the ABCS Composite. The name of the service is <name of the composite>, which in turn is the value of the attribute 'name', of the element 'definitions', in the WSDL.

      The URL of the concrete WSDL uses this format as shown in Example 16-2:

      Note:

      Populating the 'location' attribute of the element binding.ws with the URL of a run-time WSDL, does not amount to violating the principle of 'designing the service using only abstract WSDLs'. The reason is that this concrete WSDL is not accessed either at composite's design-time or at composite's deploy-time. This WSDL is only accessed at composite's runtime.

      http://{host}:{port}/soa-infra/services/default)/[Name of the Service as given in the attribute 'name' of the element 'definition' in the WSDL]/[Name of the Porttype element as given in the WSDL]?WSDL

      Example 16-2 URL of the Concrete WSDL for BPEL-Based Service

      <binding.ws 
      port="http://xmlns.oracle.com/SamplePortalApp#wsdl.endpoint(SamplesCreateCustomer
      PartyPortalProvider/SamplesCreateCustomerPartyPortalProvider)" location="http:// 
      {host}:{port}/soa-infra/services/default/SamplesCreateCustomerPartyPortalProvider
      /SamplesCreateCustomerPartyPortalProvider?WSDL"/>
      
    2. When the referenced service is mediator-based, then the binding.ws element should be populated as shown in Example 16-3.

      Example 16-3 Binding.ws Element for Mediator-Based Service

      <binding.ws port="[Namespace of the Service as defined in the 
      wsdl]#wsdl.endpoint([Name of the Porttype element  as given in the WSDL]_ep/[ 
      Name of the Porttype element as given in the WSDL]_pt)" location="[ URL of the 
      concrete WSDL]"/>
      

      The URL of the concrete WSDL uses this format as shown in Example 16-4:

      http://{host}:{port}/soa-infra/services/default)/[Name of the Porttype element as given in the WSDL]/[Name of the Porttype element as given in the WSDL]_ep?WSDL

      Example 16-4 URL of the Concrete WSDL for Mediator-Based Service

      <binding.ws 
      port="http://xmlns.oracle.com/EnterpriseServices/Core/CustomerParty/V2#wsdl.endpo
      int(SamplesCustomerPartyEBS_ep/CustomerPartyEBS_pt)" location="http:// 
      {host}:{port}/soa-infra/services/default/SamplesCustomerPartyEBS/SamplesCustomerP
      artyEBS_ep?WSDL"/>
      

      TroubleshootingTip:

      You may see error messages indicating invalid SOA composites after a server restart. This is caused by referring to concrete WSDLs where abstract WSDLs should have been used.

      You will not see the problem at the first deployment of a new composite X when you reference the concrete WSDL of composite Y. Why? Composite Y is up and running at the time of the deployment of composite X. The problem starts when the server is restarted because there is no guarantee that the composites will be activated in the right order to resolve any dependencies. If service X is activated before composite Y, the reference cannot be resolved because Y is still down, so X remains in status Invalid.

  6. Alter policies in the fault policy.

    The AIA Service Constructor generates fault policies with default values. Modify these default values based on the service's requirements.

    For details about setting up fault policies for AIA services, refer to Chapter 27, "Configuring Oracle AIA Processes for Error Handling and Trace Logging."

  7. Alter properties in the service configuration properties file.

    The AIA Service Constructor generates a configuration file snippet for service-specific properties. In case of the service configuration file of a provider ABCS, you must enter the value for the property Routing. <PartnerLinkName>.< Target System ID>>.EndpointURI as shown in Example 16-5.

    Example 16-5 Service Configuration Properties File

    <Property name="Routing. PartnerLinkName>.< Target System ID>.EndpointURI 
    ">http://[hostname]:[portnum]/soa-infra/services/default/[name of the 
    service]/[name of the exposed endpoint of the service]?WSDL</Property>
    

    Example 16-6 is a sample of a completed service configuration properties file.

    Example 16-6 Example of Configuration File for Service-Specific Properties

    <Property 
    name="Routing.SamplesCreateCustomerPartyPortalProvider.SamplePortal.EndpointURI">
    http:// 
    {host}:{port}/soa-infra/services/default/SamplesCreateCustomerPartyPortalProvider
    /SamplesCreateCustomerPartyPortalProvider?WSDL</Property>
    

    Note:

    You must provide the preceding property in the service configuration file if the value for the property Routing.<PartnerLink>.RouteToCAVS is given as false.

  8. Change the componenttype file and composite.xml as detailed in the following sections.

    You must make changes to these files to make them point to the abstract WSDLs in the MDS.

Changes Needed in the componenttype File

The attribute ui:wsdlLocation in Service element should point to abstract WSDLs in the MDS as shown in Example 16-7.

Example 16-7 Componenttype File Pointing to Abstract WSDLs in the MDS

<service 
ui:wsdlLocation="oramds:/apps/AIAMetaData/AIAComponents/ApplicationConnectorServ
iceLibrary/SampleSEBL/RequesterABCS/SamplesCreateCustomerSiebelReqABCSImpl.wsdl"
 name="SamplesCreateCustomerSiebelReqABCSImpl">

If the composite has a reference, then the attribute ui:wsdlLocation in reference element should point to abstract WSDLs in the MDS as shown in Example 16-8:

Example 16-8 Componenttype File for a Composite with a Reference

<reference name="SamplesCreateCustomerPartyPortalProvider"
ui:wsdlLocation="oramds:/apps/AIAMetaData/AIAComponents/ApplicationConnectorServ
iceLibrary/SamplePortal/V1/SamplesCreateCustomerPartyPortalProvider.wsdl">
<interface.wsdl 
interface="http://xmlns.oracle.com/SamplePortalApp#wsdl.interface(SamplesCreateC
ustomerPartyPortalProvider? )"/>
</reference>

Changes Needed in the composite.xml File

In the composite.xml, the attribute location of the element import should point to abstract WSDLs in the MDS as shown in Example 16-9.

Example 16-9 Composite.xml Pointing to Abstract WSDLs in the MDS

<import 
location="oramds:/apps/AIAMetaData/AIAComponents/ApplicationConnectorServiceLibr
ary/SampleSEBL/RequesterABCS/SamplesCreateCustomerSiebelReqABCSImpl.wsdl" 
namespace= 
"http://xmlns.oracle.com/ABCSImpl/Siebel/Samples/CreateCustomerSiebelReqABCSImpl
/V1"/>

The attribute ui:wsdlLocation in Service and Reference elements should point to abstract WSDLs in the MDS as shown in Example 16-10.

Example 16-10 Example of composite.xml Pointing to Abstract WSDLs in the MDS

<service 
ui:wsdlLocation="oramds:/apps/AIAMetaData/AIAComponents/AIAServiceLibrary/Sample
SEBL/RequesterABCS/SamplesCreateCustomerSiebelReqABCSImpl.wsdl" 
name="SamplesCreateCustomerSiebelReqABCSImpl">

For those referenced services in which the WSDLs do not have partnerLinkType elements in them, their corresponding reference WSDLs should also be changed to refer the abstract WSDLs from the MDS.

For instance, the composite of a requester ABCS has a mediator as a referenced service. Hence, change the location attribute of the element 'import' in the <EBS Reference WSDL> file as shown in Example 16-11.

Example 16-11 Referenced Service WSDLs with No partnerLinkType Elements Pointing to Abstract WSDLs in the MDS

<wsdl:import 
namespace="http://xmlns.oracle.com/EnterpriseServices/Core/CustomerParty/V2" 
location="oramds:/apps/AIAMetaData/AIAComponents/EnterpriseBusinessServiceLibr
ary/Core/EBO/CustomerParty/V2/CustomerPartyEBS.wsdl"/>

16.3 Constructing an ABCS Composite Using JDeveloper

An ABCS can be constructed using either AIA Service Constructor or JDeveloper.

While the previous section dealt with constructing an ABCS using Service Constructor, this section provides a high-level overview of constructing the ABCS composite in design mode, using JDeveloper.

The high-level tasks to be performed are:

16.3.1 How to Construct the ABCS Composite Using JDeveloper

To create an ABCS using JDeveloper:

  1. In JDeveloper, create an SOA composite project.

  2. Open the composite.xml in design mode.

  3. Add a BPEL component in the Components swim lane.

  4. Add a web service as external reference service in the References swim lane.

    This reference service could represent an EBS, an Adapter Service, or a participating application. An abstract WSDL of the EBS, Adapter Service, or participating application should be accessible from the MDS Repository.

    Note: In the composite.xml, populate the element 'binding.ws' as shown in step 5 of Section 16.2.2, "How to Complete ABCS Development for the AIA Service Constructor."

  5. Wire the BPEL component to the external reference component created in step 4.

  6. Complete the following for handling the faults.

    • Add a web service as external reference service in the References swim lane. Provide the reference to the abstract WSDL of the AIAAsyncErrorHandlingBPELProcess in the MDS repository.

    • Wire the BPEL component to the AIAAsyncErrorHandlingBPELProcess service.

    For more information about fault handling in AIA services, see Chapter 27, "Configuring Oracle AIA Processes for Error Handling and Trace Logging."

Figure 16-3 illustrates a requester ABCS composite.

Figure 16-3 Example of a Requester ABCS Composite

The image is described in the surrounding text

16.3.2 Developing the BPEL Process

After you have developed the composite in design mode using JDeveloper, the ABCS that is implemented as a BPEL process component should be constructed to its completion.

In the ABCS, the following tasks are accomplished:

  • Message enrichment

  • Message header population

  • Message content transformation

  • Error handling and logging

  • Extensibility

  • CAVS enablement

  • Security context implementation

For more information about completing ABCS development, see Chapter 17, "Completing ABCS Development."

16.3.3 How to Create References, Services, and Components

  • For each target, add a reference.

    • The target can be a web service or adapter.

    • If the target service requires transformation, create a mediator component in between.

  • For each interface, add a service.

    • The service can be a web service or adapter.

    • If the adapter interface requires transformation, create a mediator component in between.

16.3.4 Moving Abstract Service WSDLs in MDS

SOA Suite 11g has introduced a central repository, Metadata Service (MDS), that backs up your application (and hence your composites) at design time and runtime. MDS is like a version management system, where you can store and use the shared common artifacts at design and runtime.

AIA leverages the MDS repository to store common design time artifacts that are shared with all developers. There is a common directory of abstract WSDLs in the MDS, which is a centrally accessible endpoint.

The artifacts that are stored in the MDS include:

  • Schemas: EBO schemas and ABM schemas

  • WSDLs: Abstract WSDLs of EBS, ABCS, Adapter Services, CBPs and EBFs

All the abstract WSDLs of all AIA services are put in MDS. You build your consuming AIA service composite application using the abstract WSDL of a referenced service. No dependency exists on the order of deployment for composites.

Since there is no dependency on the referenced services during the deployment of the composites, there is no dependency on the order of deployment for the composites. A referenced service does not have to be deployed to be referenced by another service. This also resolves the cases where there are cyclic references involved among the services.

Tip:

Always use the abstract WSDL to refer to the services that must be invoked. The reference binding component should always use the abstract WSDL.

Do not use the concrete WSDLs directly in your consuming artifacts.

Do not reference the deployed concrete WSDL of a Service Provider

The following paragraphs describe how this can be accomplished.

To get a better understanding of why this is recommended, see Section 30.1.6, "Separation of Concerns."

For details of how MDS is used in AIA, refer to Section 2.1.3.4, "Using MDS in AIA."

Tip:

Abstract WSDLs must be modified to access the required schemas from the MDS and then moved to MDS.

Troubleshooting Tip:

You may see error messages indicating invalid SOA composites after a server restart. This is caused by referring to concrete WSDLs where abstract WSDLs should have been used.

You will not see the problem at the first deployment of a new composite X when you reference the concrete WSDL of composite Y. Why? Composite Y is up and running at the time of the deployment of composite X. The problem starts when the server is restarted because there is no guarantee that the composites will be activated in the right order to resolve any dependencies. If service X is activated before composite Y, the reference cannot be resolved because Y is still down, so X remains in status Invalid.

For ABCSs and Adapter services, the abstract WSDLs are to be located in MDS at:

AIAMetaData/AIAComponents/ApplicationConnectorServiceLibrary/<PRODUCT_CODE>/<Version Number>/<Service Type>

Possible values for <Service Type> are RequesterABCS, ProviderABCS, AdapterServices.

Possible values for <Version Number> are V1, V2.

The utility for moving artifacts to MDS is described in Section 2.1.3.4, "Using MDS in AIA."

Examples:

AIAMetaData/AIAComponents/ApplicationConnectorServiceLibrary/Siebel/V1/RequesterABCS
AIAMetaData/AIAComponents/ApplicationConnectorServiceLibrary/Siebel/V1/ProviderABCS

16.4 Implementing the Fire-and-Forget MEP

If you are implementing the fire-and-forget MEP, this section provides the necessary guidelines.

For more information about the scenarios for which this MEP is recommended, see Section 15.3.2.2, "When to Use the Asynchronous Request Only (Fire-and Forget) MEP."

In the fire-and-forget pattern, no response is sent back to the requester. In situations in which the provider ABCS is not able to successfully complete the task, transactions should be rolled back and error notifications should be sent.

For more information on how to model transactions, see Chapter 26, "Working with Message Transformations."

For more information about how to handle faults, see Chapter 27, "Configuring Oracle AIA Processes for Error Handling and Trace Logging."

In scenarios where the RequesterABCS is invoked by a JMS-based transport adapter, the JMS destination can be thought of as a milestone. In these circumstances, it is possible to configure the JMS consumer adapter and the requester ABCS for the automatic message resubmission of the failed messages.

For more information about message resubmission, see "Using the Message Resubmission Utility" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

This section includes the following topics:

16.4.1 When to Use Compensating Services

Sometimes an automatic correction of data or a reversal of what has been done in requester service is needed. The typical scenario is one in which an error occurs in the transaction and the transactions cannot be rolled back.

In these situations, the requester application can implement the compensation service operation and pass the name of the service operation to the provider ABCS. The provider ABCS invokes this compensation service operation if there are errors. There may be a requirement to implement a compensating service for the requesting service.

16.4.2 How to Invoke the Compensating Service

To invoke the correct compensating service from the providing service:

  1. Populate the EBMHeader/Sender/WSAddress/wsa:FaultTo/wsa:ServiceName with the name of the compensating service in the transformation used for constructing the request EBM.

    Example of the name of the compensation service: CompensateCreateOrderSiebelReqABCSImpl

    For more information about naming, see Chapter 32, "Oracle AIA Naming Standards for AIA Development."

    Figure 16-4 illustrates the structure of the WSAddressType.

Figure 16-4 Structure of the WSAddressType

The image is described in the surrounding text

This information is used in the compensate operation of the EBS to route the request for compensation to the correct compensating service.

16.4.3 Additional Tasks Required in Provider ABCS to Implement This MEP

For information about implementing this MEP, see Section 16.6, "Implementing Provider ABCS in an Asynchronous Message Exchange Scenario."

16.4.4 How to Ensure Transactions

For information about ensuring transactions, see Section 17.6.1, "How to Ensure Transactions in AIA Services."

16.4.5 How to Handle Errors

For information about error handling, see Chapter 27, "Configuring Oracle AIA Processes for Error Handling and Trace Logging."

16.5 Implementing the Asynchronous Request Delayed Response MEP

If you are implementing an asynchronous request-delayed response MEP, this section provides the necessary guidelines.

For more information about the scenarios for which this MEP is recommended, see Section 15.3.2.3, "When to Use the Asynchronous Request Delayed Response MEP."

This section discusses how to implement the asynchronous request-delayed response MEP.

Implementing this MEP requires that:

This section includes the following topics:

16.5.1 How to Populate the EBM Header for Asynchronous-Delayed Response

To populate the EBM header for asynchronous delayed response:

  1. Populate the EBMID.

    This is used for correlation of the response to the correct requesting service instance.

    Figure 16-5 illustrates the structure of the CreateSalesOrderEBMType.

    Figure 16-5 Structure of the CreateSalesOrderEBMType

    The image is described in the surrounding text
  2. Set the EBMHeader/Sender/WSAddress/wsa:ReplyTo/wsa:ServiceName to the name of the requesting service name in ABM to EBM transformation as shown in Figure 16-6.

    This is the name of the service that must be invoked by the EBS for processing the response message. In most of the situations, it is the same requester ABCS that is also be responsible for processing the response message coming from provider ABCS.

    Figure 16-6 Structure of the SWSAddressType

    The image is described in the surrounding text

    This information is used in the response operation of the EBS to route the response from the providing service to the correct requesting service.

  3. Set the responseCode attribute of the EBM verb.

    The responseCode attribute of the EBM verb is set to indicate to the providing service that the requesting service is expecting a response. This is evaluated in the providing service to send back a response.

  4. Set correlation information in the requesting service partner link.

    The delayed response from the providing service routed by a response EBS would be received by a Receive activity. After the Invoke step is performed in the requesting service and the process moves to the Receive step, the BPEL process instance is suspended and dehydrated. This restarts after the response is received. To facilitate this behavior, a correlation set has to be specified on the partnerLink for the Receive.

    The requester ABCS process should look like the example in Figure 16-7. This is the process for which you must set the correlation IDs.

    Figure 16-7 Example of Requester ABCS Process

    The image is described in the surrounding text

16.5.2 Setting Correlation for the Asynchronous Request-Delayed Response MEP

In the process described in Section 16.5.1 you must set the correlation in two places:

  • Correlation Set

    Add a correlation ID and create a correlation set for the Invoke activity where the process would go into the dehydration store

    Add a correlation ID and create a correlation set for the Receive activity where the process would be recalled from the dehydration store after getting a delayed response from the provider/edge application.

  • Correlation Property

    Add a standard name-value pair for each partnerLink that is linked to the Invoke or Receive activities where the correlation sets are defined as mentioned previously. The property should always be defined as correlation = correlationSet.

16.5.3 Programming Models for Handling Error Response in the Asynchronous Request-Delayed Response MEP

This section discusses programming models for:

  • Using a separate service for error handling

  • Using JMS queue as milestone between RequesterABCS and the EBS

  • Using a parallel routing rule in the EBS

16.5.3.1 Programming Model 1: Using a Separate Service for Error Handling

In this model, when a message is successfully processed, the response is sent back to the same requester that initiated the process. However, when the message errors out during the processing in the ProviderABCS, it is routed to a separate error handler service using ResponseEBS.

An inbound message reaching the Requester ABCS is passed to the EBS which invokes the Provider ABCS, for the message processing.

After the message is processed, the Provider ABCS pushes the message into a JMS Queue.

If an error occurring during the processing of the message, an error response message should be constructed and the EBM response header should indicate that the response is indeed an error message.

In a successful scenario, the response EBS routes the response message to the initiating requesterABS.

In a failure scenario, the response EBS should route the message to an error handler service.

Note:

Publish the messages to JMS Queue from Provider ABCS in both Success and Error scenarios, if the Provider ABCS is required to send the response or the error message.

This model has two transactions as shown in Figure 16-8.

Transaction 1 starts with de-queuing message by the requesterABCS or the external application directly calling the RequesterABCS. This transaction ends when the provider ABCS publishes either the reply or error message, as the case may be, to the JMS Queue.

Figure 16-8 Programming Model 1: Using a Separate Service for Error Handling

The image is described in the surrounding text

16.5.3.2 Programming Model 2: Using JMS Queue as a Milestone Between Requester ABCS and the EBS

In this model, shown in Figure 16-9, the requester ABCS publishes the inbound message to a JMS milestone. The transaction starts with de-queueing of the message by the requester ABCS or the external application directly calling the requester ABCS. The transaction ends with requester ABCS publishing the message to the JMS queue.

A second transaction starts with de-queueing the message from the JMS queue and invoking EBS. The EBS routes the inbound message to the ProviderABCS for the processing.

In the case of a successful message processing, the provider ABCS invokes the response EBS, using a native binding call, in the existing transaction.

If an error occurs during the message processing, the provider ABCS publishes the errored-out message into another JMS queue. The response EBS picks up the message and invokes the fault handler service

Figure 16-9 Programming Model 2: Using JMS Queue as a Milestone Between Requester ABCS and the EBS

The image is described in the surrounding text

Tip:

Use this Queue in the Provider ABCS Reference component ONLY for an Error scenario.

16.5.3.3 Programming Model 3: Using a Parallel Routing Rule in the EBS

An inbound message reaching the Requester ABCS is passed to the EBS. The EBS routes the message to the Provider ABCS for the message processing, using a parallel routing rule. The transaction starts with de-queuing of the message by the requester ABCS or the external application directly calling the requester ABCS. The transaction ends when the EBS persists the inbound message for a queued execution.

Figure 16-10 illustrates this programming model.

A second transaction starts with de-queuing message from EBS. In case of a successful message processing, provider ABCS making a native binding call to the response EBS in the existing transaction. The response EBS routes the response to the requester ABCS by invoking another receive activity. In case of errors, the Provider ABCS makes a web service call to invoke the Response EBS thereby causing a new transaction to start. In this transaction, the Response EBS is responsible for sending the error message back to the application using either Requester ABCS or directly.

Figure 16-10 Programming Model 3: Using a Parallel Routing Rule in the EBS

The image is described in the surrounding text

16.5.4 What Tasks Are Required in Provider ABCS to Implement This MEP

For details about the tasks see Section 16.6, "Implementing Provider ABCS in an Asynchronous Message Exchange Scenario."

16.6 Implementing Provider ABCS in an Asynchronous Message Exchange Scenario

If you are implementing asynchronous MEP in the provider ABCS, this section provides the necessary guidelines.

For more information about the scenarios for which this MEP is recommended, see Section 15.3.2.3, "When to Use the Asynchronous Request Delayed Response MEP."

The provider ABCS is implemented to either behave as a one-way service call pattern or request-delayed response pattern.

In the request-delayed response pattern, the provider ABCS receives the request message from the EBS request routing service, processes the message, and finally responds to the requesting service (requester ABCS or Enterprise Business Flow [EBF]) by invoking the response operation of the EBS response routing service. In some scenarios, the provider ABCS can also publish the response and/or the error message to a JMS queue. The EBS request routing service is not waiting for the response.

See Section 16.5.3.1, "Programming Model 1: Using a Separate Service for Error Handling."

All the provider ABCSs (and EBFs) should have the capability to invoke the callback operation, but should have a switch case to do it only if the requester wants a callback. Evaluate the responseCode attribute on the verb element of the EBM to determine whether the requesting service is expecting a response.

16.6.1 How to Implement the Asynchronous MEP

To implement the asynchronous MEP in the provider ABCS:

  1. Populate the EBM header of the request message in the providing service with fault information.

    If an error occurs in the provider service before evaluation of the requirement of a response and an exception is issued, enter the fault information in the request message EBM header. This facilitates passing the entire request EBM along with the fault message to the catch block for processing.

  2. Implement Error Handling in the providing service.

    If a particular error needs compensation service to be invoked, then the compensate operation of the EBS is invoked for routing the request to the compensation service.

    For more information, see Chapter 27, "Configuring Oracle AIA Processes for Error Handling and Trace Logging."

  3. Enter the correlation information in the EBM header in the providing service.

    Use the EBMID in the EBM header for correlation of the response message to the correct requesting service instance. To facilitate correlation, the EBMID in the EBM header of the request message must be copied to the RequestEBMID in the EBM header of the response message in the ABM to EBM transformation of the providing service as shown in Figure 16-11.

    Figure 16-11 Structure of CreateSalesOrderResponseEBMType Element

    The image is described in the surrounding text

    For information about the technique of passing the EBMHeader of the request message in a variable into the ABM to EBM XSLT, see Chapter 26, "Working with Message Transformations."

    This is required to copy the relevant information from the EBM header of the Request EBM to the EBM header of the Response EBM.

  4. Populate the EBM header of response message in the providing service with fault information.

    If an error occurs in the provider service after evaluation of the requirement of a response, you must populate the fault information in the response message EBM header fault component. This facilitates passing the response EBM along with fault message to the catch block for processing.

    The requesting service receives a response with fault elements populated.

16.6.2 Using the Programming Models for the Request-Delayed Response Pattern

If you use the programming models found in Section 16.5.3, "Programming Models for Handling Error Response in the Asynchronous Request-Delayed Response MEP" for the request-delayed response pattern, follow these guidelines.

Programming Model 1: Using a Separate Service for Error Handling

The provider ABCS should publish the messages to JMS Queue in both successful message processing and error scenarios, if the provider ABCS is required to send the response or the error message.

Note:

A new transaction is started with de-queuing of the message from JMS.

Programming Model 2: Using JMS Queue as a Milestone Between the Requester ABCS and the EBS

In the case of successful message processing, the provider ABCS invokes the response EBS, using a native binding call, in the existing transaction.

If an error occurs during the message processing, the provider ABCS publishes the errored-out message into another JMS queue. The response EBS picks up the message and invokes the fault handler service

Programming Model 3: Using a Parallel Routing Rule in the EBS

The provider ABCS has two references to the response EBS composite. Follow the naming conventions to name the provider ABCS 's second reference to the EBS.

For details on naming conventions, see Chapter 32, "Oracle AIA Naming Standards for AIA Development."

Figure 16-12 illustrates the asynchronous provider ABCS composite with a second reference to the ResponseEBS. The label for the second reference is <EBSName>ErrorResponseEBS.

Figure 16-12 Async Provider ABCS Composite with a Second Reference to ResponseEBS

The image is described in the surrounding text

When the message is processed successfully, the provider ABCS invokes the callback operation on the response EBS. The response EBS routes the response to the requester ABCS by invoking another receive activity. When en error occurs during the processing of the message, the provider ABCS invokes the response EBS through its second reference to the response EBS. In this case, the responseEBS is invoked using a SOAP call, not a native call. This is achieved by having the following property set on the second reference to the response EBS, in the composite of the provider ABCS.

<binding.ws port="<port>" location="<url>"/>
      <property name="oracle.webservices.local.optimization type="xs:boolean">false</property>
  </binding.ws>

Note:

Use this property in the provider ABCS reference component ONLY for the error scenario.

16.6.3 How to Ensure Transactions in Services

For more information about ensuring transactions, see Section 17.6.1, "How to Ensure Transactions in AIA Services."

16.6.4 How to Handle Errors in the Asynchronous Request-Delayed Response MEP

See Chapter 27, "Configuring Oracle AIA Processes for Error Handling and Trace Logging."

16.7 Implementing Synchronous Request-Response Message Exchange Scenario

If you are implementing synchronous request-response MEP, this section provides the necessary guidelines.

For more information about the scenarios for which this MEP is recommended, see Section 15.3.2.1, "When to Use the Synchronous Request-Response MEP."

In this scenario, requester ABCS synchronously invokes the EBS. The EBS invokes the Provider ABCS and waits for a response. Synchronicity should manifest in the WSDLs of requester ABCS, EBS, and provider ABCS. All of the WSDLs should have the operation defined with input and output message.

16.7.1 How to Ensure Transactions in Services

This MEP need not support transactions. No break points such as midprocess Receive, wait, Pick, onMessage activities should be in any of the BPEL processes participating in implementation of this MEP.

For more information about ensuring transactions, see Section 17.6.1, "How to Ensure Transactions in AIA Services."

16.7.2 How to Handle Errors in the Synchronous Request-Response MEP

See Chapter 27, "Configuring Oracle AIA Processes for Error Handling and Trace Logging."

16.7.3 How to Optimize the Services to Improve Response Time

Because this MEP involves implementation of transient services (no break point activities and hence, no dehydration in the middle), Oracle AIA highly recommends that the audit details for BPEL services are persisted only for faulted instances. The service instances associated with the successfully completed integration flows are not visible using Oracle Enterprise Manager. This approach significantly improves the response time.

auditLevel property sets the audit trail logging level. This configuration property is applicable to both durable and transient processes. This property controls the amount of audit events that are logged by a process. Audit events result in more database inserts into the audit_level and audit_details tables, which may impact performance. Audit information is used only for viewing the state of the process from Oracle Enterprise Manager Console. Use the Off value if you do not want to store any audit information. Always choose the audit level according to your business requirements and use cases.

For synchronous BPEL processes, AIA recommends nonpersistence of instance details for successfully completed instances. For this, set the auditLevel property to off at the service component level. This general guideline could be overridden for individual services based on use cases.

16.8 Invoking Enterprise Business Services

This section discusses the guidelines for invoking an EBS from an ABCS and for working with operations of an EBS. This content is provided from the perspective of invoking an EBS operation and also helps in understanding EBS operations from an implementation perspective.

This section includes the following topics:

These sections present a detailed view of each of the verbs in the context of:

16.8.1 Create

The Create verb indicates a request to create a business object using the information provided in the payload of the Create message. It is used in operations that are intended to create an instance of a business object.

When to Use the Create Verb

If both the service requester and service provider have the same object, then Sync would be a more appropriate verb to use. However, the usage of Sync is conditional on the service provider having an implementation of a Sync operation.

A typical use of a Create operation is a front-end customer management system that could take service requests from customers and based on the information provided, request a work order system to create a work order for servicing the customer.

The Create verb is not used for composite operations; it always involves the creation of one (or more for List) instance of a business object.

Content Payload

The payload of an operation that uses a Create verb is typically a complete business object, and in general every business object has only two messages with a Create operation (Single and List).

Verb Attributes

The Create verb has an optional ResponseCode attribute that communicates the payload that is expected in the response message to the Create request. The possible values for the ResponseCode are restricted to either ID (response payload is expected to be the Identifier of the object that was created) or OBJECT (response payload is expected to be the entire object that was created).

Corresponding Response Verb

The Create verb has a paired CreateResponse verb that is used in the response message for each Create EBM. The response is expected to be provided by the target application only if the original request message explicitly requests a response by setting the ResponseCode attribute in the Create message.

Response Content Payload

The payload type of the response verb is always based on the payload type of the Create Request operation. It is implemented as a different type to support user customization if needed.

16.8.2 Update

The Update verb indicates a request to a service provider to update an object using the payload provided in the Update message. It is used in operations that are intended for updating one or more properties of a business object or array of business objects.

Operations that use the Update verb must create or update content and should not be an orchestration of other operations.

When to Use the Update Verb

Similar to Create, a business process invokes an Update operation mainly in cases in which the source event that triggers the invocation is not the updating of the object in the requesting system. If both the service requester and service provider have the same object, then Sync would be a more appropriate verb to use. However, use of Sync would be conditional to the service provider having an implementation of a Sync operation.

An example of an Update operation is a receiving system updating a purchase order line with the quantity of items received, or an order capture system updating the customer record with customer address and other information.

The content included in the business payload of an EBM using the Update verb is assumed to be only the fields that must be updated in the target application. The Update verb uses the ActionCode property of the business components and common components to communicate processing instructions to the target system. This is necessary for hierarchical, multilevel objects when the update happens at a child level.

The ActionCode property exists in an EBO for all components that have a multiple cardinality relationship with its parent. The possible values for the ActionCode are Create, Update, and Delete. It is intended for use only with the Update verb to communicate the processing action to be applied to that business component. Ensure that the ActionCode applies only if the object has child business components-if not, an ActionCode is not needed and the verb alone is sufficient to convey this information.

A use case for ActionCode is a case in which a requisition is updated in a self-service requisitioning system, and this updated information must be communicated to the Purchasing system, which also maintains a copy of the requisition.

Assume that a user updates a requisition and does the following actions (in a single transaction):

  • Updates the description in the requisition header

  • Adds a new requisition line (line number 4)

  • Modifies the item on a requisition line (line number 3)

  • Deletes a requisition line (line 2)

  • Modifies the accounting distribution of a requisition line, and adds a new accounting distribution (line 1)

The content of the DataArea business payload in the instance XML document that communicates the preceding changes is shown in Example 16-12.

Example 16-12 DataArea Business Payload in the Instance XML Document

<UpdateRequisition actionCode="Update">   Root Action Code not processed
    <Description>New Description</Description>
   <RequisitionLine actionCode="Update"> Indicates that some property or 
association of this line is being updated. In this example, the accounting 
distribution Percentage has been updated for Line 1, and a new 
AccountingDistribution line has been added  
         <Identification>
               <ID>1</ID>
         </Identification>
         < RequisitionAccountingDistribution actionCode="UPDATE">
               <Identification>
                     <ID>1</ID>
               </Identification>
               <AccountingDistribution>
                     <Percentage>15</Percentage>
               </AccountingDistribution>
         < /RequisitionAccountingDistribution>
         < RequisitionAccountingDistribution actionCode="ADD">
               <Identification>
                     <ID>3</ID>
               </Identification>
               <AccountingDistribution>
                     <Percentage>15</Percentage>
               </AccountingDistribution>
         < /RequisitionAccountingDistribution>
   </RequisitionLine>
   <RequisitionLine actionCode="DELETE"> Indicates this line has been deleted
         <Identification>
               <ID>2</ID>
         </Identification>
   </RequisitionLine>
   <RequisitionLine actionCode="UPDATE">
         <Identification>
               <ID>3</ID>
         </Identification>
<ItemReference>
<Identification>
                     <ID>1001</ID>
               </Identification>
</ItemReference>
   </RequisitionLine>
   </RequisitionLine>
   <RequisitionLine actionCode="ADD"> Indicates this line has been added
         <Identification>
               <ID>4</ID>
         </Identification>
<ItemReference>
<Identification>
                     <ID>1005</ID>
               </Identification>
</ItemReference>
   </RequisitionLine>
</UpdateRequisition>

Content Payload

The payload of an operation that uses an Update verb is typically the entire EBO and in general every business object has only two messages with an Update operation (single and list).

Situations may occur in which subsets of an EBO must be updated, in which case multiple update messages may possibly exist, each with a distinct payload. An example is a possible UpdateSalesOrderLineEBM message with a payload that contains only SalesOrderLine.

Verb Attributes

The Update verb has an optional ResponseCode attribute that is intended to communicate the payload that is expected in the response message to the Update request. The possible values for the ResponseCode are restricted to either ID (response payload is expected to be the Identifier of the object that was created) or OBJECT (response payload is expected to be the entire object that was created).

Corresponding Response Verb

The Update verb has a paired UpdateResponse verb that is used in the response message for each Update EBM. The response is expected to be provided by the target application only if the original request message explicitly requests a response by setting the ResponseCode attribute in the Update message. The payload of the response is either the ID or the entire object that was updated, depending on the ResponseCode specified in the Update request.

Response Content Payload

The payload type of the response verb is always based on the payload type of the Update Request operation. It is implemented as a different type to support user customization if needed.

16.8.3 Delete

The Delete verb is a request to a service provider to delete the business object identified using the object Identification provided in the payload of the Delete message.

When to Use the Delete Verb

The Delete verb is used for operations that are intended to delete a business object.

Operations that use the Delete verb must delete content and should not be an orchestration of other operations.

Note:

Currently, AIA does not support using Delete for components of a business object, that is, Delete Purchase Order Line is allowed

Content Payload

The payload of the Delete verb must be only an identification element that uniquely identifies the business object to be deleted.

Verb Attributes

The Delete verb has an optional ResponseCode attribute that is intended to communicate the payload that is expected in the response message to the Update request. The only possible value for the ResponseCode for Delete is ID (response payload is expected to be the Identifier of the object that was created).

Corresponding Response Verb

The Delete verb has a paired DeleteResponse verb that is used in the response message for each Delete EBM. The Response is expected to be provided by the target application only if the original request message explicitly requests a response by setting the ResponseCode attribute in the Delete message. The only allowed value for the ResponseCode is ID.

16.8.4 Sync

The Sync verb indicates a request to a service provider to synchronize information about an object using the payload provided in the Sync message.

When to Use the Sync Verb

The Sync verb is used in situations in which applications provide operations that can accept the payload of the operation and create or update business objects as necessary.

Operations that use the Sync verb must create or update content and should not be an orchestration of other operations.

The primary usage scenario for Sync is generally batch transactions in which the current state of an object is known, but what has changed between the previous sync and the current sync is not known. Sync can also be used to synchronize individual instances of objects. The initiator of Sync is generally the system that owns the data to be synchronized.

Using the Sync operation implies that the object exists in both the source and the target system, and the result of Sync is that both the source and target have the same content. Sync is different from the other verbs in that it assumes a dual processing instruction-Sync can both create and update existing content.

The content of the Sync reflects the current state of the object in the system generating the message. In this mode, a single Sync message can contain multiple instances of nouns, with none of them having any specific change indicator. The source system generates the message, and all systems that subscribe to the message are expected to synchronize their data to reflect the message content.

Sync is probably the most practical approach for master data management scenarios in which change is not frequent, and it may not be practical or necessary from an operational point of view to synchronize data on a real-time basis.

The Sync verb has an optional syncActionCode attribute that can be used to further instruct the recipient of a Sync message about the expected processing behavior. The possible values for the syncActionCode are:

  • CREATE_REPLACE:

    This is the default behavior of Sync when no syncActionCode is specified. The target system that receives a Sync message with no syncActionCode attribute, or with a syncActionCode attribute value of NULL or CREATE_REPLACE, is expected to create the object if it does not exist in the target system, or if it does exist, the entire object is to be replaced with the definition that has been provided in the Sync message.

  • CREATE_UPDATE:

    A Sync message with the value of syncActionCode as CREATE_UPDATE is expected to be processed as follows: create the object if it does not exist in the target system, or if it does exist, update the object with the content that has been provided in the Sync message.

Content Payload

Generally speaking, there is only one Sync message per EBO (with a single and list implementation) and the payload of the message is the entire EBO.

Sync should always be used to synchronize the entire business object. Multiple Sync messages may exist in cases in which different named views of the business object exist, but never for synchronizing a specific component of a business object.

Tip:

Unlike the OAGIS implementation of Sync, Oracle AIA has opted not to have specific attributes in Sync to indicate Add, Change, Replace, and Delete. The Enterprise Object Library (EOL) implementation of Sync is a verb that is intended to change the target object to exactly what is specified in the message payload. Sync cannot be used for deleting content-an explicit delete operation must be used in this case.

Verb Attributes

The Sync verb has an optional ResponseCode attribute that is intended to communicate the payload that is expected in the response message to the Sync request. The possible values for the ResponseCode for Sync is restricted to OBJECT (response payload is expected to be the entire object that was created or updated) and ID (response is only the ID of the object that was created or updated)

Corresponding Response Verb

The Sync verb has a paired SyncResponse verb that is used in the response message for each Sync EBM. The response is expected to be provided by the target application only if the original request message explicitly requests a response by setting the ResponseCode attribute in the Sync message.

Note:

The design intent is to avoid having two verbs with the same objective. The Sync verb also supports the creation of an object, but is intended for use primarily in the scenario in which the object exists in both the source and the target systems. That is, the semantics of usage of Sync as a verb communicates to the recipient application the fact that the object being synchronized exists in both the source and target, whereas the usage of Create or Update is intended to communicate the fact that the object being created or updated does not exist in the source system.

Response Verb Content Payload

The payload type of the response verb is always based on the payload type of the Sync Request operation. It is implemented as a different type to support user customization if needed.

16.8.5 Validate

The Validate verb is a request to a service provider to validate the content provided in the payload of the message. It is used for operations that are intended to verify the validity of data.

When to Use the Validate Verb

Operations that use the Validate verb do not create or update business objects, and can internally be implemented as an orchestration of other operations. For example, validating a purchase order for approval may involve validating whether a budget is available, if the supplier is still active, if the requisitions that need the items on the line are still valid, and so on.

Content Payload

The payload of any operation that falls in the Validate category can be a business object, a business component of a business object, or any other user-defined payload.

Verb Attributes

Not applicable.

Corresponding Response Verb

The Validate verb has a paired ValidateResponse verb that is used in the response message for each Validate EBM. The Validate verb is always implemented synchronously.

Response Content Payload

The response payload of a Validate operation is user-definable.

16.8.6 Process

The Process verb is a request to a service provider to perform the corresponding operation on the business object associated with the service. It is generally used for operations that orchestrate multiple other operations, are intended to achieve a specific business result, or both.

When to Use the Process Verb

Process is used as a single verb to categorize all business operations that result in content updates but do not fall in the Create/Update/Delete category to avoid a proliferation of verbs for specific business object actions.

Operations that use the Process verb must always result in creation or updating of one or more business objects and may represent an orchestration of other operations.

The Process verb can also be used for operations that act on a single business object, but have specific business semantics that cannot be communicated using an Update operation. In general, such actions are implemented in applications with distinct access control, and specific business rules that are applicable when the action is performed. Examples of such actions are state changes, updating meter readings on equipment, and so on.

Because multiple operations can be performed by the Process verb, potentially multiple Process verbs can be used in any given EBS.

Tip:

Operations that implement the Process verb can be implemented as synchronous or asynchronous. This is a deviation from the other verbs for which a consistent implementation pattern applies across all operations that use them.

Content Payload

The nature of the operation performed by a Process verb may require properties and values that are not part of the business object on which the operation is being performed, but are required by the business rules that are implemented by the operation. For example, approval of a sales order can record a comment as part of the approval, but the comment in itself may not be a property of the sales order.

In general, the request and response payload of operations that use the Process verb need the ability to reflect the method signature of the application, without a restriction that the content that forms the payload must come from the business object to which the service operation is associated.

To support the preceding, the payload of each Process operation is not restricted to content from the EBO definition. This is unlike all the other EBOs for which the EBM business content must be the same as or a subset of the EBO content.

Note:

Currently, AIA does not support assembling Process EBM payloads using content from other business components. So a Process operation for credit verification that is defined for a customer party cannot include content from Sales Order EBO to build its message payload.

The List pattern used in the other generic verbs is also applicable here, but does not apply generically; that is, in an EBS, both a single and List implementation of a Process operation may exist, or just one or the other. Unlike the other generic verbs for which single and list are both consistently created for all EBOs, Process is driven by the requirements of the corresponding operation.

Verb Attributes

Not applicable.

Corresponding Response Verb

The Process verb has a paired ProcessResponse verb that is used in the response message for each Process EBM.

Response Verb Payload

The payload of the response verb is specific to each process operation and is determined by the objective of the operation. Similar to the Process verb payload, there is no restriction that the content of the response is restricted to the content of the EBO.

16.8.7 Query

The Query verb is a request to a service provider to perform a query on a business object using the content provided in the payload of the Query message, and return the query result using the corresponding response message associated with the query. The requester can optionally request a specific subset of the response payload.

When to Use the Query Verb

Similar to the other verbs, the Single and the List pattern apply to queries also. The use of Query for each of these patterns has been listed separately in the following sections.

Tip:

The same verb applies to both the patterns, but the implementation and attributes applicable are completely different.

Single Object Query Intended to Return One and Only One Instance

The Single Object Query operation is a simple get by ID operation that enables callers to look up an EBO by its identifier. It is intended to request a single instance of a business object by specifying the ID of the object and optionally a QueryCode and ResponseCode with a set of parameters and their values. The identifier of the object is specified in the DataArea of the Query EBM.

The single object query does not support any other query criteria to minimize the possibility of the query returning multiple objects, and the response payload for the simple query is restricted to a single instance of the object being queried.

The Single Object Query contains the following elements:

  • QueryCode within the Query element (optional)

    The QueryCode in a single object Query is used mainly as a supplement to the Identification element provided in the DataArea of the Query. The Query Code can be used for a single object query for cases in which there is a need to communicate more than the ID to the query service provider to successfully run the query. The code could be used to either refine the query, or to select the object to be queried based on the Query Code.

    Tip:

    For this to happen, the service provider should implement the processing of such a code. Currently, Oracle AIA does not predefine any generic Query Codes as part of the EOL.

  • ResponseCode within the Query Element (optional)

    The ResponseCode is a predefined code that instructs a query service provider to filter the response content of the EBO to a specific subset of the response object.

    The return payload for a generic Query is always the entire EBO; that is, by default, the response payload for a QuerySalesOrder operation is always the entire SalesOrder with lines, shipment, and so on. If the requester wants the service provider to provide only the SalesOrder header with none of the child components, then the ResponseCode can be used as an instruction to the service provider to build the response payload accordingly.

    Tip:

    For this to happen, the service provider should implement the processing of such a code. Currently, Oracle AIA does not predefine any generic Request or Response Codes as part of the EOL.

Content Payload

The payload of a single object query is always the ID of the object to be queried. This is specified within the Identification element of the DataArea as shown in Example 16-13.

Example 16-13 Content Payload of a Single Object Query

<QueryAccountBalanceAdjustmentEBM>
<corecom:EBMHeader>
        
   </corecom:EBMHeader>
   <DataArea>
         <Query>
         </Query>
         <QueryAccountBalanceAdjustment>
               <corecom:Identification>
                     <corecom:ID>1005</corecom:ID>

               </corecom:Identification>
               <Custom/>
         </QueryAccountBalanceAdjustment>
   </DataArea>
</QueryAccountBalanceAdjustmentEBM>

Verb Attributes

The simple Query can have an optional getAllTranslationsIndicator to indicate whether the service provider is expected to provide all translations to be populated in the response for all translatable elements. The default is to bring back data in the language of the request only.

Based on the preceding, there are ways in which in which a simple query can be constructed:

  • Simple Query with just ID:

    An example of querying for a single object would be querying Purchase Order with ID="3006". No other code or parameters are needed in this example.

  • Simple Query with QueryCode:

    As an example, consider an application that maintains a distinction between a person as a customer versus an organization as a customer. A single Customer Query service exists, but to successfully run the query, the service provider must be told whether the ID to be queried belongs to an organization or to a person. In this case, the QueryCode can be used to communicate the Person/Organization information.

List Query That Can Return Multiple Instances

The single object query does not support any search criteria beyond a simple search by identification, and can return only one instance of an object. All other queries are treated as List queries.

A List Query may return multiple records in response to the query and supports the ability to build complex queries.

The List Query is implemented using the following elements:

QueryCode within the Query element (optional)

The QueryCode in a List Query serves as a means for a service provider to limit the possible queries that can be built using a List Query. In the absence of a QueryCode, a service provider should be able to generically support all possible queries that can be communicated using the QueryCriteria element explained subsequently.

For this to happen, the service provider should implement the processing of such a code. Currently, Oracle AIA does not predefine any generic Query Codes as part of the EOL.

ResponseCode within the Query Element (optional)

The ResponseCode is a predefined code that instructs a query service provider to filter the response content of the EBO to a specific subset of the response object. For list queries, this can serve as an alternate mechanism instead of specifying the ResponseFilter element of a Query.

The return payload for a generic Query is always the entire EBO. For example, by default, the response payload for a QuerySalesOrder operation is always the entire SalesOrder with lines, shipment, and so on. If the requester wants the service provider to provide only the SalesOrder header with none of the child components, then the ResponseCode can be used as an instruction to the service provider to build the response payload accordingly.

For this to happen, the service provider should implement the processing of such a code. Currently, Oracle AIA does not predefine any generic Request or Response Codes as part of the EOL.

QueryCriteria (1 to n instances)

The QueryCriteria element enables a user to build a complex query statement on a specific node of the object being queried. At least one QueryCriteria element must be specified for a List Query.

Multiple QueryCriteria elements can be present in a Query if the query spans multiple nodes of the object being queried. Multiple Query criteria is similar to a subselect in that the result set of one Query Criteria is filtered by the second to arrive at a smaller subset of records.

Each QueryCriteria element consists of:

  • QualifiedElementPath (0 or 1 instance):

    This enables the user to specify the node on which the QueryCriteria applies. If the element is not included in the Query, or if it is included with no value or a NULL value, or if it has a value of /, the query criteria applies to the root element of the object.

    QueryExpression (exactly 1 instance, with optional nesting of other QueryExpressions within it): This element is the container for the actual query. The QueryExpression is a nested construct that enables you to define complex queries. Each QueryExpression consists:

    • A logicalOperatorCode attribute that can have a value of either AND or OR. These attributes can be specified to indicate the logical operation to be performed on the content (nested multiple QueryExpressions or list of ValueExpressions) within the QueryExpression.

    • A choice of one or more QueryExpressions or one or more ValueExpressions.

      • A QueryExpression may contain other QueryExpressions when you must combine multiple AND or OR operations in a query.

      • If the Query can be expressed with a single AND or OR operator, then it can be built using multiple ValueExpressions within an outer QueryExpression.

  • ValueExpression (1 or more instances):

    Each ValueExpression represents an assignment of a value to a specific node within the node represented by the QualifiedElementPath (or the root node if the QualifiedElementPath is not present). The ValueExpression is specified using:

    • An ElementPath element that represents either a node (expressed as a simpleXPath expression) to which the query value is being assigned, or a Code in case the element cannot be found in the document. For example, /SalesOrderLine/Status/Code or just StatusCode. No explicit way is available to indicate whether the ElementPath contains a code or an Xpath expression.

    • Value element that contains the value assigned to the ElementPath, for example, Approved.

    • A queryOperatorCode attribute that specifies the operator applicable to the Value assigned to the ElementPath. The possible operators are EQUALS, NOT_EQUALS, GREATER_THAN, GREATER_THAN_EQUALS, LESS_THAN, LESS_THAN_EQUALS, CONTAINS, DOES_NOT_CONTAIN, LIKE, NOT_LIKE, LIKE_IGNORE_CASE, NOT_LIKE_IGNORE_CASE, IS_BLANK, IS_NOT_BLANK, BETWEEN, NOT_BETWEEN, IN, NOT_IN

  • SortElement (0 or more instances):

    Each QueryCriteria can have one or more SortElements defined, as shown in Example 16-14. A SortElement is used to request the Query result set to be sorted using the criteria specified in the SortElement. Each SortElement has an optional sortDirectionCode attribute that identifies the order of sorting-ASC (ascending) or DESC (descending).

    Example 16-14 Defining SortElements for Single QueryCriteria

    <QueryCriteria>
    <QueryExpression>
             <ValueExpression>
                  
             </ValueExpression>     
       </QueryExpression>           
       <SortElement sortDirection="DESC">/OrderDateTime</SortElement>
       <SortElement sortDirection="ASC">/Description</SortElement>
    </QueryCriteria>
    

    In Example 16-14, the result set of the QueryExpression is to be sorted in descending order of OrderDateTime and ascending order of Description.

    If multiple QueryCriteria exist, then each can have its own SortElement, as shown in Example 16-15. The result set of one QueryCriteria is sorted, and then after the next QueryCriteria filter is applied, the resultant subset is sorted using the SortElement specified for that QueryCriteria.

    Example 16-15 Defining SortElements for Multiple QueryCriteria

    <QueryCriteria>
    <QueryExpression>
             <ValueExpression>
                  
             </ValueExpression>     
       </QueryExpression>           
       <SortElement sortDirection="DESC">/OrderDateTime</SortElement>
       <SortElement sortDirection="ASC">/Description</SortElement>
    </QueryCriteria>
    <QueryCriteria>
       <QualifiedElementPath>/SalesOrderLine/SalesOrderLineBase</QualifiedElementPath>
       <QueryExpression>
       ...
       </QueryExpression>
       <SortElement>/SalesOrderLine/SalesOrderLineBase/ListPrice</SortElement>
    </QueryCriteria>
    

    In Example 16-15, the SalesOrder root query is sorted by OrderDateTime and Description, while the child node SalesOrderLine is sorted by price.

QueryCriteria Examples

Example 1   Query with a Single QueryCriteria Element and Single Query Expression

Example 16-16 is an example of a query with a single QueryCriteria element and a single QueryExpression element that contains only ValueExpression elements. The query to be run is Query SalesOrder, in which "SalesOrder/CurrencyCode = "USD" AND "SalesOrder/OrderDateTime = "2003-12-04". The query expression is defined for the root node; hence, the QualifiedElementPath is not present (optional).

This is modeled as two ValueExpressions nested within a QueryExpression. The logicalOperatorCode on the QueryExpression indicates the operation (AND) to be performed across the two ValueExpressions.

Example 16-16 Example of Query with Single QueryCriteria Element and Single QueryExpression

<Query>
<QueryCriteria>
         <QueryExpression logicalOperatorCode="AND">
               <ValueExpression queryOperatorCode="EQUALS">
                     <ElementPath>/SalesOrderBase/CurrencyCode</ElementPath>
                     <Value>USD</Value>
               </ValueExpression>
               <ValueExpression queryOperatorCode="GREATER_THAN_EQUALS">
                     <ElementPath>/SalesOrderBase/OrderDateTime</ElementPath>
                     <Value>2003-12-04</Value>
               </ValueExpression>
         </QueryExpression>
   </QueryCriteria>
</Query>
Example 2   Query with a Single QueryCriteria and Nested QueryExpressions

Figure 16-13 is an example of a Query with a single QueryCriteria but with nested QueryExpressions. The query to be run is Query SalesOrders, in which SalesOrder/CurrencyCode=USD AND SalesOrder/OrderDateTime<2003-12-04 OR SalesOrder/Description CONTAINS "BMW 520i". Both the query expressions are defined for the root node; hence, the QualifiedElementPath is not present (optional).

Note: When nested QueryExpressions exist, they are all on the same QualifiedElementPath.

This is modeled as two QueryExpressions nested within an outer QueryExpression.

The outer QueryExpression identifies the operand to be applied to the two inner QueryExpressions (OR). The ValueExpressions contain the actual query data with the query operator to be applied to the data element as shown in Figure 16-13.

Figure 16-13 Example of Query with Nested Query Expressions

The image is described in the surrounding text
Example 3   Query with Multiple QueryCriteria

Example 16-17 is an example of a Query with multiple QueryCriteria. When multiple QueryCriteria exist, no logical operation is present that is applicable across them-they are the equivalent of running the query specified in the first QueryCriteria element, then applying the second QueryCriteria to the result of the first.

The query to be executed is: Query CustomerParty where Type = GOLD and filter the result set to only accounts whose status is "ACTIVE".

This is implemented as two QueryCriteria. The first is to query the CustomerParty and retrieve all Customers of TYPE-"GOLD". This query is run on the CustomerParty root node.

The result set of this query is then filtered by applying the second Query Criteria. This queries the CustomerParty/Account node to get all CustomerParty Accounts that have STATUS = "ACTIVE".

Example 16-17 Example of Query with Multiple QueryCriteria

<Query>
<QueryCriteria>
         <QueryExpression>
               <ValueExpression queryOperatorCode="EQUALS">
                     <ElementPath>/Type</ElementPath>
                     <Value>GOLD</Value>
               </ValueExpression>
         </QueryExpression>
         <SortElement>/LastName</SortElement>
   </QueryCriteria>
   <QueryCriteria>
         <QualifiedElementPath>/CustomerAccount</QualifiedElementPath>
         <QueryExpression>
               <ValueExpression queryOperatorCode="EQUALS">
                     <ElementPath>/CustomerAccount/Status/Code</ElementPath>
                     <Value>ACTIVE</Value>
               </ValueExpression>
         </QueryExpression>
   </QueryCriteria>
</Query>

ResponseFilter (0 to 1 instance)

The ResponseFilter enables a requester to indicate which child nodes he or she is interested or not interested in. The excluded child nodes are not populated by the application when the response to the query is being built. If supported by participating applications, this feature improves performance by not querying the nodes that are excluded from the query.

Example 1   Request for Single Return to QueryInvoice Message

Example 16-18 illustrates requesting only the InvoiceLine to be returned in response to a QueryInvoice message.

Example 16-18 Requesting a Single Return to QueryInvoice Message

<Query>
<QueryCriteria>

   </QueryCriteria>
         <ResponseFilter>
               <ChildComponentPath>InvoiceLine</ChildComponentPath>
         </ResponseFilter>
</Query>
Example 2   Request for Specific Message Return to QueryInvoice Message

Example 16-19 is an example of returning all QueryInvoice message content except for Charge and PaymentTerm.

Example 16-19 Requesting Specific Message Return to QueryInvoice Message

<Query>
<QueryCriteria>

   </QueryCriteria>
   <ResponseFilter>
         <ExclusionIndicator>true</ExclusionIndicator>
         <ElementPath>Charge</ElementPath>
         <ElementPath>PaymentTerm</ElementPath>
   </ResponseFilter>
</Query>

Tip:

In the absence of a very comprehensive framework for processing queries, this option is difficult to implement practically, because in theory infinite ways are available by which the query can be built, and the service provider would not be able to process all possible ways in which the QueryCriteria is specified.

Content Payload

No content payload for a List Query is available-the query is defined entirely within the Verb element of the DataArea.

Verb Attributes

  • getAllTranslationsIndicator(optional):

    A Query can have an optional getAllTranslationsIndicator to indicate whether the service provider is expected to provide all translations to be populated in the response for all translatable elements. The default is to bring back data in the language of the request only.

  • recordSetStart(optional):

    This is an instruction to the query service provider to return a subset of records from a query result set, with the index of the first record being the number specified in this attribute.

    As an example, consider a query that returns 200 records in the result set. The requester can invoke the query with a recordSetStart parameter set to "101", in which case the service provider is expected to process this value and build a result set that contains the 101st to the 200th record of the result set.

  • recordSetCount(optional):

    The presence of this attribute is an instruction to the service provider to return the same attribute with the count of the number of records in the response to the Query. Absence of this attribute indicates that a record set count is not expected in the response to the query.

  • maxItems(optional):

    This is an instruction to the query service provider that the maximum number of records returned in the query response should not exceed the value specified for this attribute.

    The result set of a query may result in multiple records that meet the query criteria, but the query service Requester may be able to process only a specific number of records at a time. For example, a query might result in a result set of a 1000 records, but the query Requester can process only 100 records at a time. The service Requester can use the maxItems attribute to instruct the service provider to return only 100 records in the response.

Corresponding Response Verb

The Query Verb has a paired QueryResponse verb that is used in the response message for each Query EBM.

Response Verb Payload

The payload of the response verb is typically the entire business object.

16.9 Invoking the ABCS

This section assumes that you have completed the ABCS construction. The different ways in which your ABCS can be invoked are discussed here.

An ABCS can be invoked by an application or by another service. The service, if it happens to be an AIA artifact, could be either a transport adapter or an EBS. This section describes what must be done in each of the three scenarios.

This section includes the following topics:

16.9.1 How to Invoke an ABCS Directly from an Application

For the inbound interactions of applications with the ABCS:

  1. Start with identifying the participating applications.

  2. Analyze the integration capabilities of each participating application.

  3. Work with the application providers (developers) to decide the best way to interact with the application to achieve the needed functionality.

    The interaction mechanism can be one of the following:

    • SOAP WebService

    • Events/Queues

    • JCA

  4. Obtain relevant details from the applications in situations in which the interactions between the participating applications and the ABCS happen through a message queue adapter or a JCA Adapter.

    These details are used in configuring the adapters. The configuration results in the WSDL creation. Care must be taken to ensure that the environment-specific details are configured in relevant resource files on the server and not directly in the WSDLs.

16.9.2 How to Invoke an ABCS Using Transport Adapters

When the Requester ABCS is invoked by the transport adapters, the interaction between ABCS and the transport adapters is using either SOAP Web Service or native binding.

More details are specified in Section 17.3.1, "Interfacing with Transport Adapters."

The details on establishing the inbound connectivity between adapters and the ABCS are given in Chapter 24, "Establishing Resource Connectivity."

16.9.3 When Does an Enterprise Business Service Invoke an ABCS

An EBS invokes:

  • A provider ABCS, which implements an EBS operation. This is true because an EBS provides the mediation between the requesting services and providing services.

  • A requester ABCS to send the response to it. In scenarios in which a requesting service is waiting for a delayed response, the delayed response from the providing service can be routed by a Response EBS to the waiting Requester ABCS.