As we have discussed the SDO Inbound Integration with the ADF –BC Application, there could the SDO Outbound Integration where BPEL Process Service which invokes the Outbound Call to connect the ADF-BC Application to retrieve the data.
We discussed in previous blog (BPEL Data Operations using Entity Variables in SOA 12c) that in such cases the Oracle BPEL Process Manager uses the unique key which will get stored in the dehydration store. While invoking the Outbound call, BPEL Process Service binds the Unique Key and passes it as an Input to retrieve the required data.
Below given are the main steps that need to be followed
1) Oracle ADF-BC is the external application which is deployed as the SDO Service in the Service Infrastructure
2) In the BPEL Process Service, we need to create the partner link with the exposed SDO external service
3) To do so, we need to create the entity variable
4) Create the Binding key to map it as an input for the external ADF-BC Service
This blog discuss about the usage of SDO (Service Data Objects) Inbound Integrations with the ADF-BC Application. Refer the blog BPEL Data Operations using Entity Variables in SOA 12c to understand how to perform the BPEL data operations using the data provider services through the usage of entity variables.
Till Release 10.X, only DOM format variables were supported. From Release 11g onwards, SDO format variables were introduced and supported in the BPEL Process Services and components can be converted into required formats as per the Business Process need (Example – Usage of ASSIGN Activity to convert the DOM based BPEL Process Service Component to SDO based format and vice –versa
Unlike DOM and SDO based variables, Entity variables supports SDO based data and enables a unique key which binds the value to data. A common Example could be Create Supplier Operation or Create Purchase Order using BPEL Process Service. This unique key gets stored in the dehydration store. When the data is to be retrieved, Oracle BPEL Process Manager performs the below steps:
1) It uses the Bind Entity Activity to map the unique key
2) Executes the data provider service to retrieve the data places into memory
SDO Inbound Integrations
The above given diagram depicts the SDO Inbound Integration where the ADF-BC Application Invokes the BPEL Process Service. The BPEL Process Service Component is converted from SDO based variables to DOM based Variables and executes the services as per the received operation.
SOA 12c provides the capability to perform the BPEL data operations using the data provider services through the usage of entity variables. The data provider services perform the data operations behind the scenes and thus eliminates the usage of Database Adapter in the BPEL Process Service, enhancing the SOA runtime performance.
The common example of using entity variables with the Oracle Application Development Framework (ADF) which provides Business Component provider service using SDO based data to connect to the Data Store.
SDO is the specification provided to streamline the execution of SOA data from heterogeneous systems in the form of XML document, relational databases and web service being the source of information.
Entity variables using data provider service overcomes the below given issues:
1) Earlier the unsupported XML data source (Native Data) was required to be converted into XML Format before it can be processed using the SOA components.
2) The large payloads during the data conversion also leads to performance issue
3) In the previous release of SOA, the DOM form data was retrieved using the Database Adapter and was getting stored in the dehydrated data store. The stored data was not in sync with the target data store and thus might provide the stale data details.
The current SOA 12c Release overcomes this issue by providing the entity variables which retrieves the data using the data provider services (ADF –BC). Instead of storing the data in the dehydrated store, key is persisted (done using the BindEntity Activity in the BPEL Process).
Every time, this key will be referred to retrieve the data from the target data store using the data provider services, eliminating redundant data / stale data issue.
S. No
10.1.x Release
11g and 12c Release (Entity Variables)
1
Usage of Database Adapters for retrieving / saving the data
Retrieving / saving of data is performed using data provider services ( ADF-BC)
2
Storage of data in the dehydrated store using the Oracle BPEL Process Manager
Key is persisted for the transaction
3
Data variables are in the DOM( Document Object Model) Form
Data variables are in the SDO ( Service Data Objects) Form
The blog discuss about ” How to invoke Synchronous Transactions using SOA Suite Integration Pattern in SOA 12c” , “How to invoke Asynchronous Process from the Synchronous Transactions in SOA12c” .
Synchronous Transaction Integration Pattern
The synchronous integration pattern is the one where the application sends the message from the Client and receives the response back or we can say that its a 2 way communication process which is a combination of request and response. The BPEL Process Service Component can be a Client who sends the request to the service and receives the response back or it could be the service who accepts the request and returns the response to the Client.
Synchronous Transaction Example in SOA 12c
Consider an example for synchronous transaction in SOA Composite application where user clicks on the application to get the list of employee in a particular department. In this scenario, the Department No. is the input from the Client and list of Employee will be the response sent back by the called service.
Integration pattern: Synchronous Transactions
If the synchronous transaction uses BPEL Process as the Client, it needs to have the Invoke Activity. The port on the client side is used to send the request data to the Target Service and to receive the response (using the Reply Activity). The WSDL in the Client side BPEL Process Services defines the interaction depicting the portType, operation.
If the synchronous transaction uses BPEL Process as the Service, it needs to have the Receive Activity. The Service will execute the data as per the received request and returns either the Response or the Fault Message in case of any error occurred while processing the data. The WSDL in the Service side BPEL Process Services defines the interaction depicting the details including the fault defined.
Synchronous Transaction Invoking the Asynchronous Process:
If the synchronous transaction using the BPEL Process invokes an Asynchronous Process, then it will not have processed successfully as the callback response message is not acknowledge by the synchronous BPEL Process ad it will be timed out.
Sample for the portType and operation of the BPEL Process WSDL. The WSDL Operation supports both the Input and output messages for synchronous transaction processing.
The blog explains the One way message integration pattern between the BPEL Process Service Component and external service(s). The one way message integration pattern approach is also called as ” Fire and Forget message”
There are scenarios where information need to be sent but it is not of utmost important to send immediately as these are independent actions need to perform once main service has been executed.
One Way message integration pattern example in SOA 12c
Consider an example of the user registration process requires user data validation, business process validation and then submission of user data in the custom user database table. Once the user registration process is completed, user receives the email notification for the confirmation of the user creation process. As user data is already being saved, the email notification service can be invoked once user registration process is completed. The email notification process is the example of One-way message (or fire and forget) where client application sends the email notification and does not wait for the response.
To implement the one-way message service invocation process, the BPEL Process Service component needs the following 1. The message that client has to send to the target service. To accept the message from the client, the BPEL Process Service component needs a Receive Activity. 2. A Partner link for the target service to which message is to be sent. 3. An Invoke activity to invoke the partner link
Interaction pattern one – way messages
Sample for the portType and operation of the BPEL Process WSDL. The WSDL operation includes only input message and No response message is supported.
Perform the below steps for managing the deployed soa services using JDeveloper
Select Windows -> Application Servers -> <CustomApplication ServerName>
Click SOA Folder
Expand the SOA partition in which the SOA Composite is deployed
Right-Click the deployed SOA Composite to perform the below given operations
• Stop – Shutdown the running SOA Composite application
• Start – Restart the stopped running SOA Composite application
• Retire – Retire the SOA Composite application. It cannot create new instances.
• Activate – Activates the SOA Composite application
• Undeploy – Undeploy the SOA Composite application from the SOA Server. The SOA composite cannot be configured , cannot create instances and cannot view the previously processed instacnes.
• Set Default Revision – Revision for the SOA Composite application
If the SOA Composite application is to be deployed , then below steps to be performed
– Right click on SOA Folder, select Deploy SOA Archive
– Select the configure SOA Server
– Select the SOA archive that need to be deployed
– Select the Configuration Plan if created
– Select Default Revision or overwrite for the deployment revision number
SOA Composite is an collection of services, components and references which are created , managed and deployed as single application integrating the business processes. Components are divided as Service Components and Binding Components.
Service components: Service components acts as the building blocks for developing SOA Composite application. • BPEL Process • Business Rule • Human Task • Oracle Mediator • Spring • SubProcess
Binding components : Binding components are used for establishing the connection between a SOA Composite and external services like external web services , JMS Queues , Database Adapters.
Services : Services provides an entry point to connect the SOA Composite with the external services. The protocols ( SOAP /HTTP/REST) used in external services acts as the Binding connectivity within the SOA composite application References – are used to send messages from SOA Composite to the external services/ applications.
Below given are the provided binding components for the external services.
External Services
Binding Component
Web Services ( SOAP Over HTTP)
SOAP enables services over HTTP Protocol
JCA Adapters
helps in integrating services with different technologies with the usage of provided adapters
FTP Servers
FTP Adapter
JMS Messaging
JMS Adapter
Database Server
DB Adapter
Oracle User Messaging Service
Oracle User Messaging Service Adapter
File server
File Adapter
IBM Websphere MQ
MQ Adapter
LDAP Server
LDAP Adapter
Oracle Coherence Cache
Oracle Coherence Adapter
PeopleSoft
PeopleSoft Adapter
Oracle Sales Cloud
Oracle Sales Cloud Adapter
Oracle B2B
helps in browsing B2B Metadata Services Repository (MDS)
Oracle ADF
BC Service – integrates the Oracle Application Development Framework using Service Data Objects (SDO) with the SOA Application
Oracle E-Business Suite
integrates the oracle applications with the use of Oracle E-Business Suite Adapter
BAM 11g Adapter
integrates the Business Activity Monitoring (BAM) for the exchange of data
EJB Service
integrates the Service Data Objects (SDO) parameters or Java Interfaces with the Enterprise Java Beans (EJB)
HTTP Binding
integrates SOA Application with HTTP
REST Service
integration of REST enabled services with SOA Application.
Oracle Managed File Transfer ( MFT)
integrates the transfer files process to and from endpoint types like FTP / SFTP servers, SOA Web Services , Oracle Service Bus , etc.
Cloud Adapters
integration of Cloud application with SOA Application
The blog discuss on the handling of SOA Composite run time fault error and fault recovery mechanism provided by the Oracle SOA Server. Oracle SOA provides the automated SOA Fault recovery with the usage of Fault Policy Wizard.
We will discuss the BPEL Standard faults, classification of BPEL Faults (Business Fault and Run-time Faults) with the help of SOA Composite example using Fault Policy Wizard.
Error handling in Oracle SOA Composite is one of the common pain area. SOA provides the Fault Handling mechanism to capture error message / run time exceptions returned by the invoked web services in BPEL Process Service components. The BPEL provides the below given standard faults
bindingFault
conflictingReceive
conflictingRequest
correlationViolation
forcedTermination
invalidReply
joinFailure
mismatchedAssignmentFailure
remoteFault
repeatedCompensation
selectionFailure
uninitializedVariable
The BPEL fault has a fault name called a Qname (name qualified with a namespace) and a possible messageType. There are two categories of BPEL faults:
Business faults
Runtime faults
Business Faults are the error when the application executes a throw activity or when an invoke activity returns Fault as a response. The invoked service returns error when the required information is not received Example – The Purchase Order Number is not available. A business fault can be caught with a faultHandler using the faultName and a faultVariable.
Run Time Faults are the error received by the BPEL Process Service Component or Web Service at the run time returned by the system, not user-defined. The invoked service is not available, the transformation error occurs at run time, etc. Run Time Faults are provided in the http://schemas.oracle.com/bpel/extension namespace and are associated with the messageType RuntimeFaultMessage
To handle the above mentioned Business Faults and Run Time Faults, we were required to create Fault Policy and Fault binding files manually in SOA 11g. But now with SOA 12c, the Fault Policy Wizard has been provided to create the Fault Policy with ease for the composites. Let’s create a sample application which invokes the Remote Service. The Service will handle the RemoteFault using the SOA 12c Fault Policy Wizard and link it to the Fault Binding File
Create the SOA Application and Project – FaultPolicyRemoteInvocPrj
Select the options with No Composite
Create the synchronous BPEL Process – RemoteFaultPolicyBPELProcess
Fault Policy Wizard- Application
Create the Partner Link with the enabled WSDL. Create the Invoke Activity and provide the details for the created partner link. Create the Invoke Input Variable – InvokeCustomSupplierSrvc_updateSupplier_InputVariable Now, let’s utilize the Fault Policy Wizard. Right click on the SOA project and click on New ->From Gallery. Choose SOA Tier -> Faults -> Fault Policy Document to create new fault policy file. Below given are the actions which can be used for the custom fault policy. Multiple Fault Policies can be created.
Fault Policy Wizard
The Alerts can be created with any of the 3 given types (JMS, Log and email). Let’s use JMS Alert to see the required details to be entered. Provide the Alert Id and then click on ‘Create Required Properties’. Enter the Property Name and then select the Web Logic Server and the JMS Queue and JMS Connection factory created in the Web Logic JMS Module.
Fault Policy Wizard -JMS Properties
Click OK and these details will be shown in the Alert Window. Now link the created JMS Alert to the Fault which need to be captured. Enter the Fault Name: bpelx: remoteFault Enter the description: Enter the Default Action: [abort] default-termination Below given are the available action to be selected.
Fault Policy Wizard -Actions
The below screenshot provides the complete details entered for handling the Remote Fault.
Fault Policy Wizard -Actions Details
Similarly, you can select the Alert for Email and Log also.
Fault Policy Wizard -Email Details
You can map the Created Remote Fault accordingly with any of the created Alert. You can select 1 Alert for the 1 Fault Policy. Set the Alert Property Set similar to JMS Property Set.
Fault Policy Wizard -Complete Wizard Details
Now, we need to create the fault binding file and link the created RemoteFaultPolicy to the available composite, components, services and references. Now click on the highlighted icon to Edit the Fault Policies and map the value of RemoteFaultPolicy to composite, components, services and references
Composite-Fault-Policy Binding
As the scenario is shown for the RemoteFault, the remote service which will be invoked thorough this application should be down to get the fault policy invoked.
Deploy the application and test the SOA Composite application
Oracle SOA 12c provides new feature “Translate Activity” which can be used to convert any native format file like CSV to XML and vice versa. The blog provides the steps to translate the Native Format File to XML File.
Translate Native Format File to XML File
Consider a common scenario where XML message can contain delimited / fixed length string and to overcome such issues SOA 11g provided the File / FTP Adapter as the mechanism but there was no specific activity available to confirm the XML messages to Native Format or from Native Format to XML message from the received input.
SOA 12 c provides Translate Activity as the solution for such transactional data. Steps are similar to what we use in the File /FTP Adapter Let’s go through the sample given below to see how to convert XML messages to Native Format or from Native Format to XML message using the Translate Activity
Create the SOA Application for the Translate Activity
SOA-Translate-Activity
Drag the Translate Activity from Oracle Extensions to the BPEL Process
Double Click the Translate Activity to get the translation tab. Translate Activity provides below options ( Native to XML and XML to Native)
Select the option as Native to XML and click on the Search Icon corresponding to the Input parameter. The below given is the Input Variable Payload Input String
SOA-Translate-Activity Input String
Convert the Schema to Native (delimited string) to XML format. We can use either of the given below options
Option 1 – Provide the available schema OR
Option 2- Generate the schema using the Native format builder wizard
Click Option 2 for the NXSD schema to generate the Native schema
SOA-Translate-Activity-Native-Builder-Format
Select the option as Delimited. Specify the file with the Native format which includes delimited records. I have selected EMP.txt file with sample employee records delimited with commas
The next steps identifies the number of records present in the file ( whether there is single record or it could be multiple record file), whether it contains single type data or different type data.
Define the target namespace for the schema
The Native Format builder wizard shows the Type for each column identified with the delimiter ( Commas )
Below given is the screenshot for the Native Schema File generated
The Translate activity includes Input and Output Variable. The Input variable was intialized, now the schema has been generated. Create the Output Variable by clicking the GREEN + icon
Oracle SOA provides the File Adapter for processing the file based SOA Composite applications by supporting the file adapter polling configuration. When File adapter polling configuration is enabled, the SOA composite application starts polling the file immediately once it is deployed and keep polling the file directory as per the given polling frequency.
The SOA File adapter provides the option as “Trigger File” checkbox, which enables the file polling when the trigger file is placed in the trigger directory. This provides the restriction on how to poll the files based on trigger.
Oracle SOA File Polling Options with File Adapter
Oracle SOA Provides the below given File Polling options
Polling Frequency : This option defines after how much time the file polling is to be done.
Minimum File Age: This option is useful when we have large files for processing and we know that it will take time for file to be processed and thus next available new file should be read after that. So increasing the value here ensures that no file is missed from getting processed.
Check box for Trigger File : This option when checked then the above 2 Options Polling Frequency and Minimum File Age will not be used as file will not be Polled automatically, they requires a trigger or in simple words it need to be invoked
Oracle SOA File Polling using Triger File option
Select the File Adapter to the SOA Composite Application
Enter the Service Name for the File Adapter
Select the Adapter Interface as ” Define from operation and Schema”
Select the operation as “Read File”
Enter the File Polling Frequency value
Enter the Minimum File age value
Select the checkbox” Use Trigger File” as an option
We need to provide the file location from where the file will be processed .
We need to provide the Trigger File Name for which file adapter should check having extension as .trg. If this file is available , then file adapter will poll the students.txt file and get it processed.
Such file trigger mechanism is useful when data is critical for processing and needs confirmation before it is processed . With the file data , we need to place the trigger file which , when read by the file adapter gives the confirmation / triggering to proceed with the file processing.
The below given are the steps for configuring File Adapter in SOA BPEL Project. The File Adapter provides the below given operation to read and write files on the application server.
READ : The READ Operation of File Adapter picks and read the file data from the given server location
WRITE : The READ Operation of File Adapter allows to write files to a specific server location
SYNCHRONUS READ : The SYNCHRONUS READ Operation of File Adapter allows to to read a file in middle of the process
LIST FILE : The LIST FILE Operation of File Adapter allows to list all the files in a given directory
CHUNKED READ : The CHUNKED READ operation is used for processing large file data . The chunk Size provides the option of reading data content in sizes to minimize the performance impact on the server and other running services on the application server.
Please find below the steps to create the File Adapter in SOA Project
Create a new SOA Project and provide the Project Name
Select the “Empty Composite” template and click on Finish
Drag and drop the File Adapter from the Palette , Components -> Technology
4. The File Adapter Configuration Wizard will open. Provide the File Adapter Service Name and click Next
5. As we will be reading the data content from the file and does not require any transformations, the default option
will be selected for the File Adapter Interface. Click Next.
6. Provide the File Server JNDI Name
7. Select the File Adapter ReadFile Operation for reading the file data content.
Provide the Operation Name and Click Next
8. Provide the File Adapter Directory Path from where the file is to be picked and read
Select the option to process the files recursively
Select the option to archive the file once they are read for reference. Provide the Directory path where file to be placed once processed.
Select the option to Delete the file once they are successfully processed.
Click Next
9. Provide the extension which are allowed for reading the files .
students *.txt allows to read the text file
students *.* will allow to read all file starting with name students
Click Next
10. Define the Polling frequency for the file adapter to check and read file from a particular server location.
Polling Frequency : This option defines after how much time the file polling is to be done.
Minimum File Age: This option is useful when we have large files for processing and we know that it will take time for file to be processed and thus next available new file should be read after that. So increasing the value here ensures that no file is missed from getting processed.
Click Next
11. Select the default option for the Opaque Schema as file is read and processed as it and not required any transformation.
Click Next
12. Click Finish to complete the File Adapter Configuration Wizard.
My previous post ( DB Adapter configuration in SOA 12c) had shown the steps to configure the DB Adapter but it is observed that the DB Adapter Polling does not work correctly when records are retrieved in a clustered environment.
Example :
The Customer Order details to be picked from the Oracle Database , transformation of the data as per business scenario and then send the updated data to the target server for further processing. In a clustered environment, the DB Adapter polling will be done simultaneously by all the configured managed server at the same whereas single instance should be initiated to retrieve the order details.
Solution:
NON XA Datasource : Do not use the XA datasource when using distributed transactions as it can cause problems with autonomous transactions such as java.sql.SQLException
Distributed Polling : While configuring the DB Adapter , select the option for the Distributed Polling
DB Adpater Plan.xml : Ensure that once the configuration of DB Adapter in the Weblogic Server is being done, update the Plan.xml file (deployment plan for the DbAdapter) to the other managed server
Singleton Property in Composite: To enable for high availability environment for a inbound database adapter , add the singleton JCA service binding property in the composite.xml with value as ‘true’
