13 Completing ABCS Development

This chapter describes how to develop Application Business Connector Services (ABCS) to:

This chapter includes the following sections:

13.1 Developing Extensible ABCS

An ABCS, regardless of whether it is requester or provider specific, can invoke custom code a minimum of either two or four times during its execution. These serve as extensibility points.

The ABCS supporting request-response pattern in either synchronous or asynchronous mode has four extensibility points. An ABCS supporting fire-and-forget patterns has two extensibility points. You can develop "add-ins" and have them hooked to these extensibility points. These "add-ins" - customer-developed services- behave as an extension to the delivered ABCS. Each extension point allows one hook so only a single customer extension can be plugged in.

This section describes the mechanism for creating ABCSs with extensible services, which enables you to have service implementations that require no modifications to the delivered ABCS.

13.1.1 Introduction to Enabling Requester ABCS for Extension

For request/response Requester ABCS, you can hook your custom code to four extensibility points:

  1. Just prior to the execution of transformation of application business message (ABM) to Enterprise Business Message (EBM). Use this configuration property name: ABCSExtension.PreXformABMtoEBM.

  2. Just prior to the invocation of the enterprise business service (EBS). Use this configuration property name: ABCSExtension.PreInvokeEBS.

  3. Just prior to the execution of transformation of EBM to ABM and after invoking the EBS. Use this configuration property name: ABCSExtension.PostInvokeEBS.

  4. Just prior to the invocation of callback service or response return and transforming EBM to ABM. Use this configuration property name: ABCSExtension.PostXformEBMtoABM.

The third and fourth extension points are available only in ABCS implementing request-response pattern.

For Fire and Forget Requester ABCS, you can hook your custom code to two extensibility points:

  1. Just prior to the execution of transformation of application business message (ABM) to EBM. Use this configuration property name: ABCSExtension.PreXformABMtoEBM.

  2. Just prior to the invocation of the enterprise business service (EBS). Use this configuration property name: ABCSExtension.PreInvokeEBS.

For more information about configuration parameters, see section 15.1.3.1.

Figure 13-1 depicts the high-level flow of activities in a requester-specific ABCS. The diagram assumes that the EBS with which it is interacting employs a request-response interaction style. Note that the steps for executing the customer extension to do additional tasks are optional.

Figure 13-1 Extending the Request-Response Interaction Style

The image is described in the surrounding text

Figure 13-2 shows the high-level flow of activities in a requester-specific ABCS. The diagram assumes that the EBS with which it is interacting employs a fire-and-forget interaction style. Note that the steps for executing the customer extension to do additional tasks are optional.

Figure 13-2 Requester-Specific ABCS Using Fire-and-Forget Interaction Style

The image is described in the surrounding text

The first extensibility point made available to the implementers of the requester ABCS can be used to perform custom message inspection. This extensibility point can be used to inject code to perform tasks such as custom validation, message alteration, message filtering and so on. The custom code has access to the ABM that is about to be transformed and can return either an enhanced ABM or raise a fault.

The second extensibility point can be used to perform custom message augmentation. The extensibility point can be used to inject code to perform tasks such as EBM enhancement, custom validation and so on. The custom code has access to EBM that is about to be used for invocation of EBS and can return either an enhanced EBM or raise a fault.

The third extensibility point can be used to inject code to perform tasks such as custom validation, message alteration, message filtering and so on. The custom code has access to EBM that is about to be transformed to ABM. The custom code can return either an altered EBM or raise a fault.

The fourth extensibility point can be used to inject code to perform tasks such as ABM enhancement, custom validation and so on. The custom code has access to ABM that is about to be used for invocation of callback services. The custom code can return either an altered ABM or raise a fault

13.1.2 Introduction to Enabling Provider ABCS for Extension

For request/response Requester ABCS, you can hook your custom code to four extensibility points:

  1. Customer extension just prior to the execution of the EBM to ABM transformation. Use this configuration property name: ABCSExtension.PreXformEBMtoABM.

  2. Customer extension just prior to the invocation of application service. Use this configuration property name: ABCSExtension.PreInvokeABS.

  3. Customer extension just prior to the execution of the ABM to EBM transformation and after invoking Application Service. Use this configuration property name: ABCSExtension.PostInvokeABS.

  4. Customer extension just prior to the invocation of Enterprise Business Service and after transforming Application Message to Enterprise Business Message. Use this configuration property name: ABCSExtension.PostXformABMtoEBM.

The third and fourth extension points are available only in the ABCS implementing request-response pattern.

For Fire and Forget Requester ABCS, you can hook your custom code to two extensibility points:

  1. Customer extension just prior to the execution of the EBM to ABM transformation. Use this configuration property name: ABCSExtension.PreXformEBMtoABM.

  2. Customer extension just prior to the invocation of application service.Use this configuration property name: ABCSExtension.PreInvokeABS.

For more information about configuration parameters, see section 15.1.3.1.

Figure 13-3 depicts the high-level flow of activities in a provider-specific ABCS. The diagram assumes that the EBS with which it is interacting employs a request-response interaction style.

Figure 13-3 Provider-Specific ABCS Using Request-Response Interaction Style

The image is described in the surrounding text

Figure 13-4 depicts the high-level flow of activities in a provider-specific ABCS. The diagram assumes that the EBS with which it is interacting employs a fire-and-forget interaction style.

Figure 13-4 Provider-Specific ABCS Using Fire-and-Forget Interaction Style

The image is described in the surrounding text

The first extensibility point made available to the implementers of the Provider ABCS can be used to inject code to perform tasks such as custom validation, message alteration, message filtering and so on. The custom code has access to EBM that is about to be transformed. The custom code can return either an enhanced EBM or raise a fault.

The second extensibility point can be used to perform custom message augmentation. The extensibility point can be used to inject code to perform tasks such as ABM enhancement, custom validation and so on. The custom code has access to ABM that is about to be used for invocation of application service. The custom code can return either an enhanced ABM or raise a fault.

The third extensibility point can be used to inject code to perform tasks such as custom validation, message alteration, message filtering and so on. The custom code has access to ABM that is about to be transformed to EBM. The custom code can return either an altered ABM or raise a fault.

The fourth extensibility point can be used to perform custom message augmentation. The extensibility point can be used to inject code to perform tasks such as EBM enhancement, custom validation and so on. The custom code has access to EBM that is about to be used for invocation of callback services. The custom code can return either an altered EBM or raise a fault.

13.1.3 How to Design Extensions-Aware ABCS

Each of the extensibility points is modeled as a service operation having a well-defined interface. ABCS authors define these interfaces. The extensibility interfaces consist of service operations that the ABCS invokes to execute the custom message enrichment or transformation or validations specific code implemented by the customer.

Each ABCS is accompanied by a corresponding customer extension service. A request-response ABCS has four extensibility points, therefore, the ABCS extension service has four service operations. For a fire-and-forget ABCS, the corresponding ABCS extension service has two service operations.

As delivered, the implementation of these service operations for all of the ABCS extension services invokes the same piece of code that always returns the same message. This piece of code has been implemented as a Servlet.

The ABCS is developed to invoke the appropriate service operation at each of the extensibility points. To minimize overhead, a check is made to ensure that the service for the relevant extensibility interface has been implemented. Oracle AIA Configuration properties have one property for each extensibility point. Setting the property to 'Yes' indicates that there is a custom implementation for the extensibility point. The default value for these properties is No, therefore, the ABCS never invokes the implementations of these extensions as they were delivered.

Table 13-1 lists the service operations for the requester ABCS-specific extensibility points:

Table 13-1 Service Operations for Requester ABCS-Specific Extensibility Points

Extensibility Point Service Operation Name

Just before the execution of transformation of ABM to EBM

Pre-ProcessABM

Just before the invocation of the EBS

Pre-ProcessEBM

Just before the execution of transformation of EBM to ABM

Post-ProcessEBM

Just before the invocation of callback service or response return

Post-ProcessEBM


Figure 13-4 lists the service operations for the provider ABCS-specific extensibility points:

Table 13-2 Service Operations for Provider ABCS-Specific Extensibility Points

Extensibility Point Service Operation Name

Just before the execution of transformation of EBM to ABM

Pre-ProcessEBM

Just before the invocation of Application Service

Pre-ProcessABM

Just before the execution of transformation of ABM to EBM

Post-ProcessABM

Just before the invocation of callback EBS or response return

Post-ProcessEBM


AIA recommends that the ABCS and that the customer extension services be co-located. In SOA 11g, when the services are deployed on the same server, the SOA 11g run time uses native invocation.

AIA recommends that the extension service should be enlisted as part of the ABCS transaction. When the extension service is implemented using SOA 11g technology, then set the transaction property bpel.config.transaction to 'required' on the extension service to enlist itself in the ABCS transaction.

For more information, see Section 13.6.1, "How to Ensure Transactions in AIA Services".

13.1.3.1 Configuration Parameters

Operations at the extension points are invoked based on the values of the specific parameters in the file AIAConfigurationProperties.xml. Each service configuration section specific to an ABCS requires that these parameters be specified. The parameters for each of the four extension points are:

  • ABCSExtension.PreXformABMtoEBM

  • ABCSExtension.PreInvokeEBS

  • ABCSExtension.PostInvokeEBS

  • ABCSExtension.PostXformEBMtoABM

  • ABCSExtension.PreXformEBMtoABM

  • ABCSExtension.PreInvokeABS

  • ABCSExtension.PostInvokeABS

  • ABCSExtension.PostXformABMtoEBM

These parameters must be configured with value 'true' for a service invocation. When these parameters are not specified in the configuration section for an ABCS, the value considered by default is 'false'.

The intent of this section is to provide developers with a set of guidelines on how to create and leverage these configuration properties to optimize extensibility. The service operation names and extension configuration properties provided in this section are recommendations only

Also, it is not within the scope of this discussion to provide guidelines for extension points for every one of the invocations. The number of parameters for any particular ABCS could be different. Product management and engineering teams are best equipped to identify the additional extension points where additional extensibility is required.

IT organizations developing services that could potentially be extended by the departmental teams or by their partners will find a need for ABCS to made extension aware. Given this use case, if a customer has to develop ABCS with additional extension points than the recommended, they can come up with appropriate names by following the appropriate naming conventions for service operation names and configuration properties similar to the currently proposed properties.

13.1.4 Designing an ABCS Composite with Extension

When an ABCS composite is developed as an extension-enabled service:

  • The ABCS is implemented as a component (using BPEL technology) in the composite.

  • The extension service is referred to by the ABCS composite as an external Web service.

The service at the extension point is developed in a separate composite if it is developed over an Oracle Fusion Middleware platform.

When different external extension services are referred to by the ABCS composite, more than one hook exists from the ABCS composite to the External Service. That is, when an ABCS invokes two different services at two of its extension points, the composite must be designed to have two distinct external references, as shown in Figure 13-5:

Figure 13-5 Example of Composite with Two Distinct External References

The image is described in the surrounding text

However, when an ABCS composite invokes two distinct operations that are exposed on the same external service, then the ABCS composite has only one external reference, as shown in Figure 13-6:

Figure 13-6 Example of Composite with One External Reference

The image is described in the surrounding text

13.1.5 Defining Service at Extension Points

At the extension points, partner links are defined to set up the conversational relationship between two services by specifying the roles played by each service in the conversation and specifying the port type provided by each service to receive messages within the context of the conversation.

This is accomplished with the help of a Web Services Description Language (WSDL) file that describes the services the partner link offers. The WSDL is an XML document that describes all the Service Provider contracts to the service consumers.

The WSDL separates the service contract into two distinct parts, the Abstract WSDL and the Concrete WSDL:

  • The Abstract WSDL includes elements such as types, messages that define the structure of the parameters (input and output types), fault types, and the port type, which is known as the interface.

  • The Concrete WSDL includes bindings to protocols, concrete address locations, and service elements.

13.1.6 Defining a Service Using an Abstract WSDL

An abstract WSDL defines the external reference service at design time. This WSDL provides interfaces to the operations to be invoked at the extension points. It should also include or import the schemas for the application business object (ABO) and Enterprise Business Object (EBO). It is devoid of communication transport protocols, network address locations, and so on.

The abstract WSDL used to define the extension point service should be placed in the project folder. Do not push this into MDS, unlike other abstract WSDLs of the AIA services.

Note: An abstract WSDL may be used temporarily for design-time modeling only. At the time the composite is deployed, the binding should be specified.

When AIA Service Constructor is used to construct ABCS, it creates the extension service references in the composite.xml file.

When you use JDeveloper, follow these high-level steps to design the composite:

To design the composite to extension-enable ABCS:

  1. In JDeveloper, open a SOA composite project.

  2. Open the composite.xml in design mode.

  3. To reference an extension point service, add a Web service as an external reference service in the References swim lane. Use the Abstract WSDL for design time modeling.

    Tip:

    This abstract WDSL will not be in the MDS. It is associated with the project and is in the project folder.
  4. Wire the BPEL component to the external reference component created in the previous step.

    When the composite is opened in the source mode, you see code similar to the Example 13-1.

    This code example was reproduced from the composite.xml, where the extension service is defined using an abstract WSDL:

    Example 13-1 Wiring the BPEL component to the external reference component

    <reference name="SamplesCreateCustomerSiebelReqABCSImplExtExtension"
    ui:wsdlLocation="SamplesCreateCustomerSiebelReqABCSImplExtExtensionAbstract.wsdl">
            <interface.wsdl 
    interface="http://xmlns.oracle.com/ABCSImpl/Siebel/Samples/CreateCustomerSiebelR
    eqABCSImplExtExtension/V1#wsdl.interface(SamplesCreateCustomerSiebelReqABCSImpl
    ExtExtensionService)"/>
            <binding.ws port="" location=""/>
        </reference>
    
    

13.1.7 How to Specify a Concrete WSDL at Deployment Time

A concrete WSDL is a copy of the abstract WSDL used for defining the extension service. The concrete WSDL also defines the binding element that provides information about the transport protocol and the service element that combines all ports and provides an endpoint for the consumer to interact with the service provider.

Initially, at the time of development, the concrete WSDL points to the sample extension service, which is a Servlet. The Servlet is named MirrorServlet and is shipped with the Foundation Pack.

You should push the concrete WSDL into the MDS repository to the folder 'ExtensionServiceLibrary'.

13.1.7.1 Populating the binding.ws Element in the composite.xml

To invoke the external reference service, a run-time WSDL with concrete bindings must be specified in the ABCS composite.xml. The Port type in the WSDL should have a concrete binding. That is, in the composite, the attributes of the element, binding.ws, cannot be empty.

Note:

Populating the 'location' attribute of the element binding.ws with the URL of a run-timeWSDL, does not amount to voilating 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 run time.

To deploy the composite that references an external Web service, which is defined using an abstract WSDL, the attributes of the element binding.ws must be populated, as shown below:

<binding.ws port="[namespace of the ABCS Extension Service as defined in the WSDL]/V1#wsdl.endpoint(<Name of the ABCS Service as given in the WSDL>/<Name of the Porttype as given in the WSDL>" location="[location of the concrete WSDL in the MDS]" xmlns:ns="http://xmlns.oracle.com/sca/1.0"/>

The name of the ABCS 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. According to naming conventions, the name of the service is <name of the composite>, which in turn is the value of the attribute 'name' of the 'definitions' element in the WSDL.

At the time when the service at the extension point is developed and deployed by the customer,

  • Customer can replace the sample concrete WSDL in the MDS with the concrete WSDL that is developed for the extension service and redeploy the ABCS.

  • Customer can change binding.ws.location to point to the concrete WSDL of the deployed service and redeploy the ABCS.

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

13.1.8 Designing Extension Points in the ABCS BPEL Process

The following section details the steps to be completed to provide extension points in a Requester ABCS with a one-way invocation call.

In a Requester ABCS with a request-only call to a service, two possible extension points exist. The first extension point is just before the transformation from ABM to the EBM, and second extension point is just before the invocation of the service. The service operations at these extension points are defined as Pre-ProcessABM and Pre-ProcessEBM, respectively. The service operation at the extension points is an invocation to Servlet that only returns the payload.

13.1.9 How to Set Up the Extension Point Pre-ProcessABM

When AIA Service Constructor is used to construct ABCS, the extension point is already set up by the tool.

The Requester ABCS requires the following process activities in the order specified:

  1. Switch

    The Switch activity determines if the service invocation at the extension point is to be made or not. This is achieved by checking the value of the property variable in the file AIAConfigurationProperties.xml. The name of the configuration parameter is 'ABCSExtension.PreProcessABM '. Check this parameter for a value of 'true'. This is achieved by using an appropriate 'AIAXPathFunction' in the switch expression.

  2. Assign-Invoke-Assign

    The Assign-Invoke-Assign subsequence of process activities is embedded in the Switch activity.

    • Assign

      The Assign activity assigns the value of the input variable of the 'receive' step to the input variable of the 'invoke' step that follows.

    • Invoke

      The Invoke activity makes the service-call on the partner-link. The programming model for the ABCS extension points sets up a contract on the service to return the same payload that it receives.

    • Assign

      The Assign activity assigns the value of the response payload from the service invocation to the variable of the process activity that follows.

    Figure 13-7 illustrates the sequence:

    Figure 13-7 Setting up the Extension Point Pre-ProcessABM

    The image is described in the surrounding text

13.1.10 How to Set Up the Extension Point Pre-ProcessEBM

When AIA Service Constructor is used to construct ABCS, the extension point is already set up by the tool.

The Requester ABCS requires the following process activities in the order specified:

  1. Switch

    The Switch activity determines if the service invocation at the extension point is to be made or not. This is achieved by checking the value of the property variable in the file AIAConfigurationProperties.xml. The name of the configuration parameter is 'ABCSExtension.PreProcessEBM'. Check the parameter for a value of 'true'. This is achieved by using an appropriate 'AIAXPathFunction' in the switch expression.

  2. Assign-Invoke-Assign

    The Assign-Invoke-Assign subsequence of process activities is embedded in the Switch activity.

    • Assign

      The Assign activity assigns the value of EBM to the input variable of the 'invoke' step that follows.

    • Invoke

      The Invoke activity makes the service-call on the partner-link. The programming model for the ABCS extension points sets up a contract on the service to return the same payload that it receives.

    • Assign

      The Assign activity assigns the value of the response payload from the service invocation to variable of the process activity that follows.

    Figure 13-8 illustrates the sequence:

Figure 13-8 Setting up the Extension Point Pre-process EBM

The image is described in the surrounding text

13.1.11 How to Test the Extensibility with Servlet as Sample Extension Service

The sample extension service used in the document is a java servlet that mirrors the input payload back. The Servlet (shown in Example 13-2) as the endpoint has the advantage that it can be used as a partner-link service to test any extension. This is useful when you must test any extension-aware ABCS that have PartnerLink services defined using Abstract WSDL.

Example 13-2 Servlet to test extension

<service name="CreateCustomerSiebelReqABCSImplExt">
<port name="CreateCustomerSiebelReqABCSImplExt" 
binding="tns:CreateCustomerSiebelReqABCSImplExt_Binding">
               <soap:address 
location="http://{host}:{port}/MirrorServlet/mirror"/>
           </port>
    </service>

The implementations for the methods PreProcessABM are not required; the SOAP request is treated as the Servlet payload, and the Servlet outputs back the entire payload. The SOAPAction element is also rendered a dummy since it is not used at the Servlet-side.

The test Servlet is a java file with name Mirror.java. When deployed, it is accessible at: http://[hostname].com:[portno]/Mirror/mirror

13.2 Handling Errors and Faults

To determine how faults are handled and passed by a participating application, you must make sure the application error handling capabilities are in line with the integration platform's error handling capabilities.

13.2.1 How to Handle Errors and Faults

  • In synchronous request-response message exchange patterns (MEPs), the requesting services are waiting for response.

    Whenever an error occurs in the provider services, an exception is raised and the fault message is propagated back to the requesting service.

  • In asynchronous fire-and-forget MEPs, the requesting service does not expect a response.

    If an error occurs in the providing service, compensation may be needed. In such situations, the compensatory operations in EBS must be used for triggering compensations.

  • In asynchronous request-delayed response MEPs, the requesting service is in a suspended mode, waiting for a response.

    If an error occurs in the providing service, the response to the requesting service includes details about the error.

    For details on implementing the ABCS and EBS services in this scenario, see Section 12.5, "Implementing the Asynchronous Request Delayed Response MEP."

    For more information about implementing error handling in BPEL and Mediator processes in each of the MEPs, see Chapter 24, "Configuring Oracle AIA Processes for Error Handling and Trace Logging".

  • In an asynchronous MEP, the message initiated from a sender is persisted until it is successfully delivered to and acknowledged by the receiver, if an acknowledgment is expected.

    The sender and receiver are not necessarily the participating applications. Rather, they can be logical milestones in an Oracle AIA integration scenario. Each persistence store represents a milestone and may be a database, file system, or JMS persistence. Multiple milestones may be configured in an integration scenario to ensure the movement of messages from one persistence point to another.

    For more information about configuring milestones for Guaranteed Message Delivery in an Integration flow, see Chapter 24, "Configuring Oracle AIA Processes for Error Handling and Trace Logging".

13.3 Working with Adapters

This section discusses working with transport and version adapters.

This section includes the following topics:

13.3.1 Interfacing with Transport Adapters

Use transport adapters to interface with the ABCS in these scenarios:

  • For packaged applications, such as Siebel, PeopleSoft, J.D. Edwards, and SAP, the preferred route is to use the respective packaged-application adapters. These adapters can be deployed as JCA resource adapters. This solution is better than using the conventional SOAP interface.

  • In situations for which the participating applications do not expose their business logic as Web services, interactions with these applications must occur using technology adapters such as database adapters, JMS adapters, and so forth.

Transport adapters allow connectivity to the systems/applications that were not originally developed using Web services technologies. Some examples of applications that can use adapters are:

  • Systems that use non-xml for communication

  • Packaged software

  • Database systems

  • Data sources or persistent stores such as JMS, and so on

Investigate whether or not the services exposed by the participating applications provide support for proprietary message formats, technologies, and standards. If the applications that implement the functionality do not have inherent support for standards and technologies such as XML, SOAP, and JMS, then the transformations must happen in the ABCS.

For example, the application might be able to receive and send messages only using files, and EDI is the only format it recognizes. In this case, the ABCS is responsible for integrating with the application using a file adapter, translating the EDI-based message into XML format, exposing the message as a SOAP message.

When to Use Adapters for Message Aggregation

In some situations, you must combine responses to a request that originated from multiple sources. For example, for convergent billing in the telecommunication solution, the Application Business Connector Service for the getBillDetails EBS might have to retrieve details from multiple participating applications.

For more information about the Message Aggregation design pattern, see Chapter 25, "Working with AIA Design Patterns".

When to Use Adapters for Event Aggregation

The Event Aggregation model provides a comprehensive methodology for the business use case in which events, entity, or message aggregation is needed. In such scenarios, multiple events are raised before the completion of a business message, and all such fine-grained message events are consolidated into a single coarse-grained event.

In such use cases, a requester ABCS is invoked by an event consumer adapter service, which feeds the requester ABCS with an aggregated event message.

For more information about the event aggregation design pattern, see Chapter 25, "Working with AIA Design Patterns".

13.3.2 How to Develop Transport Adapters

Here are the high-level steps from the ABCS perspective.

To develop JMS Consumer Adapter:

  1. Add JMS adapter in the Exposed Services swim lane.

  2. Configure the JMS adapter service with the help of Adapter Configuration wizard.

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

  4. Wire the BPEL component to the JMS adapter service.

  5. Wire the BPEL component to the Referenced Service.

  6. Open the BPEL component in design mode and add 'invoke activity' to invoke the JMS adapter partner link.

  7. Complete the coding for the BPEL process.

For more information about JMS Adapters, see Oracle Fusion Middleware Configuring and Managing JMS for Oracle WebLogic Server.

To develop Portal DB Adapter:

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

  2. Add DB adapter as external reference service in the References swim lane.

  3. Configure the adapter service with the help of Adapter Configuration wizard.

  4. Wire the BPEL component to the db adapter service.

  5. Open the BPEL component in design mode and add 'invoke activity' to invoke the db adapter partner link.

  6. Complete the coding for the BPEL process.

13.3.3 When to Put Adapters in a Single Composite

In principle, an ABCS composite is a component implemented along with other components and wires between those components. For example, you can implement a Requester ABCS composite using:

  • A BPEL process component representing the ABCS process flow.

  • BPEL or Mediator-based adapter components representing the adapters used or required by the process component.

  • Both the process component and the adapter components promoted as Services of the composite in which they are defined.

An ABCS and a TransportAdapter service can be in the same composite and when they are, the composite name is the same as that of the ABCS. Alternatively, you can develop an ABCS service and a TransportAdapter service as separate composites.

AIA recommends that you put adapters that are interfaced with ABCS in a different composite from that of ABCS when the same transport adapter service could be used with multiple ABCSs.

13.3.4 Planning Version Adapters

When service providers release a new version of an application service, you may need to have multiple versions of it running concurrently when the consumer code is migrated.

The version adapter allows the client request and response to consume a different release of a service and routes requests to the appropriate service endpoint based on the content.

Examples:

  • For assets, the view definition being used in integration is different between Oracle 11.5.10 and R12.

  • For payment authorization, the API name is different in Oracle 11.5.10 and R12.

Changes such as these between different versions of applications require a new adapter service to be created for each application version.

When the changes between different versions of applications are minor, introduce a version adapter, based on a Mediator component, between the existing connector service and the provider application, as shown in Figure 13-9:

Figure 13-9 Introducing a Version Adapter

The image is described in the surrounding text

This approach ensures that the connector service remains agnostic of the version of the applications. This option should be considered when no transformations are needed or when input and output transformations in the version adapter are simple and do not involve extensive logic affecting the performance.

13.3.5 How to Configure a Version Adapter

To configure a version adapter:

The version adapter service is a mediator-based component that sits between the provider ABCS implementation service and the actual participating applications.

The mediator-based version adapter service should have references to all the application adapters:

  1. Configure the routing rules in the version adapter to route to corresponding adapter services of the applications.

  2. For each of the connecting application's adapters, two routing rules should exist to enable both content-based routing and property-based (from AIAConfiguration file) routing.

  3. When the changes between different application versions are minor with regard to the content to be passed and the content is already available in the transformed ABM, use a transformation map to transform the input of the version adapter to the corresponding adapter service of the provider application.

  4. Map the response from the different adapters to the schema that the connector service is expecting.

13.4 Developing ABCS for CAVS Enablement

This section provides instructions on how to develop Oracle AIA services that are ready to work with the Composite Application Validation System (CAVS). This section includes the following topics:

Tip:

CAVS configurations are only required when simulators are a part of the testing scenario. These configurations lay the foundation for allowing services to route messages to simulators.

For more information about using the CAVS, see Oracle Application Integration Architecture Foundation Pack: Infrastructure Components and Utilities Guide, "Working with the CAVS."

13.4.1 How to CAVS Enable Provider ABCS

Provider ABCSs that are asynchronous and invoke a callback to a ResponseEBS service must also CAVS-enable that invocation.

Developers must populate a value for the property: Routing.<PartnerLinkName>.<TargetSystemID>.EndpointURI as shown below.

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

To code a provider ABCS for dynamic CAVS-enabled PartnerLinks for invoking target participating application Web services:

  1. Define the following service-level configuration properties for the provider ABCS as shown in Example 13-3:

    Example 13-3 Defining service-level configuration properties for the provider ABCS

    <Property name="Default.SystemID">[DefaultTargetSystemID]</Property>
    <Property name="Routing.[PartnerlinkName].RouteToCAVS">[true|false]</Property>
    <Property 
    name="Routing.[PartnerlinkName].[TargetSystemID].EndpointURI">[AppEndpointURL]<
    /Property>
    <Property name="Routing.[PartnerlinkName].CAVS.EndpointURI">[CAVSEndpointURL]</Property>
    
    

    The CAVSEndPointURL value is set at design time.

    For more information about the design-time designation of the CAVSEndPointURL, see Section 13.4.3, "Introduction to the CAVSEndpointURL Value Designation".

  2. Ensure that you have the following namespace prefixes defined in your BPEL process as shown in Example 13-4:

    Example 13-4 Defining namespace prefixes in the BPEL process

    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:wsa=http://schemas.xmlsoap.org/ws/2003/03/addressing
    xmlns:corecom=http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2
    
    
  3. Add this variable to your global variables section:

    <variable name="SystemID" type="xsd:string"/>
    
  4. Add an attachment named AddTargetSystemID.xsl to your BPEL project in the 'xsl' directory. Be sure to replace the [ABCServiceNamespace] and [ABCServiceName] tokens in the file appropriately.

  5. Add the assignment shown in Example 13-5 as the first step in the BPEL process. Be sure to replace the tokens appropriately:

    Example 13-5 Adding an assignment

    <assign name="GetTargetSystemID">
        <copy>
            <from expression="ora:processXSLT('AddTargetSystemID.xsl', 
    bpws:getVariableData('[RequestEBMVariableName]', '[RequestEBMPartName]'))"/>
            <to variable="[RequestEBMVariableName]"
                part="[RequestEBMPartName]"/>
        </copy>
        <copy>
            <from variable="[RequestEBMVariableName]"
                  part="[RequestEBMPartName]"
                  query="/[NamespacePrefixedEBMName]/corecom:EBMHeader/corecom:
                   Target/corecom:ID"/>
            <to variable="SystemID"/>
        </copy>
    </assign>
    
    
  6. Add the following <scope> as shown in Example 13-6 once for each PartnerLink before its invoke activity:

    1. Replace the tokens in the AssignDynamicPartnerlinkVariables assignment activity to set the variables appropriately.

    2. Update the PartnerLink name token in the AssignPartnerlinkEndpointReference assignment activity.

    3. Updating the embedded Java code should not be necessary.

      Example 13-6 Adding <scope> for each PartnerLink

      <scope name="SetDynamicPartnerlinkScope">
          <variables>
              <variable name="TargetEndpointLocation" type="xsd:string"/>
              <variable name="EndpointReference" element="wsa:EndpointReference"/>
              <variable name="ServiceName" type="xsd:string"/>
              <variable name="PartnerLinkName" type="xsd:string"/>
              <variable name="EBMMsgBpelVariableName" type="xsd:string"/>
              <variable name="EBMMsgPartName" type="xsd:string"/>
          </variables>
          <sequence name="SetDynamicPartnerlinkSequence">
              <assign name="AssignDynamicPartnerlinkVariables">
                  <copy>
                      <from expression="'{[ABCServiceNamespace]}[ABCServiceName]
                       '"/>
                      <to variable="ServiceName"/>
                  </copy>
                  <copy>
                      <from expression="'[PartnerlinkName]'"/>
                      <to variable="PartnerLinkName"/>
                  </copy>
                  <copy>
                      <from expression="'[RequestEBMVariableName]'"/>
                      <to variable="EBMMsgBpelVariableName"/>
                  </copy>
                  <copy>
                      <from expression="'[RequestEBMPartName]'"/>
                      <to variable="EBMMsgPartName"/>
                  </copy>
              </assign>
              <bpelx:exec name="GetTargetEndpointLocation" language="java"
                          version="1.5">
                  <![CDATA[/*------------------------------------------------------
      This code snippet will derive the dynamic endpoint URI for a partnerlink.
      -----------------------------------------------------------------*/
      
      java.lang.String serviceName = (java.lang.String)getVariableData("ServiceName"); 
      java.lang.String partnerLinkName = (java.lang.String)getVariableData("PartnerLinkName");
      java.lang.String cavsEndpointPropertyName = 
      "Routing."+partnerLinkName+".CAVS.EndpointURI";
      java.lang.String ebmMsgBpelVariableName = (java.lang.String)getVariableData("EBMMsgBpelVariableName");
      java.lang.String ebmMsgPartName = 
      (java.lang.String)getVariableData("EBMMsgPartName");
      java.lang.String systemIdBpelVariableName = "SystemID";
      java.lang.String targetEndpointLocationBpelVariableName = 
      "TargetEndpointLocation";
      java.lang.String routeToCavsPropertyName = 
      "Routing."+partnerLinkName+".RouteToCAVS";
      java.lang.String defaultSystemIdPropertyName = "Default.SystemID";
      java.lang.String targetEndpointLocation = null;              
      java.lang.String targetID = null;
      boolean addAudits = false;
      
      if (addAudits) addAuditTrailEntry("Partnerlink = " + partnerLinkName);
      
      // check configuration for CAVS routing flag
      try {        
          boolean routeToCAVS = 
      java.lang.Boolean.parseBoolean(oracle.apps.aia.core.config.Configuration.
      getServiceProperty(serviceName, routeToCavsPropertyName));
          if (addAudits) addAuditTrailEntry("RouteToCAVS = " + routeToCAVS);
          if (routeToCAVS) {
              targetEndpointLocation = oracle.apps.aia.core.config.Configuration.
               getServiceProperty(serviceName, cavsEndpointPropertyName);        
              if (addAudits) addAuditTrailEntry("Endpoint = '" + targetEndpoint
               Location + "' selected from configuration property " + 
      cavsEndpointPropertyName);           
          }
      }     
      catch (oracle.apps.aia.core.config.PropertyNotFoundException e) {
          if (addAudits) addAuditTrailEntry("Configuration property " + cavs
      EndpointPropertyName + " not found!");
      }
      
      if (targetEndpointLocation==null || targetEndpointLocation=="") {
      
          // check bpel variable for already retrieved target system Id
          try {
              targetID = (java.lang.String)getVariableData(systemIdBpel
               VariableName);
              if (addAudits && targetID!=null) addAuditTrailEntry("Using previously 
      stored Target System ID = '" + targetID + "'");
          }
          catch (com.oracle.bpel.client.BPELFault e) {
          }
      
          if (targetID==null || targetID=="") {
              // try to get Target system ID from EBM Header
              try {           
      oracle.xml.parser.v2.XMLElement targetIdElement =
       (oracle.xml.parser.v2.XMLElement)
      getVariableData(ebmMsgBpelVariableName, 
      ebmMsgPartName, "/*/corecom:EBMHeader[1]/corecom:Target/corecom:ID
      [text()!='']");
                  targetID = targetIdElement.getText();          
                  if (addAudits) addAuditTrailEntry("Target System ID = '" + targetID 
      + "', selected from EBM header");           
              }    
              catch (com.oracle.bpel.client.BPELFault e) {
                  if (addAudits) addAuditTrailEntry("Unable to retrieve Target System 
      ID from message header");           
              }
              try {
                  if (targetID!=null && targetID!="") 
      setVariableData(systemIdBpelVariableName, targetID);
              }
              catch (com.oracle.bpel.client.BPELFault e) {
              }
          }
      
          if (targetID==null || targetID=="") {
              // try to get Target system ID from configuration
              try {
                  targetID = oracle.apps.aia.core.config.Configuration.getService
                   Property(serviceName, defaultSystemIdPropertyName);
                  if (addAudits) addAuditTrailEntry("Target System ID = '" + targetID 
      + "', selected from configuration property " + defaultSystemIdPropertyName);
              }
              catch (oracle.apps.aia.core.config.PropertyNotFoundException e) {
                  if (addAudits) addAuditTrailEntry("Configuration property " 
      + defaultSystemIdPropertyName + " not found!");           
              }
              try {
                  if (targetID!=null && targetID!="") setVariableData(systemIdBpel
                   VariableName, targetID);
              }
              catch (com.oracle.bpel.client.BPELFault e) {
              }
          }
       
          if (targetID!=null || targetID!="") {
              // try to get EndpointLocation from Configuration
              java.lang.String endpointPropertyName = "Routing."+partnerLinkName+
               "."+targetID+".EndpointURI";
              try {            
                  targetEndpointLocation =
      oracle.apps.aia.core.config.Configuration.getServiceProperty(serviceName, 
      endpointPropertyName);             
                  if (addAudits) addAuditTrailEntry("Endpoint = '" + 
      targetEndpointLocation + "' selected from configuration property " + 
      endpointPropertyName);
              }    
              catch (oracle.apps.aia.core.config.PropertyNotFoundException e) {
                  if (addAudits) addAuditTrailEntry("Configuration property " + 
      endpointPropertyName + " not found!");
              }
          }
      }
       
      try {
          setVariableData(targetEndpointLocationBpelVariableName, targetEndpoint
           Location);
      }
      catch (com.oracle.bpel.client.BPELFault e) {
      }]]>
              </bpelx:exec>
              <switch name="Switch_SetEndpoint">
                  <case condition="string-length(bpws:getVariableData('Target
                   EndpointLocation'))>0">
                      <assign name="AssignPartnerlinkEndpointReference">
                          <copy>
                              <from>
                                  <wsa:EndpointReference xmlns:wsa="http://schemas.
                                   xmlsoap.org/ws/2003/03/addressing">
                                      <wsa:Address/>
                                  </wsa:EndpointReference>
                              </from>
                              <to variable="EndpointReference"/>
                          </copy>
                          <copy>
                              <from variable="TargetEndpointLocation"/>
                              <to variable="EndpointReference"
                                  query="/wsa:EndpointReference/wsa:Address"/>
                          </copy>
                          <copy>
                              <from variable="EndpointReference"/>
                              <to partnerLink="[PartnerlinkName]"/>
                          </copy>
                      </assign>
                  </case>
                  <otherwise>
                      <empty name="Empty_NoSetEndpoint"/>
                  </otherwise>
              </switch>
          </sequence>
      </scope>
      

13.4.2 How to CAVS Enable the Requester ABCS

The general programming model concept is similar to how the endpoint URI is dynamically computed in the provider ABCS to achieve dynamic target invocation.

To code a requester ABCS for CAVS-enabled invocation of an Enterprise Business Service that is implemented as mediator service:

  1. In the BPEL artifact, add a switch activity.

  2. The condition expression in the 'case' tests for the nonzero value in the element EBMHeader/MessageProcessingInstruction/DefinitionID.

  3. Populate the wsa:EndpointReference element with the value of the element EBMHeader/MessageProcessingInstruction/DefinitionID as shown in Example 13-7.

    Example 13-7 Populating the wsa:EndpointReference element

    <switch name="Switch_CAVSEnablement">
    <case condition="string-length(bpws:getVariableData('CreateCustomerPartyList_
    InputVariable','CreateCustomerPartyListEBM','/custpartyebo:CreateCustomerPartyLis
    tEBM/corecom:EBMHeader/corecom:MessageProcessingInstruction/corecom:DefinitionID'
    ))>0">
                    <bpelx:annotation>
                        <bpelx:pattern>Is_CAVS_DefinitionID</bpelx:pattern>
                    </bpelx:annotation>
                    <sequence>
                        <assign name="Assign_TargetEndpointLocation">
                            <copy>
                                <from variable="CreateCustomerPartyList_
    InputVariable"
                                      part="CreateCustomerPartyListEBM"
                                      query="/ 
    corepartyebo:CreateCustomerPartyListEBM/corecom:EBMHeader/corecom:Message
    ProcessingInstruction/corecom:DefinitionID"/>
                                <to variable="TargetEndpointLocation"/>
                            </copy>
                        </assign>
                        <assign name="AssignPartnerlinkEndpointReference">
                            <copy>
                                <from>
                                    <wsa:EndpointReference>
                                        <wsa:Address/>
                                    </wsa:EndpointReference>
                                </from>
                                <to variable="EndpointReference"/>
                            </copy>
                            <copy>
                                <from variable="TargetEndpointLocation"/>
                                <to variable="EndpointReference"
                                    query="/wsa:EndpointReference/wsa:Address"/>
                            </copy>
                            <copy>
                                <from variable="EndpointReference"/>
                                <to partnerLink="SamplesCustomerPartyEBS"/>
                            </copy>
                        </assign>
                    </sequence>
                </case>
                <otherwise> <empty name="Empty_NoSetEndpoint"/> </otherwise>
            </switch>
    

    Tip:

    Some requester ABCSs must communicate back directly with the calling participating application. For this type of partnerlink, the requester ABCS acts similarly to a provider ABCS because it is invoking a participating application Web service.

13.4.3 Introduction to the CAVSEndpointURL Value Designation

The CAVSEndPointURL value is set at design time as follows:

  • If the ABCS or Enterprise Business Flow (EBF) is invoking a synchronous service, then the CAVSEndPointURL value in the AIAConfigurationProperties.xml file is set to a default value of: http://<host>:<port>/AIAValidationSystemServlet/syncresponsesimulator

  • If the ABCS or EBF is invoking an asynchronous one-way service, then the CAVSEndPointURL value in the AIAConfigurationProperties.xml file is set to a default value of: http://<host>:<port>/AIAValidationSystemServlet/asyncrequestrecipient

  • If the ABCS or EBF is invoking an asynchronous request-delayed response service, then the CAVSEndPointURL value in the AIAConfigurationProperties.xml file is set to a default value of: http://<host>:<port>/AIAValidationSystemServlet/asyncresponsesimulator

  • If the ABCS or EBF is invoking a Response EBS, then the CAVSEndPointURL value in the AIAConfigurationProperties.xml file is set to a default value of: http://<host>:<port>/AIAValidationSystemServlet/asyncresponserecipient

13.4.4 Purging CAVS-Related Cross-Reference Entries to Enable Rerunning of Test Scenarios

When a participating application is involved in a CAVS testing flow, execution of tests can potentially modify data in a participating application. Therefore, consecutive running of the same test may not generate the same results. The CAVS is not designed to prevent this kind of data tampering because it supports the user's intention to include a real participating application in the flow. The CAVS has no control over modifications that are performed in participating applications.

However, this issue does not apply if your CAVS test scenario uses test definitions and simulator definitions to replace all participating applications and other dependencies. In this case, all cross-reference data is purged once the test scenario has been executed. This enables rerunning of the test scenario.

This purge is accomplished as follows:

  1. Process integration packs (PIPs) that are delivered to work with Oracle AIA Foundation Packs are delivered with cross-reference systems in place. They are named CAVS_<XYZ>, where <XYZ> is the participating application system. For example, for systems EBIZ and SEBL, the PIP is delivered with cross-reference systems CAVS_EBIZ and CAVS_SEBL.

  2. For every system type defined on the System - Application Registry page for which you want to make test scenarios rerunnable (<XYZ>), create a related CAVS system (CAVS_<XYZ>). The System Type field value for the CAVS-related entry should match the name of the system for which it is created. To access the System - Application Registry page, access the AIA Home Page, click Go in the Setup area, and select the System tab. Figure 13-10 illustrates the system and CAVS-related entries.

    Figure 13-10 System and CAVS-related System Entries on the System-Application Registry Page

    The image is described in the surrounding text
  3. When testing a provider ABCS in isolation, the EBM is passed from the CAVS to the provider ABCS with the NamespacePrefixedEBMName/EBMHeader/Target/ID element set as CAVS_<XYZ>.

  4. When testing a requester ABCS in isolation, the element in the Application Business Message (ABM) that normally contains the Internal ID value now contains the CAVS-specific Internal ID value set for the system on the System - Application Registry page.

  5. When testing an entire flow (requester ABCS-to-EBS-to-provider ABCS), you must set the Default.SystemID property of the provider ABCS to CAVS_<XYZ>, where <XYZ> is the system.

    To do this, edit the Default.SystemID property value in the AIAConfigurationProperties.xml file in the $AIA_HOME/aia_instances/$INSTANCE_NAME/AIAMetaData/config directory.

    Access the Configuration page and click Reload to load the edit.

    You can now begin testing the entire flow.

    Note:

    If the test scenario is an entire flow that includes multiple instances of the same system, then the approach described previously will not work. In this case, data created in the cross-reference will remain, making the same test case incapable of being rerun.

13.5 Securing the ABCS

The participating applications are developed during different times with different concepts and implementation of authentication and authorization. When applications are integrated, you must pass authentication and authorization information between applications.

The information related to security is exchanged between participating applications and ABCS. The AIA application security context standardizes the exchange of participating applications' authentication and authorization information between various applications so that any application can be integrated with any other application.

13.5.1 How to Secure the ABCS

You should answer the following questions:

  • Does the application need the security credentials to authenticate?

    If yes, can you use a generic account or should you use the requester's credentials, as specified in the message?

  • How are these credentials transmitted? Are they adopting a WS-Security scheme or a custom mechanism?

    If a custom mechanism, is it through the header or as part of the payload?

Refer to Chapter 26, "Working with Security" for details about how to:

  • Transform application security context into standard format in ABCS.

  • Propagate the standard security context from ABCS to ABCS through EBS and EBF.

  • Transform standard security context to application security context.

13.6 Enabling Transactions

When SOA is used to encapsulate and integrate cross-enterprise workflows, multiple services may take part in transactions spanning system boundaries. End-to-end business transactions that cross application boundaries involve multiple applications. Creating robust integration solutions requires more than simply exchanging messages.

An important consideration is that the Web services participating in an end-end message flow are often asynchronous, stateless, distributed, and opaque. You must understand the mechanics of transaction management.

13.6.1 How to Ensure Transactions in AIA Services

Business requirements drive transactional requirements. Transaction considerations must start during the design phase. You cannot postpone them until construction time. You must:

  • Identify all the ABCS services and the EBFs that comprise a business activity.

  • Organize these activities into meaningful groups to have an overall unifying purpose.

  • Indicate transaction demarcation points.

The grouping of activities provides the starting point for transaction demarcation so that the relevant business operations are performed in the context of a transaction.

In the asynchronous fire-and-forget pattern, where no milestones are configured, the requester, EBS, and provider ABCS must participate in the same global transaction, including cross-references in Oracle XA.

In an asynchronous MEP, where JMS queues are set up and the participating applications interact with the queues, the JMS consumer adapters must also participate in the global transaction, as do the requester ABCS, EBS, and provider ABCS.

In such a case, when an undergoing transaction is aborted before the message is persisted at a milestone, the message is rolled back into the JMS queue.

In other words, the transaction demarcation begins with the JMS consumer adapter picking up the message from the queue and ends when the message is delivered to the consumer application or when the message is persisted at a configured milestone.

In a SOA-based integration, long-running business transactions often involve incompatible trust domains, asynchrony, and periods of inactivity, which present challenges to traditional ACID-style transaction processing. You may need to predefine the transaction boundaries based on technical or business criteria. PIP designers/architects should divide the whole transaction into parts by setting transaction boundaries using JMS interface at logical points.

Non-retryable application services must have corresponding compensatory services.

ABCS invoking non-retryable application services should invoke compensatory services in case of roll-back.

Application services implemented using JCA adapters can leverage session management to facilitate transaction coordination.

13.6.2 Transactions in Oracle Mediator

If a transaction is present, Oracle Mediator participates in that existing transaction. If a transaction is not present, Oracle Mediator starts a transaction. In the case of sequential routing rules, all rules are executed in the same transaction and, if an error occurs, a rollback is issued.

13.6.3 Transactions in BPEL

The BPEL component, by default, creates a new transaction on the basis of a request. That is, when a BPEL process is invoked, a new transaction begins by default. If a transaction already exists, then it is suspended and a new one created. To chain an execution into a single global transaction, you must set the transaction flag on the provider process (callee BPEL component).

13.6.3.1 Impact of BPEL Activities on Transaction Scope

BPEL engine ends its local transaction when it reaches the end of flow or hits a breakpoint activity, for example, receive, onMessage, onWait, and Alarm.

Transaction design considerations are also governed by:

  • Invocation patterns employed across the AIA integration

    ABCS -- EBS - ABCS

  • Technology pattern: BPEL -- MEDIATOR-BPEL

    ABCS - EBS - EBF - EBS -- ABCS

  • Technology Pattern: BPEL - MEDIATOR- BPEL - MEDIATOR- BPEL

    Based on the transaction semantics in FMW, you must design and configure transactions across ABCS, EBS and Enterprise Business Flows.

  • Participating applications

    Participating applications should be able to support transactions using their application services. However, the reality is that many application services are able to do this, so compensatory services are needed in case of rollback (orchestrated by AIA layer).

    Design integration logic and transaction boundaries in the AIA layer to account specifically for the peculiarities of the participating application services, SCA Composite transaction semantics, and business requirements.

13.6.4 Developing ABCS to Participate in a Global Transaction

In SOA 11g, you do not need to set up any configuration properties on the calling (consuming) process to chain an execution into a single global transaction.

You only need to set the appropriate transaction flag on the Callee BPEL component. You can do this in the composite editor's source by adding bpel.config.transaction into a BPEL component, with value as 'required' as shown in Example 13-8:

Example 13-8 Setting the transaction flag on the callee BPEL component

<component name="SamplesCreateCustomerSiebelReqABCSImplProcess">
    <implementation.bpel  
src="SamplesCreateCustomerSiebelReqABCSImplProcess.bpel"/>
    <property name="bpel.config.transaction">required</property>


</component>

With the transaction flag set as shown, BPEL inherits the transaction that is already there, started by the parent process. If the parent process has not started a transaction, BPEL creates a new one. For a global transaction, the transaction is committed when the initiator commits.

If BPEL has an inbound interface with an adapter, you must set the appropriate transaction flag in the composite of the adapter.

Example 13-9 shows how transaction properties should be set on the BPEL adapter interface:

Example 13-9 Setting transaction properties on the BPEL adapter interface

<component name="SamplesCreateCustomerSiebelJMSConsumerProcess">
     <implementation.bpel 
src="SamplesCreateCustomerSiebelJMSConsumerProcess.bpel"/>
        <property name="bpel.config.transaction">required</property>


</component>

In the case of BPEL invoking Mediator, the Mediator participates in the existing transaction if a transaction is present. If a transaction is not present, then Mediator starts a transaction.

13.6.5 How to Transaction-Enable AIA Services

The following sections provide details on how to transaction enable AIA services in different scenarios:

13.6.5.1 Synchronous Request-Response Scenarios

Invoking a synchronous BPEL process results in creation of BPEL instance within its local transaction by default. This transaction can be enlisted to a global transaction given proper configurations.

Hence, the transaction settings in the ABCS services should be as shown in Example 13-10:

Example 13-10 Transaction Settings in the composite.xml of the RequesterABCS

<component name="SamplesCreateCustomerSiebelJMSConsumerProcess">
     <implementation.bpel 
src="SamplesCreateCustomerSiebelReqABCSImplProcess.bpel"/>
        <property name="bpel.config.transaction">required</property>

</component>

This setting ensures that the caller's transaction is joined, if there is one, or a new transaction is created when there is not one.The EBS inherits the transaction initiated by the Requester ABCS.

A Mediator always enlists itself into the global transaction propagated through the thread that is processing the incoming message.

Figure 13-11 illustrates the transaction boundary.

Figure 13-11 Transaction Boundary

The image is described in the surrounding text

13.6.5.2 AIA Services in Asynchronous MEP

Invoking an asynchronous BPEL process results in persistence of invocation message in invoke message table within part of the caller's transaction. The Caller's transaction ends. The asynchronous BPEL executes in its own local transaction. For the Callee to be executed within the Caller's transaction, the transaction flag must be set to required, as shown below, for the BPEL component, in the Callee's composite.

bpel.config.transaction=required

To ensure a single threaded execution of the Callee, a case of a one-way operation, you must have a sync-type call. Set the property for the BPEL component in the Callee's composite as shown below:

bpel.config.oneWayDeliveryPolicy=sync

Therefore, the transaction settings in the ABCS services should be as shown in Example 13-11:

Example 13-11 Transaction settings for asynchronous MEP

<component name="SamplesCreateCustomerSiebelReqABCSImplProcess">
     <implementation.bpel 
src="SamplesCreateCustomerSiebelReqABCSImplProcess.bpel"/>
        <property name="bpel.config.transaction">required</property>
   <property name=bpel.config.oneWayDeliveryPolicy">sync</property>

If the Requester ABCS has an inbound interface with an adapter, then in the adapter's composite, set the property at the BPEL component level, that is, bpel.config.oneWayDeliveryPolicy=sync.

Example 13-12 shows how transaction properties are set on the adapter component:

Example 13-12 Transaction properties set on adapter component

<component name="SamplesCreateCustomerSiebelJMSConsumerProcess">
     <implementation.bpel 
src="SamplesCreateCustomerSiebelJMSConsumerProcess.bpel"/>
        <property name="bpel.config.transaction">required</property>
   <property name=bpel.config.oneWayDeliveryPolicy">sync</property>
</component>

Figure 13-12 illustrates the transaction boundary.

Figure 13-12 Transaction Boundary in Asynchronous MEP

The image is described in the surrounding text

13.6.5.3 Asynchronous Operation from an ABCS in the Same Thread but in a Different Transaction

When an ABCS has to invoke an asynchronous operation on a process, which must be executed in the same thread as that of ABCS but in a different transaction, set the following configuration in the called BPEL composite:

<property name="bpel.config.oneWayDeliveryPolicy">sync</property>

Note that, in this case, the transaction configuration, bpel.config.transaction, need not be set in the called BPEL composite because the called BPEL should be executed in a transaction different from that of the Caller.

13.7 Guaranteed Message Delivery

Guaranteed message delivery means that a message being sent from a producer to a consumer is not lost in the event of an error.

AIA uses queues for asynchronous and reliable delivery of messages. For example,

  • PeopleSoft CRM, upon occurrence of a business event, can either push the message directly into a queue or send a SOAP message over HTTP to a JMS message producer (a JMS transport adapter) that is responsible for entering the message in the queue.

    PeopleSoft CRM can consider the message as sent as soon as the message is dropped into the queue. With this mechanism, the PeopleSoft CRM application can keep sending new messages regardless of whether the CRM on Premises is available or not.

  • A JMS consumer (another JMS transport adapter) is responsible for dequeuing the messages and invoking PeopleSoft CRM ABCSs.

    Having the PeopleSoft CRM ABCSs, the EBS, the CRM on Premises ABCS and the Web services as part of the transaction initiated by JMS message producer ensures that the message is removed from the queue only after the successful completion of the task in the CRM on-premise application.

13.8 Versioning ABCS

Versioning of a service means:

  • A new service with Version suffix in the name of the Composite and name of the Service Component.

  • The target namespace of the WSDL of the Service Component indicates a new version.

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

13.8.1 Guidelines for Versioning

During the preparatory phase, be aware of the following guidelines:

  • An ABCS is used across multiple PIPs. It is not PIP-specific.

    For example, EBizRequesterCreateItemABCS is used by ISCM PIP as well as Agile PLM - Ebiz Integration PIP.

  • Use the Oracle Enterprise Repository to discover the existence of a service.

    Service definition annotations are persisted in Oracle Enterprise Repository. Oracle Enterprise Repository documents the various conceptual and physical assets depicting the PIP and constituting services.

  • Inline changes made to ABCS without changing the version suffix should be backward compatible.

  • Multiple versions for a service with semantically and technically incompatible contracts among versions are not acceptable.

    It is not permissible to version an existing ABCS when the contract is totally different, even though the operation to be performed or the verb is same.

  • ABCS is versioned independently of an application version.

    ABCS is not bound to a specific application version. So, when an application undergoes a version change, it is not binding on ABCS to undergo a similar version change. Thus, ABCS is designed to be agnostic of version changes of the application.

  • Avoid concurrent multiple versions of an ABCS.

    For example, Team A owns Version 1; Team B does not like the contract and creates Version 2 with a different MEP/Contract. Now Team A is creating Version 3 with a contract that contradicts the previous one.

  • The system does not allow more than one service for an application to perform a single business activity using a specific role (Requester/Provider).

  • Do not have more than one service with same logic but different names, either a different name for composite, for service, or having a different portType in the WSDL.

  • Do not have more than one service with different logic but the same names.

The operation defined on the EBS determines the implementing ABCS.

The operation defined on an EBS is dictated by the business activity/business task.

Variations of business activity, business task, or both are possible. These are passed in the form of context and implemented by different ABCSs.

Multiple teams involved in producing, consuming, or both producing and consuming an ABCS for a specific application and a business activity must reach consensus regarding the contracts.