17 Completing ABCS Development

This chapter describes how to develop Application Business Connector Services (ABCS), handle errors and faults, work with adapters, develop ABCS for CAVS enablement, secure ABCS, enable transactions, enable message delivery and version ABCS, enable resequencing in Oracle Mediator and Layered Customizations.

This chapter includes the following sections:

17.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.

17.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 before the execution of transformation of application business message (ABM) to Enterprise Business Message (EBM). Use this configuration property name: ABCSExtension.PreXformABMtoEBM.

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

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

  4. Just before 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 before the execution of transformation of application business message (ABM) to EBM. Use this configuration property name: ABCSExtension.PreXformABMtoEBM.

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

For more information about configuration parameters, see Section 17.1.3.1, "Configuration Parameters."

Figure 17-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. The steps for executing the customer extension to do additional tasks are optional.

Figure 17-1 Extending the Request-Response Interaction Style

The image is described in the surrounding text

Figure 17-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. The steps for executing the customer extension to do additional tasks are optional.

Figure 17-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

17.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 before the execution of the EBM to ABM transformation. Use this configuration property name: ABCSExtension.PreXformEBMtoABM.

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

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

  4. Customer extension just before 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 before the execution of the EBM to ABM transformation. Use this configuration property name: ABCSExtension.PreXformEBMtoABM.

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

For more information about configuration parameters, see Section 17.1.3.1, "Configuration Parameters."

Figure 17-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 17-3 Provider-Specific ABCS Using Request-Response Interaction Style

The image is described in the surrounding text

Figure 17-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 17-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.

17.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 17-1 lists the service operations for the requester ABCS-specific extensibility points:

Table 17-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


Table 17-2 lists the service operations for the provider ABCS-specific extensibility points:

Table 17-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 runtime 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 17.6.1, "How to Ensure Transactions in AIA Services."

17.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.

17.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, multiple hooks exist 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 17-5:

Figure 17-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 17-6:

Figure 17-6 Example of Composite with One External Reference

The image is described in the surrounding text

17.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.

17.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 17-1.

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

    Example 17-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>
    

17.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'.

17.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 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.

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 2.1.3.4, "Using MDS in AIA."

17.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.

17.1.9 How to Set Up the Extension Point Pre-ProcessABM

When AIA Service Constructor is used to construct ABCS, the extension point is 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 17-7 illustrates the sequence:

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

    The image is described in the surrounding text

17.1.10 How to Set Up the Extension Point Pre-ProcessEBM

When AIA Service Constructor is used to construct ABCS, the extension point is 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 17-8 illustrates the sequence:

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

The image is described in the surrounding text

17.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 17-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 17-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

17.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.

17.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 16.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 27, "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 27, "Configuring Oracle AIA Processes for Error Handling and Trace Logging."

17.3 Working with Adapters

This section discusses working with transport and version adapters.

This section includes the following topics:

17.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 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 28, "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 28, "Working with AIA Design Patterns."

17.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.

17.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.

17.3.4 Planning Version Adapters

When service providers release a new version of an application service, you must 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 17-9:

Figure 17-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.

17.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 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.

17.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 "Introduction to the Composite Application Validation System" in Oracle Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack.

17.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 17-3:

    Example 17-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 17.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 17-4:

    Example 17-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 17-5 as the first step in the BPEL process. Be sure to replace the tokens appropriately:

    Example 17-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 17-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 17-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>
      

17.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 17-7.

    Example 17-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.

17.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

17.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 after the test scenario has been executed. This enables rerunning of the test scenario.

This purge is accomplished as follows:

  1. Pre-Built Integrations that are delivered to work with Oracle AIA Foundation Pack 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 Pre-Built Integration 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 17-10 illustrates the system and CAVS-related entries.

    Figure 17-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 does not work. In this case, data created in the cross-reference remains, making the same test case incapable of being rerun.

17.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.

17.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 29, "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.

17.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.

17.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 must predefine the transaction boundaries based on technical or business criteria. Pre-Built Integration 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.

17.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.

17.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 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).

17.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.

17.6.4 Developing ABCS to Participate in a Global Transaction

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

You only must 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 17-8:

Example 17-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 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 17-9 shows how transaction properties should be set on the BPEL adapter interface:

Example 17-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.

17.6.5 How to Transaction-Enable AIA Services

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

17.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 17-10:

Example 17-10 Transaction Settings in the composite.xml of the Requester ABCS

<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 17-11 illustrates the transaction boundary.

Figure 17-11 Transaction Boundary

The image is described in the surrounding text

17.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 17-11:

Example 17-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 17-12 shows how transaction properties are set on the adapter component:

Example 17-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 17-12 illustrates the transaction boundary.

Figure 17-12 Transaction Boundary in Asynchronous MEP

The image is described in the surrounding text

17.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>

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.

17.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.

17.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 32, "Oracle AIA Naming Standards for AIA Development."

17.8.1 Guidelines for Versioning

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

  • An ABCS is used across multiple Pre-Built Integrations. It is not Pre-Built Integration specific.

    For example, EBizRequesterCreateItemABCS is used by ISCM Pre-Built Integration and Agile PLM - Ebiz Integration Pre-Built Integration.

  • 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 Pre-Built Integration 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 multiple services for an application to perform a single business activity using a specific role (Requester/Provider).

  • Do not have multiple services 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 multiple services 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/task.

Variations of business activity, 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.

17.9 Resequencing in Oracle Mediator

This section provides an overview of the Requencing feature in Oracle Mediator and discusses how to set up and use it in the Oracle AIA Asynchronous message exchange pattern.

In the Oracle AIA asynchronous message exchange pattern, participating applications push messages to the Oracle AIA layer where they are processed in a store-and-forward fashion.

In this message exchange pattern, there is a need to process messages pertaining to the same object instance in the same sequence in which they are generated. The Resequencer in Oracle Mediator helps to maintain correct processing sequence.

A Resequencer is used to rearrange a stream of related but out-of-sequence messages back into order. It sequences the incoming messages that arrive in a random order and then send them to the target services in an orderly manner.

The sequence of messages is maintained until the next persistence point. If the next persistence point is not an application, then the messages must be resequenced again.

Consider an integration scenario where in the Siebel application is sending CreateOrder/UpdateOrder messages which are enqueued in JMS queue. These messages are de-queued by a JMS consumer adapter service and sent down stream for processing. When incoming messages arrive at JMS queue, they may be in a random order owing to different reasons such as network latency, downtime of server and so on. The resequencer orders the messages based on sequential or chronological information, and then sends the message to the target services in an orderly manner.

The Figure 17-13 depicts an usecase where an incoming stream of messages from Siebel application which are persisted in a JMS destination are processed in a correct sequence.

Figure 17-13 Message Sequencing Using the Oracle Mediator's Resequencing Feature

The image is described in the surrounding text

The sequencing is done based on the sequencing strategy selected. The mediator provides us with three types of resequencers:

  • Standard Resequencer

  • FIFO Resequencer

  • BestEffort Resequencer

For more information about the Oracle Mediator Resequencer feature, see "Resequencing in Oracle Mediator" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

17.9.1 Configuring the Oracle Mediator Service to Use its Resequencer Feature

As this is a feature of the Oracle Mediator, a Mediator service must be in place for it to work as designed.

This section discusses how to configure the Oracle Mediator service to use its re-sequencing feature.

  • Open the Mplan file of the Mediator component in the design mode.

  • Select the 'Resequence Level' as 'operations'

Note:

Mediator allows us to select the Resequence Level as either 'operations' or 'component'. For Mediator components which only have a single operation, it does not matter whether you select Resequence Level as either 'operations' or 'component'. For a Mediator that has multiple operations defined on it, selecting the 'component' option means resequencing is applied to all operations in it.

In AIA, for the mediator, it is recommended to select the 'Resequence Level' as 'operations'. Figure 17-14 is the screen shot of a composite mplan where the Resequence level is selected at operation level.

Figure 17-14 Resequence Level is Selected at Operation Level

The image is described in the surrounding text

For the resequencer to work, have one or both of following values in the source payload depending on the resequencing strategy employed.

The first one is a sequenceID, and the next one is a groupID. The sequenceID is used as identifier for the message itself. The groupID is used to group the messages in which the resequencer rearranges the messages based on the sequenceID.

17.9.2 How to Configure the Resequencing Strategy

  1. Determine and set the Resequence type from the following three options:

    • Standard: Use when the incoming message has an integer as a sequence ID with a known increment and the starting sequence number.

    • BestEffort: Use when the incoming message has a timestamp as a sequence ID.

    • First in First out (FIFO): Use in all other cases.

    Figure 17-15 is the screenshot that shows Resequence types.

    Figure 17-15 Resequence Types

    The image is described in the surrounding text
  2. Set resequence options.

    1. Determine and set the Group

      The group ID is a parameter (field or attribute) on the incoming message that uniquely identifies the group of messages to be sequenced.

      For example, CustomerId, OrderId, ProductId, Account ID and so forth.

      The group ID is configured by setting the 'Resequence Options' called 'Group' with an XPath expression that points to the field in the payload which the resequencer uses to group incoming messages. This ensures that the messages belonging to a specific group are processed in a sequential order.

      For example, SyncCustomerPartyListEBM/ns0:SyncCustomerPartyListEBM/ns0:DataArea/ns0:SyncCustomerPartyList/ns0:CustomerPartyAccount/corecom:Identification/corecom:ApplicationObjectKey/corecom:ID[@schemeID='AccountId'].

      Figure 17-16 is the screenshot that shows XPath expression in the Group field.

      Figure 17-16 Resequence Options

      The image is described in the surrounding text
    2. Determine and set the ID

      The ID is a parameter (field or attribute) on the incoming message that indicates the position of the message in the sequence.

      The ID is declared by an XPath expression that points to the field in the incoming message on which the resequencing is done.

      For example, $in.SyncCustomerPartyAccountListEBM/ns0:SyncCustomerPartyAccountListEBM/ns0:DataArea/ns0:SyncCustomerPartyAccountList/ns0:CustomerPartyAccount/corecom:Identification/corecom:ApplicationObjectKey/corecom:ID /@schemeID

      Figure 17-17 is the screenshot that shows XPath expression in the ID field.

      Figure 17-17 Setting the ID Parameter

      The image is described in the surrounding text
    3. Set the Resequence Options for Best Effort Resequence Mode. The incoming messages cannot provide information to the resequencer about the identifier to use for sequencing. Typically, the identifier used for sequencing in such scenarios is of a dateTime type or numeric type. Using the dateTime field as the sequence ID XPath enables you to control the sequencing.

      Figure 17-18 is the screenshot that shows the option dateTime selected.

      Figure 17-18 Resequence Options for Best Effort Resequence Mode

      The image is described in the surrounding text

When a resequencer mediator service is placed between the JMS Consumer adapter service and the Requester ABCS, the message is removed from the JMS queue when it goes into resequencer so that transaction boundary is shifted to resequencer store.

17.9.3 Processing Multiple Groups Parallelly

The messages that arrive for resequencing are split into groups and the messages within a group are sequenced according to the ID selected resequencing strategy. Sequencing within a group is independent of the sequencing of messages in any other group. Groups in themselves are not dependent on each other and can be processed independently of each other.

For example, when the 'accountID' in Update Order message is used as group ID, the incoming Update Order messages that have the specific account ID are processed as a group independent of the Update Order messages that have a different account ID.

Resequencer helps maintain correct processing sequence up to the point that directly receives message from resequencer. The sequence is not guaranteed if a-synchronicity is introduced in the process that receives the re-sequenced messages. In other words, the sequence of messages is maintained till the next persistence point. After that the messages must be resequenced again.

17.9.4 Describing Oracle Mediator Resequencer Error Management

When a message for a group fails, message processing for that group is stopped and pending messages are held back. Error messages are placed in the Error Hospital for fixing and resubmission for all the errors that can be retried.

As all messages of same group id are processed by a single thread in different transactions. If a message fails to get processed, the rest of the messages for that group are suspended. So resubmit the message that has error. Processing resumes from next sequence only after you either retry or abort the message.

The processing of messages for other groups continues without interruption.

If a new message arrives for the group that has error, the messages get stored in the Resequencer store so that they not lost. When failed messages are resubmitted from the Oracle Enterprise Manager (OEM) Console or another tool, the associated group that has error is unlocked and normal processing resumes for that group.

17.9.4.1 Resubmitting Messages that have Errors

When a message cannot be delivered to a service or component in the flow of a global transaction, the message is rolled back to the appropriate source milestone. This source milestone corresponds to a Queue or topic or Resequencer. It is here that the message is persisted until it can be resubmitted for delivery to the service or component.

For Message Resubmission Utility to resubmit messages that have errors, the incoming messages must be first populated using Message resubmission parameters when they are de-queued from the source milestone using the JMS consumer.

For more details on how to populate these values in the incoming message, see Section 27.5.3.1, "Populating Message Resubmission Values."

17.9.4.2 Using the Message Resubmission Utility API

The Message Resubmission Utility API enables external programs to enable a message that is in error state to be consumed for a transaction. This utility is typically run to fix the problem that caused the message to end in error.

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

The message that generates an error is moved to the error hospital. The group is moved to an error state and is not picked up by the worker thread. You can resubmit the error-generating message using the error hospital. After you resubmit the message, the group is moved to a normal state, so that it can be picked up by the worker thread.

17.9.5 Tuning the Resequencer

The following parameters help you with turning the resequencer.

ResequencerWorkerThreadCount: The number of threads used by resequencers.

ResequencerMaxGroupsLocked: The maximum number of groups that can be locked by a thread.

The sleep interval: If your message frequency is high, set the sleep interval to low. It is desirable to set the number of groups locked to a value greater than the worker thread count so that worker threads are not idle. By default, the value of ResequencerMaxGroupsLocked and ResequencerWorkerThreadCount are set to same.

Note:

You cannot turn off the resequencer at runtime after you turn it on for a composite.

17.10 Developing Layered Customizations

Oracle application composites are created for specific industry needs. Oracle also provides options to further customize these components for business specific needs of individual organizations. Customization refers to modification of delivered artifacts to produce new behavior. You can use this option to customize the out-of-box composites delivered by Oracle and also and deploy them in place of original composites. When you customize a few composites, you create a specific solution for your organization.

However, these customizations can be overwritten when you apply a patch or upgrade when there is a new version. To ensure customization at a higher layer is not lost during an upgrade the customized layer and the base process are kept in their own metadata files. This externalization of customizations away from the base composite is possible only when the base version has been enabled for customization. Only when you want to deploy a solution the layers are merged with the base process for creating a single executable process.

For more information about layered customizations, see "Customizing SOA Composite Applications" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Can all the composites be customized?

For the services that are delivered in the certain set of Out of the Box Prebuilt Integration, customizable scopes have been added in the BPEL flow. Refer to your pre-built integration implementation guide to check whether your pre-built integration allows customization of services. You can add the custom logic in these scopes when you open the BPEL in JDeveloper using customization developer role. These customizations are kept separate from the base definition. The advantage of adding the custom logic in these scopes is that, the customization is safe when you upgrade. When you uptake the subsequent patches or new releases, they can merge these customizations on top of the new base definition and deploy the BPEL.

Pre-built integrations that do not have services containing customizable scopes cannot be customized.

Adhere to following guidelines while doing the customizations:

  • Customizations are allowed only for BPEL based AIA artifacts that have customizable scopes. Inline customizations done to any other artifacts are overwritten when you apply a patch or upgrade to a newer.

  • Do not customize a composite which is not marked as customizable because they encounter merge conflicts when the composite is patched at a later point in time.

  • Do not modify the out of the box defined variables or messages as these variables may have been used in the section following customized code resulting in adverse impact on the behavior of the BPEL flow.

17.10.1 Deploying services after customizations

To deploy a service after customization:

  1. Right click the customized composite in JDeveloper tree.

  2. Select Make<customized composite name>.jar to compile the changes.

  3. Open the CustomizeApp folder from the Jdeveloper work location.

    You can see the folder named merged that contains Out of the box code and Customized Code.

  4. Copy this merged folder to your server and deploy the composite using Application Deployment Driver.

    For instructions on how to deploy the changed services, see Chapter 8, "Generating Deployment Plans and Deploying Artifacts."

17.10.2 Customizing the Customer Version

If you want to customize customer version of the SOA composite application, see "Customizing the Customer Version" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

17.10.3 Applying patches after customization

To apply patches after you have customized, see "Upgrading the Composite" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite. Instructions here help you to apply layers to the new base composite.