10 Implementing Direct Integrations
This chapter provides an overview of direct integrations and describes the procedure for implementing direct integrations.
This chapter includes the following sections:
-
Section 10.2, "Using the Application Business Flow Design Pattern for Direct Integrations"
-
Section 10.5, "Enabling Outbound Interaction with Applications"
10.1 Understanding Direct Integrations
Oracle Foundation Pack helps organizations integrate their applications using common information model known as canonical model. Canonical Enterprise Business Objects (EBOs) work best in the integrations where integration flows involve connectivity with multiple source and destination systems. Canonical-based interfaces minimize close coupling between participating applications. This allows re-usability and increases the speed of deployment when new applications are added to the ecosystem.
However, every integration scenario does not require a canonical integration model. Foundation Pack components also provide support for application-to-application (direct) integration.
You must consider direct integration when:
-
There is only one application on each end of the integration.
-
There is requirement for fewer mappings.
-
The integration requires very low latency.
-
The integration is transformation-intensive and requires very high throughput (peaks at over 10,000 messages per hour - or 30 messages per second).
-
The integration is process-centric rather than data-centric.
-
The requester and the provider applications are not expected to change.
10.2 Using the Application Business Flow Design Pattern for Direct Integrations
A simple mode of communication between a consumer and a provider application or services is allowing them to interact directly with each other using the XML-based data structures, as specified by the provider or service.
The Application Business Flow (ABF) manages the integration flow and implements the following tasks necessary for integration:
-
The service receives the request from the client application and does data enrichment, if required.
Data Enrichment can be described as retrieving additional details from the client application.
-
The service makes calls to the provider using connectivity protocols.
The response received from the provider application is transformed into the client application format before returning the response to the client application.
The interface for the integration service is defined by requester / client application.
Note:
If you introduce any additional provider at a later time, you must add another ABF.
10.3 Finding the Correct Granularity
You can implement end-to-end integration flows either using a single ABF composite or multiple ABF composites, depending on your integration requirement. Consider the following when you design your integration flow.
-
Define and design reusable services if the functionality of the service could potentially be reused multiple times.
-
When some functionality, embedded in a service, is needed in multiple integration scenarios, re-factor it a separate ABF and create a service to reference it.
-
Optionally, use an ABF to invoke another ABF, as shown in Figure 10-1, if functionality is available as a separate service.
10.4 Handling Transactions
When an operation defined on an ABF service interface involves destructive writes to two or more resources then Oracle advises you to perform these tasks in a single transaction.
10.4.1 Building an ABF as a Transactional Composite
Design an ABF composite with transactional attributes set on it in the following scenarios:
-
Two different applications need to be updated and you want to avoid problems that occur when only one update is successful leading to inconsistency.
-
There is an existing global transaction context and the operations performed by your integration process service must be part of the global transaction.
-
An application has to send/receive a message and also has to do an update.
-
A group of related messages have to be processed in a batch mode.
10.4.2 Achieving Transactionality in the ABF
Create a common transaction context using two-phase commit to achieve transactionality.
The BPEL component creates a new transaction when a BPEL process is invoked. If a transaction already exists, BPEL suspends it and creates a new one. Set the transaction flag on the BPEL component to chain an execution into a single global transaction by adding bpel.config.transaction in the source of composite editor with value as required as shown inExample 10-1.
Example 10-1 Setting the transaction flag on the BPEL component
<component name="<BPELProcessName">
<implementation.bpel src="<BPELProcessName" >.bpel"/>
<property name="bpel.config.transaction">required</property>
</component>
When the transaction flag is set, BPEL inherits the existing transaction. It creates a new transaction only when no similar transaction exists.
When an ABF service is invoked by another SOA composite ensure a single-threaded execution of the composite. You must implement this only when a one-way operation is being exposed by your service. To accomplish a single threaded execution of the composite, set a sync-type invocation of your composite by the caller composite by setting the property for the BPEL component in your composite as shown below:
bpel.config.oneWayDeliveryPolicy=sync
Note:
Both the settings can be set while designing your service in JDeveloper.
10.5 Enabling Outbound Interaction with Applications
This section describes how to enable outbound interactions with participating applications.
10.5.1 Using JCA Adapters
If JCA Adapters are available, they should be your first choice to connect to applications as they provide support for tasks associated with connection management, transaction management, and scalability in combination with the runtime environment.
10.5.2 Using Standard Web Service Interfaces (SOAP/HTTP, XML/HTTP)
Most applications expose functionality in the form of a web service. The most common transport used is SOAP over HTTP. However, some applications may expose direct XML over HTTP. Participating applications making an outbound interaction in a synchronous mode alone should send the requests using SOAP/HTTP.
10.5.3 Using JMS Queues
Use queues when the message submission is decoupled from processing of the message. When JMS queues are used, access them using JMS Adapter. The message is enqueued to the JMS queue by the ABF artifact and the application dequeues the message
10.6 Invoking an ABF
Communication between an ABF and the application is governed by the application capabilities. You can invoke an ABF in the following ways:
-
Using standard web service interface where the client application makes a web service call to the ABF.
-
Using another ABF, when the required functionality is available as a separate ABF.
-
Using appropriate bindings such as JCA/JMS inside the composite for service endpoints if requester cannot make a web service call.
An ABF is built by including an adapter that can be invoked by the client application.
-
Using JMS queues when message submission needs to be decoupled from processing of the message. JMS queues must be accessed using JMS Adapter. The message is en-queued to the JMS queue by the application and ABF de-queues the message. The JMS helps exchange of messages in a persistent manner for guaranteed message delivery.
-
Exposing a JMS producer composite if the requester application does not have a capability to drop messages into a queue. Build a JMS consumer adapter into the ABF composite. The JMS consumer adapter dequeues the message and invokes the service provider application. The Asynchronous Queuing design pattern establishes a central queue to allow services to overcome availability issues and increase the overall robustness of asynchronous data exchange.
10.7 Handling Errors
This section describes how you can catch errors when implementing direct integration.
10.7.1 Using Direct Integration Services
Enable and configure direct integration services to catch and handle the runtime and business faults. Include all the business faults that you can envisage while deciding WSDL contracts and enable services to return the business fault to the caller of the ABF service.
Oracle recommends that you create a separate catch block for all possible errors and ensure that only unexpected errors go to catchAll block.
The best practice is to invoke a one-way error notification service for sending error notification and error logging.
10.7.2 Using the Fault Management Framework
You can leverage Error Handling framework that comes with the AIA Foundation Pack for exception capture and exception processing. Oracle recommends that you define a service-specific fault policy file and define both runtime and business faults in it and associate fault policies at composite level.
Use AIAAsyncErrorHandlerBPELProcess of AIA Error Handler framework with direct integration but pass the input in the format that is required by it. Construct an XML element representing an AIAFault element as string before you invoke the AIAAsyncErrorHandlerBPELProcess for business fault handling and error notification/logging.
To invoke the AIAAsyncErrorHanlderBPELProcess, follow the guidelines described in Section 27.4.2, "Guidelines for BPEL Catch and Catch-All Blocks in Synchronous Request-Response", except for the step where you apply XSLT EBM_to_Fault.xsl. However, the input message should have the following elements populated with data.
-
Fault/FaultNotification/FaultMessage/Text
-
Fault/FaultNotification/FaultingService/InstanceID
-
Fault/FaultNotification/FaultingService/ECID
-
Fault/FaultNotification/FaultingService/ImplementationCode
-
Fault/FaultNotification/FaultingService/ID
You can get all the necessary framework behavior including email notifications, and also drill down into it using the EM console.
You cannot access the information that is part of the Fault Message which is derived from the EBM_HEADER. However, the following elements can be derived by the AIA fault handling framework for remote, binding and other faults that are configured in the fault policy xml files.
-
Fault Message Code
-
Fault Message Text
-
Severity
-
Stack
-
Faulting Service ID
-
Faulting Service Implementation Code
-
Faulting Service Instance ID
-
Corrective Action
-
Reporting Date Time
Enable routing of error information through the Notification Setup screen using error code and service name.
Note:
Creation of EBM_Header variable in the BPEL process, which you use for fault handing in canonical integrations, is not relevant in direct integrations.
There is no default support for message resubmission for this release.
10.8 Implementing a Direct Integration
This section describes the various stages in implementing a direct integration.
-
Add a project in the Project Lifecycle Workbench.
For information on Project Lifecycle Workbench, see Chapter 3, "Working with Project Lifecycle Workbench."
-
Use Service Constructor to create new service solution components. Select the service type as ABF when you create a new service type.
A new folder is created with suffix ABF.
For information on Service Constructor, see Chapter 4, "Working with Service Constructor."
-
Asset Type AIA: ABF supports direct integration. This asset type enables Foundation Pack to provide harvester support into OER.
For information about AIA Harvester, see Chapter 5, "Harvesting Oracle AIA Content."
-
Go to Project Lifecycle Workbench and generate Bill of Materials.
For information on generation of bills of material, see Chapter 6, "Working with Project Lifecycle Workbench Bills of Material."
-
Run Deployment Generation Plan and deploy using AIA Deployment Driver.
For information about deployment plan generation, see Chapter 8, "Generating Deployment Plans and Deploying Artifacts."
10.9 Securing the Service
The processes for securing the direct integration services is similar to the way AIA services are secured. The processes are:
-
All the web service end points should be secured.
-
Individual service components do not have to be secured.
-
All services should be provided with authentication credentials.
-
Applications invoking secured ABF services need to send required credentials.
10.9.1 Security Recommendations for OWSM Policies for Authentication
The Table 10-1 lists security recommendations for OWSM policies.
Table 10-1 Security Recommendations for OWSM Policies
| Policy | Recommendations |
|---|---|
|
oracle/aia_wss_saml_or_username_token_service_policy_OPT_ON |
This is a clone of oracle/wss_saml_or_username_token_service_policy with Local Optimization set to ON. Attach this OWSM security policy to the Service end point(s) of a composite. This policy is applied when authenticating the incoming requests using credentials provided in SAML tokens in the WS-Security SOAP header OR UsernameToken WS-Security SOAP header. |
|
oracle/aia_wss10_saml_token_client_policy_OPT_ON |
This is a clone of oracle/wss10_saml_token_client_policy with Local Optimization set to ON. Attach this OWSM security policy to the Reference end point(s) of a composite. This policy inserts SAML tokens in outbound SOAP request messages. |
Note:
The two custom OWSM policies are made available on the server when Foundation Pack is installed.
Further recommendations:
-
Use appropriate client-specific policies for composites that invoke protected application services.
-
Use no_authentication_client_policy when invoking application services with no protection.
-
Do not have to attach policies for composites calling JCA based application services.
10.9.2 Attaching OWSM Policies to the Composites
Services in direct integration can leverage global policy attachment support provided by the Foundation Pack. After deployment, Foundation Pack tools automatically attach global policies to services that have naming pattern ending with ABF.
Services that do not use Foundation Pack have to attach OWSM policy directly (locally). Attach the policies in the composite.xml file at design time to Service and Reference endpoints. You can also attach OWSM policies to SOA composites, after deployment using EM console.
10.10 Using Cross References
Generate a custom database table for each cross reference entity. Oracle recommends that you configure the XREF entity to store the cross references in the custom cross reference table. This does not change the programming model. Wherever the cross reference data is stored, whether it is in SOA infra – XREF_DATA or custom database table, XREF look up and population are done using a single set of APIs.
The Cross Reference editor enables you to specify whether the custom database table needs to be used. (Use the optimize option while defining cross reference artifact.) It also generates the required DDL script. However, SOA does not create the table automatically.
For more information about using custom cross reference tables, see http://www.oracle.com/technetwork/middleware/foundation-pack/learnmore/aiaxref-524690.html.
Note:
The population of cross reference rows in the integration layer can be avoided in situations where the source or target applications have capabilities to manage cross references.
10.11 Naming Conventions and Standards
The ABF is modeled as a task-oriented service to capture the process logic. A practical approach is to name services based on the processing and the entity context. Oracle recommends that you use verbs and the entity in service names.
Because ABF is designed to integrate specific applications, use the names of applications as part of the service name.
The template for the name of the ABF is [Verb][Entity][App1][App2] ABF[Vn if version > 1], where App1 is source and App2 is target application.
For example, ProcessFulfillmentOrderEbizFusionABF.
You can also add the word To between participating source and target applications, if required. For example, ProcessFulfillmentOrderEbizToFusionABF.
10.11.1 Additional Guidelines for Naming Services
-
Naming an ABF when invocations to enrichment services are involved
If integration interacts with an intermediary/utility application such as GOP, Tax Computation and so on to get values to be used for integrating with target application, include the names of these intermediary/utility applications in the service names.
-
Naming an overarching ABF
An overarching orchestration process contains multiple tasks, wherein each task may involve integration with another application. In such cases do not include all the application names in the service name. Use only the source application name.
For example, ProcessFulfillmentOrderEbizABF creates an entry in FusionCRM, updates BRM for billing and sends a shipment notification to an external TP through B2BGateway and interface. Because the overarching process may be dictated by source application, use only the source application name.
-
Operation name
Since the service name covers the broad context, you can have the verb followed by entity in the service operation name.
-
Message name
The message name should be [name of the operation]Request/[name of the operation]Response
-
Composite Namespace
Composite namespace standard is http://xmlns.oracle.com/ApplicationBusinessFlow/[Functional area or pre-built integration]/[composite name minus the version]/V[n]
For example http://xmlns.oracle.com/ApplicationBusinessFlow/OrderToCash/ProcessFulfillmentOrderFusionDOOToEbiz/V1
-
Namespaces for Messages
All namespaces must start with http://xmlns.oracle.com/followed by an entity specific and domain specific identifier. For example core, Industry. If there are sub-domains, specify them.
For example, http://xmlns.oracle.com/ABFMessage/Core/Invoice/V1
-
Namespaces for ABF (WSDL) Interface
http://xmlns.oracle.com/ApplicationBusinessFlow/\[Functional area or PIP]/[composite name]/V[n]
For example, http://xmlns.oracle.com/ApplicationBusinessFlow/OrderToCash/ProcessFulfillmentOrderFusionDOOEbizABF/V1
10.12 Annotating Composites
The meta information of ABF services is used in maintaining Oracle Enterprise Repository (OER) assets. These composites are expected to be harvested multiple times during the development cycle; from conception till deployment to production environment. Oracle advises you to provide annotations in the composites for the exposed services and for the referenced services. Adhere to the proposed guidelines and insert these comments at development time.
Embed the annotations in the <svcdoc:AIA> element and place the <svcdoc:AIA> element inside the xml comments tags <!-- and -- > as shown in the examples in this section.
<svcdoc:ServiceSolutionComponentAssociation> must be the first annotation element in every annotated composite.xml file as shown in Example 10-2
Example 10-2 First Annotation Element for Every composite.xml File
<composite name="SamplesCreateCustomerPartyPortalBusinessService"> ........................ <!--<svcdoc:AIA> <svcdoc:ServiceSolutionComponentAssociation> <svcdoc:GUID></svcdoc:GUID> </svcdoc:ServiceSolutionComponentAssociation> </svcdoc:AIA>--> ..................................... </composite>
This element describes a globally unique identifier (GUID) used for artifacts generation and must be placed under the root element <composite>. The value for this element should be left blank. The GUID associates the solution service component with the implemented business service composite. This association enables auto-population into the Bill Of Material. The GUID is generated in the solution service component and is moved to the AIA Project Lifecycle Workbench database.
Annotate the Service and Reference elements of the composite.xml as shown in Example 10-3 and Example 10-4.
Example 10-3 A Skeletal Service Element in composite.xml with Annotations
<service ui:wsdlLocation .......> <interface.wsdl ....... /> <binding.ws ........... /> <!-- <svcdoc:AIA> <svcdoc:Service> . . . . . . . . . . . . </svcdoc:Service> </svcdoc:AIA> --> </service>
Example 10-4 A Skeletal Reference Element in composite.xml with Annotations
<reference ui:wsdlLocation ........"> <interface.wsdl ............/> <binding.ws ................/> <!-- <svcdoc:AIA> <svcdoc:Reference> ................. </svcdoc:Reference> </svcdoc:AIA> --> </reference>
In the previous examples the root of the annotation element of the composite is <svcdoc:AIA>. Provide annotations for the Service and Reference elements of the composite under xml comment tags using the annotation elements <svcdoc:Service> and <svcdoc:Reference>, respectively as shown in Example 10-5 and Example 10-7.
Example 10-5 An Example of Service Annotation Element
<svcdoc:Service>
<svcdoc:InterfaceDetails>
<svcdoc:ServiceName>.....</svcdoc:ServiceName>
<svcdoc:Namespace>.......</svcdoc:Namespace>
<svcdoc:ArtifactType>ApplicationBusinessFlow</svcdoc:ArtifactType>
<svcdoc:ServiceOperation>
.......
</svcdoc:ServiceOperation>
</svcdoc:InterfaceDetails>
<svcdoc:ImplementationDetails>
<svcdoc:ApplicationName>Source Application</svcdoc:ApplicationName>
................
<svcdoc:ArtifactType>ApplicationBusinessFlow</svcdoc:ArtifactType>
<svcdoc:ServiceOperation>
..........
</svcdoc:ServiceOperation>
</svcdoc:ImplementationDetails>
</svcdoc:Service>
Example 10-6 An Example of Service Annotation Element When It Has a Transport Adapter
<svcdoc:Service>
<svcdoc:ImplementationDetails>
<svcdoc:ApplicationName>Source Application</svcdoc:ApplicationName>
.................................................................
<svcdoc:ArtifactType>ApplicationBusinessFlow</svcdoc:ArtifactType>
<svcdoc:ServiceOperation>
......................................................................
</svcdoc:ServiceOperation>
</svcdoc:ImplementationDetails>
<svcdoc:TransportDetails>
<svcdoc:JMSAdapter>
<svcdoc:ResourceProvider>WLSJMS</svcdoc:ResourceProvider>
<svcdoc:ConnectionFactory>JNDINameOfConnectionFactory</svcdoc:ConnectionFactory>
<svcdoc:XAEnabled>true</svcdoc:XAEnabled>
<svcdoc:ResourceTargetIdentifier>JMSUSER1</svcdoc:ResourceTargetIdentifier>
<svcdoc:ResourceType>Queue</svcdoc:ResourceType>
<svcdoc:ResourceName>JMSQueueName</svcdoc:ResourceName>
<svcdoc:ResourceFileName></svcdoc:ResourceFileName>
</svcdoc:JMSAdapter>
</svcdoc:TransportDetails>
</svcdoc:Service>
Example 10-7 An Example of Reference Annotation Element
<svcdoc:Reference>
<svcdoc:ArtifactType>UtilityService</svcdoc:ArtifactType>
<svcdoc:ServiceOperation>
<svcdoc:Name>initiate</svcdoc:Name>
</svcdoc:ServiceOperation>
</svcdoc:Reference>
Example 10-8 An Example of Reference Annotation Element when it has a Transport Adapter
<svcdoc:Reference>
<svcdoc:ArtifactType>TransportAdapter</svcdoc:ArtifactType>
<svcdoc:ServiceOperation>
<svcdoc:Name>GetSalesOrderLineShippingDetailsEbizAdapter</svcdoc:Name>
</svcdoc:ServiceOperation>
<svcdoc:TransportDetails>
<svcdoc:ApplicationAdapter>
<svcdoc:ResourceProvider>OracleDB</svcdoc:ResourceProvider>
<svcdoc:BaseVersion>12.1.3</svcdoc:BaseVersion>
<svcdoc:ConnectionFactory>eis/Apps/OracleAppsDataSource</svcdoc:ConnectionFactory>
<svcdoc:ApplicationName>ebiz</svcdoc:ApplicationName>
<svcdoc:XAEnabled>true</svcdoc:XAEnabled>
<svcdoc:ResourceTargetIdentifier></svcdoc:ResourceTargetIdentifier>
<svcdoc:ResourceType>Procedure</svcdoc:ResourceType>
<svcdoc:ResourceName></svcdoc:ResourceName>
<svcdoc:ResourceFileName>XX_BPEL_GETSALESORDERLINESHIPP.sql</svcdoc:ResourceFileName>
</svcdoc:ApplicationAdapter>
</svcdoc:TransportDetails>
</svcdoc:Reference>
10.12.1 Annotating WSDLs
WSDL annotations are similar to an existing AIA service annotations. Look at Example 10-9.
10.13 Service Configuration
Direct integrations services that use AIA Foundation Pack tools can use the existing approach for setting up service level configuration properties in an XML file. However, Oracle recommends that you use BPEL preferences by leveraging BPEL preferences/properties feature of SOA for freshly built direct integration flows. In the composite use the property and define the configurable preferences.
<property name="bpel.preference.myProperty">myValue</property>
Configuration updates to the defined properties such as add/delete/modify can be made directly through EM console. If you use SOA BPEL preferences for service configuration you do not require a separate UI for updating the properties.
There are limitations with this approach. This approach:
-
Does not have support in XSL transformations
-
Can be used only from BPEL. Does not have support in Mediator
-
Has no support for Domain level configurations
-
Has non-intuitive navigation in the EM console to the preferences
The AIA Service Configuration file can be used to configure runtime behavior of services by the direct integration flow when AIA Foundation Pack is installed.
10.14 Extending Direct Integrations
This section discusses the extensibility patterns for Direct Integrations. This section includes the following topics:
10.14.1 Extending XSLs
Develop the base transformation XSL file to provide extension capabilities using the following guidelines.
-
To make transformation maps extension aware, create an extension XSL file for every transformation.
An example of a core transformation XSL file: PurchaseOrder_to_PurchaseOrder.xsl
Every core XSL file name has one extension XSL file, for example: PurchaseOrder_to_PurchaseOrder_Custom.xsl.
-
Define empty named templates in the extension file for every component in the message.
-
Include the extension file in the core transformation file.
-
Add a call-template for each component in core transformation.
-
Enable the transformation to accommodate transformations for custom element as shown in Example 10-10.
Example 10-10 Transformation Enabled to Accommodate Transformations for Custom Element
<!-XSL template to transform Address-->
<xsl: template name="Core_AddressTemplate">
<xsl:param name = "context" select ="."/>
<xsl:param name = "contextType" select ="'CORE'"/>
<address1><xsl:value-of select="$context/address1"><address1>
<address2><xsl:value-of select="$context/address1"></address2>
<city><xsl:value-of select="$context/city"></city>
<state><xsl:value-of select="$context/state"></state>
<zip><xsl:value-of select="$context/zip"></zip>
<xsl:if test="$contextType!='CORE'">
<xsl:call-template name="Vertical_AddressTemplate">
<xsl:with-param name="context" select="$context"/>
<xsl:with-param name="contextType" select="$contextType">
</xsl:call-template>
</xsl:if>
</xsl: template>
10.14.2 Extending Services
-
Mark your composite as customizable only if you have a specific customization use case.
-
Mark specific scopes in your BPEL process as customizable only if there is a specific customization use case.
For information about how to mark your composites and BPEL processes as customizable, see Chapter 4, "Working with Service Constructor."
10.14.3 Guidelines for Enabling Customizations
The section discusses general guidelines for identifying the BPEL scope to be marked as customizable.
The scope of the customizable scope activity should be made as narrow as possible. For example, rather than marking the top level scope of the BPEL flow as customizable, identify a specific scope where the logic can be added to meet customization requirements.
-
Avoid marking complex logic which could be partially deleted later as customizable.
-
If a composite is marked as customizable, do not unmark it once it is released. If you unmark it, the customization will not survive patching.
-
Do not make changes to the base version which, in a way, could cause conflict when the customized composite is patched. For example, deleting components, routing rules and activities in the customizable BPEL scope requires the customer to manually resolve the merge conflict when customized item is deleted.
-
Do not delete any component or routing rule from a customizable composite and do not delete any activities in a BPEL scope marked as customizable once the composite is released.