Using Concurrent Programs

Overview

A concurrent program is an instance of an execution file with associated parameters. Concurrent programs use a concurrent program executable to locate the correct execution file. The execution file can be an operating system file or database stored procedure which contains your application logic (such as PL/SQL, Java). Several concurrent programs may use the same execution file to perform their specific tasks, each having different parameter defaults.

The concurrent program can be exposed as a Web service based integration interface. An integration repository administrator can further deploy a generated service from Oracle Integration Repository to the application server.

This deployed service can be exposed to customers through service provider and invoked through any of the Web service clients.

For example, an integration developer can take a deployed Web service WSDL URL and directly use it to define a partner link for the Web service that a BPEL process connects to in order to perform tasks, or carry information between the Web service and the BPEL process.

Detailed information on how to create a BPEL process to invoke the Web service and use it to update Oracle E-Business Suite is discussed in this chapter. For the example described in the following sections, we use Oracle JDeveloper 10.1.3.3.0 as a design-time tool to create the BPEL process and use Oracle SOA Suite BPEL server 10.1.3.3.0 for the process deployment.

Using Concurrent Program WSDLs at Design Time

BPEL Process Scenario

This example uses Departure Shipment Notice Outbound WSHDSNO concurrent program to explain the BPEL process creation.

When a shipment notice generation request is received as an input to the BPEL process, a sales order information including header and line items are read by a File Adapter. The sales order data is then passed through to create a departure shipment notice (DSNO). The shipment notice creation document number will be passed back to the request application.

If the BPEL process is successfully executed after deployment, you should be able to validate if the generated shipment notice has correct trading partner information as described in the sales order.

Prerequisites to Create a BPEL Process Using a Concurrent Program Web Service

Before performing design-time tasks for concurrent programs, you need to ensure the following tasks are in place:

• An integration repository administrator needs to successfully deploy the generated concurrent program web service to the application server.

• An integration developer needs to locate and record the deployed WSDL URL for the concurrent program exposed as a SOAP service.

• SOAHeader elements should be populated in order to run the concurrent program for SOAP request

Deploying the Concurrent Program WSDL URL

An integration repository administrator must first create a Web service for the selected interface definition, and then deploy the service from Oracle Integration Repository to the application server.

For example, the administrator must perform the following steps before letting integration developers use the deployed WSDL in creating a BPEL process:

1. To generate a web service, locate the interface definition first from the Oracle Integration Repository (such as Departure Shipment Notice Outbound WSHDSNO concurrent program ) and click Generate in the SOAP Web Service tab of the interface details page. For detailed instruction on how to generate a web service, see Generating SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

2. To deploy a generated SOAP service, select at least one authentication type and click Deploy in the SOAP Web Service tab of the interface details page to deploy the service.

   Once the service is successfully deployed, the selected authentication type(s) will be displayed along with 'Deployed' Web Service Status. For more information on securing web services with authentication types, see Managing Web Service Security, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

   For detailed instruction on how to deploy a web service, see Deploying and Undeploying SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Searching and Recording WSDL URL

Apart from the required tasks performed by the administrator, an integration developer also needs to log on to the system to locate and record the deployed SOAP service WSDL URL for the interface (such as WSHDSNO concurrent program) that needs to be orchestrated into a meaningful business process in Oracle JDeveloper using BPEL language.

This WSDL information will be used directly for a partner link during the BPEL process creation at design time.

For information on how to search for an interface and review the interface details, see Searching and Viewing Integration Interfaces.

Setting Variables in SOAHeader for SOAP Request

You must populate certain variables in the BPEL process for SOAHeader elements to pass values that may be required to set application context during service execution. These SOAHeader elements for concurrent program interface type are Responsibility, RespApplication, SecurityGroup, NLSLanguage, and Org_Id.

Note: The user information is defined by the wsseUsername property passed within the security headers. Detailed instructions on how to pass the security headers along with the SOAP request, see Passing Values to Security Headers.

The expected values for these elements are described in the following table:

Header Variables and Expected Values for Concurrent Program Interface Type

Element Name	Expected Value
Responsibility	responsibility_key (such as "SYSTEM_ADMINISTRATOR")
RespApplication	Application Short Name (such as "FND")
SecurityGroup	Security Group Key (such as "STANDARD")
NLSLanguage	NLS Language (such as "AMERICAN")
Org_Id	Org Id (such as "202")

Note: NLS Language and Org_Id are optional values to be passed.

• If the NLS Language element is specified, SOAP requests can be consumed in the language passed. All corresponding SOAP responses and error messages can also be returned in the same language. If no language is identified, then the default language of the user will be used.

• If a service execution is dependent on any particular organization, then you must pass the Org_Id element of that SOAP request.

The context information can be specified by configuring an Assign activity before the Invoke activity in the BPEL PM.

BPEL Process Creation Flow

Based on the scenario, the following design-time tasks are discussed in this chapter:

1. Create a New BPEL Project

   Use this step to create a new BPEL project called ShipNotice.bpel. This automatically creates two dummy activities - Receive and Reply - to receive input from a third party application and to reply output of the BPEL process back to the request application.

2. Create a Partner Link

   Use this step to create a partner link for the Departure Shipment Notice Outbound Shipment_Notice concurrent service.

3. Add a Partner Link for File Adapter

   This is to synchronous read sales order details received from the trading partner.

4. Add Invoke Activities

   Use this step to create two Invoke activities in order to:

   1. Point to the File Adapter - Synchronous Read operation to read the order details from the Assign activity.

   2. Point to the Shipment_Notice web service to create the shipment notice with header and line details.

5. Add Assign Activities

   Use this step to create three Assign activities in order to:

   1. To pass the SOAHeader variables for the invocation of the DSNO concurrent program service.

   2. To pass the order details from the output of the Synchronous Read - File Adapter service to the input of the DSNO creation.

   3. To set the SOAP response to output.

For general information and basic concept of a BPEL process, see Understanding BPEL Business Processes and Oracle BPEL Process Manager Developer's Guide for details.

Creating a New BPEL Project

Use this step to create a new BPEL project that will contain various BPEL process activities.

To create a new BPEL project:

1. Open JDeveloper BPEL Designer.

2. From the File menu, select New. The New Gallery dialog box appears.

3. Select All Items from the Filter By box. This produces a list of available categories.

4. Expand the General node and then select Projects.

5. Select BPEL Process Project from the Items group.

6. Click OK. The BPEL Process Project dialog box appears.

7. In the Name field, enter a descriptive name for example ShipNotice.

8. From the Template list, select Synchronous BPEL Process and then select Use Default Project Settings.

9. Use the default input and output schema elements in the Input/Output Elements dialog box.

10. Click Finish.

    A new synchronous BPEL process is created with the Receive and Reply activities. The required source files including bpel.xml, using the name you specified (for example, ShipNotice.bpel) are also generated.

Creating a Partner Link for the Web Service

Use this step to create a Partner Link called Shipment_Notice for the web service exposed through WSHDSNO concurrent program.

To create a partner link for Shipment_Notice Web service:

1. In JDeveloper BPEL Designer, drag and drop the PartnerLink service from the Component Palette into the Partner Link border area of the process diagram. The Service Name dialog box appears.

2. Copy the WSDL URL corresponding to the Departure Shipment Notice Outbound WSHDSNO service that you recorded earlier in the WSDL File field. Click OK.

3. A Partner Link Type message dialog box appears asking whether you want the system to create a new WSDL file that will by default create partner link types for you.

   Click Yes to have the Partner Name value populated automatically.

   The partner link is created with the required WSDL settings, and is represented in the BPEL project by a new icon in the border area of the process diagram.

   BPEL Process Diagram with the Web Service Partner Link

   

4. You can optionally change the default partner link name by double-clicking the icon to open the Edit Partner Link window. For example, change it from WSHDSNO to Shipment_Notice.

   Select the Partner Role value from the drop-down list. Click Apply.

   Edit Partner Link Dialog

   

5. Passing Values to Security Headers

   Select the Property tab and click the Create Property icon to select the following properties from the property name drop-down list in order to pass the security headers along with the SOAP request:

   • wsseUsername

     Specify the username to be passed in the Property Value box.

   • wssePassword

     Specify the corresponding password for the username to be passed in the Property Value box.

   • wsseHeaders

     Enter credentials as the property value.

   Click Apply to save the selected property values.

   Edit Partner Link Dialog: Property Tab

   

6. Click OK to complete the partner link configuration.

Adding a Partner Link for File Adapter

Use this step to configure a BPEL process by synchronously reading a sales order to obtain the order details.

To add a Partner Link for File Adapter to read order details:

1. In JDeveloper BPEL Designer, drag and drop the File Adapter service from the Adapter Service section of the Component Palette into the Partner Link area of the process diagram. The Adapter Configuration wizard welcome page appears.

2. Click Next. The Service Name dialog box appears.

3. Enter a name for the file adapter service, for example ReadOrder. You can add an optional description of the service.

4. Click Next and the Operation dialog box appears.

   Operation Dialog

   

5. Specify the operation type, for example Synchronous Read File. This automatically populates the Operation Name field.

   Click Next to access the File Directories dialog box.

6. Select Physical Path radio button and enter the input payload file directory information. For example, enter /usr/tmp/ as the directory name.

   Uncheck the Delete Files after successful retrieval check box. Click Next to open the File Name dialog box.

7. Enter the name of the file for the synchronous read file operation. For example, enter 'order_data.xml'. Click Next. The Messages dialog box appears.

8. Select Browse for schema file in Schema Location. The Type Chooser window is displayed.

   1. Click Import Schema Files button on the top right corner of the Type Chooser window.

   2. Enter the schema location for the service. Such as http://<myhost>:<port>/webservices/SOAProvider/concurrentprogram/wshdsno/APPS_ISG_CP_REQUEST_CP_SUBMIT.xsd.

      Schema location for your service can be found from the service WSDL URL (for example, http://<myhost>:<port>/webservices/SOAProvider/concurrentprogram/wshdsno/?wsdl).

   3. Select the Add to Project check box and click OK.

   4. Click OK for Import schema prompt.

      The Imported Schemas folder is automatically added to the Type Chooser window.

   5. Select schema element by expanding the Imported Schemas folder > APPS_ISG_CP_REQUEST_CP_SUBMIT.xsd > InputParameters.

      Click OK.

      The selected schema location and element values are displayed.

      Messages Dialog with Selected Message Schema and Element

      

9. Click Next and then Finish. The wizard generates the WSDL file corresponding to the partner link. The main Create Partner Link dialog box appears, specifying the new WSDL file ReadOrder.wsdl.

   Edit Partner Link Dialog with Partner Link Configuration

   

   Click Apply and then OK to complete the configuration and create the partner link with the required WSDL settings for the File Adapter Service.

   The ReadOrder Partner Link appears in the BPEL process diagram.

   BPEL Process Dialog with File Adapter Partner Link

   

Adding Invoke Activities

This step is to configure two Invoke activities:

• Read order details that is passed from the first Assign activity through the ReadOrder partner link for File Adapter.

• Send the order header and line details received from the Assign activities to generate an outbound shipment notice (DSNO) by using the Shipment_Notice partner link.

To add an Invoke activity for ReadOrder Partner Link:

1. In Oracle JDeveloper BPEL Designer, drag and drop the Invoke activity from the Component Palette into the Activity box of the process diagram, between the Receive and Reply activities.

2. Link the Invoke activity to the ReadOrder service. The Invoke activity will send order data to the partner link. The Edit Invoke dialog box appears.

   Edit Invoke Dialog

   

3. Enter a name for the Invoke activity, and then click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog box appears.

   Create Variable Dialog

   

4. Select Global Variable and then enter a name for the variable. You can also accept the default name. Click OK.

5. Click the Create icon next to the Output Variable field. Select Global Variable and then enter a name for the variable. You can also accept the default name. Click OK.

6. Click Apply and then OK in the Edit Invoke dialog box to finish configuring the Invoke activity.

   The Invoke activity appears in the process diagram.

To add the second Invoke activity for Shipment_Notice Partner Link:

1. In Oracle JDeveloper BPEL Designer, drag and drop the Invoke activity from the Component Palette into the Activity box of the process diagram, after the Invoke and Reply activities.

2. Link the Invoke activity to the Shipment_Notice service. The Invoke activity will send event data to the partner link. The Edit Invoke dialog box appears.

3. Enter a name for the Invoke activity such as 'Invoke_ShipmentNotice'. Select input and output global variables as described in the first Invoke activity creation procedure.

   Edit Invoke Dialog

   

   Click Apply and then OK in the Edit Invoke dialog box to finish configuring the Invoke activity.

   The second Invoke activity appears in the process diagram.

   BPEL Process Dialog with Invoke Activities

   

Adding Assign Activities

This step is to configure three Assign activities:

1. To pass the application context for SOAHeader in the invocation of the DSNO concurrent program service.

2. To pass the order details from the output of the Synchronous Read - File Adapter service to the input of the DSNO creation through the Invoke_ShipmentNotice Invoke activity.

3. To set the SOAP response to output.

Assigning SOAHeader Parameters:

To add the first Assign activity to pass SOAHeader variables used in the invocation of the DSNO concurrent program service:

1. Add the first Assign activity by dragging and dropping the Assign activity from the Component Palette into the Activity box of the process diagram, between the two Invoke activities.

2. Enter 'SOAHeader' as the Assign name in the Edit Assign dialog box. Click OK.

3. Enter the first pair of parameters by selecting Copy Operation from the Create drop-down list with the following values:

   • In the From navigation tree, select type Expression and then enter 'ORDER_MGMT_SUPER_USER' in the Expression box.

   • In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_Shipment_Notice_WSHDSNO_InputVariable >header > ns2:SOAHeader and select ns2:Responsibility. The XPath field should contain your selected entry.

   • Click OK.

4. Enter the second pair of parameters by selecting Copy Operation from the Create drop-down list with the following values:

   • In the From navigation tree, select type Expression and then enter 'ONT' in the Expression box.

   • In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_Shipment_Notice_WSHDSNO_InputVariable >header > ns2:SOAHeader and select ns2:RespApplication. The XPath field should contain your selected entry.

   • Click OK.

5. Enter the third pair of parameters by selecting Copy Operation from the Create drop-down list with the following values:

   • In the From navigation tree, select type Expression and then enter 'STANDARD' in the Expression box.

   • In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_Shipment_Notice_WSHDSNO_InputVariable >header > ns2:SOAHeader and select ns2:SecurityGroup. The XPath field should contain your selected entry.

   • Click OK.

6. Enter the fourth pair of parameters by selecting Copy Operation from the Create drop-down list with the following values:

   • In the From navigation tree, select type Expression and then enter 'AMERICAN' in the Expression box.

   • In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_Shipment_Notice_WSHDSNO_InputVariable >header > ns2:SOAHeader and select ns2:NLSLanguage. The XPath field should contain your selected entry.

   • Click OK.

7. Enter the fifth pair of parameters by selecting Copy Operation from the Create drop-down list with the following values:

   • In the From navigation tree, select type Expression and then enter '202' in the Expression box.

   • In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_Shipment_Notice_WSHDSNO_InputVariable >header > ns2:SOAHeader and select ns2:Org_Id. The XPath field should contain your selected entry.

   • Click OK.

8. The Edit Assign dialog box appears.

   Click Apply and then OK to complete the configuration of the Assign activity.

To add the second Assign activity to set order details to the Invoke_ShipmentNotice Invoke activity:

1. In JDeveloper BPEL Designer, drag and drop the Assign activity from the Component Palette into the Activity box of the process diagram, between Assign and Invoke activities.

2. Double-click the Assign activity to access the Edit Assign dialog box.

3. Click the General tab to enter the name for the Assign activity, such as 'SetOrderDetails'.

4. On the Copy Operation tab, click Create and then select Copy Operation from the menu. The Create Copy Operation window appears.

5. Enter the first pair of parameters:

   • In the From navigation tree, select type elect type Variable. Navigate to Variable > Process > Variables > InvokeReadOrder_SynchRead_OutputVariable > InputParameters and select ns1:InputParametersr.

     The XPath field should contain your selected entry.

   • In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > InvokeShipmentNotice_WSHDSNO_InputVariable > body and select ns1:InputParameters. The XPath field should contain your selected entry.

   • Click OK.

     Create Copy Operation Dialog for Assigning Parameters

     

6. The Edit Assign dialog box appears.

   Click Apply and then OK to complete the configuration of the Assign activity.

To add the third Assign activity to set SOAP response to output:

1. Add the third Assign activity by dragging and dropping the Assign activity from the Component Palette into the Activity box of the process diagram, between the Invoke and the Reply activities.

2. Repeat Step 2 to Step 4 described in creating the first Assign activity to add the third Assign activity called 'SetCPdetails'.

3. Enter the following information:

   • In the From navigation tree, select type Variable. Navigate to Variable > Process > Variables > InvokeShipmentNotice_WSHDSNO_OutputVariable and select body.

   • In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > OutputVariable and select payload.

   • Click OK.

4. Click Apply and then OK to complete the configuration of the Assign activity.

Deploying and Testing the BPEL Process at Run Time

After creating a BPEL process using the WSDL URL generated from the concurrent program interface definition, you can deploy it to a BPEL server if needed. To ensure that this process is modified or orchestrated appropriately, you can also manually test the BPEL process by initiating the business process contained in the BPEL process to test the interface integration.

Prerequisites

Before deploying the BPEL process using Oracle JDeveloper, you must ensure that you have established the connectivity between the deign-time environment and the run-time servers including the application server and the integration server.

How to configure the necessary server connection, see Configuring Server Connection.

To validate your BPEL process, perform the following run-time tasks:

1. Deploy the BPEL process

   Once you deploy the process to a BPEL server, it becomes available so that you can run the process manually to test it for validation.

2. Test the BPEL process

   After deploying a BPEL process, you can manage the process from the BPEL console to validate the interface integration contained in your BPEL process.

Deploying the BPEL Process

You must deploy the BPEL process (ShipNotice.bpel) that you created earlier before you can run it.

To deploy the BPEL process:

1. In the Applications Navigator of Oracle JDeveloper BPEL Designer, select the ShipNotice project.

2. Right-click the project and click Make action from the menu.

   Look for any compilation error messages in Message Log.

   Right-click the project and select Deploy >Integration Server Connection name > Deploy to Default Domain action from the menu.

   For example, you can select Deploy > BPELServerConn > Deploy to Default Domain to deploy the process if you have the BPEL Process Manager setup appropriately.

   Oracle JDeveloper for Deploying the BPEL Process

   

3. Look for 'Build successful' message in Apache Ant – Log. The BPEL project is compiled and successfully deployed.

Testing the BPEL Process

To validate whether the BPEL process that you created works or not, you need to manually initiate the process after it has been successfully deployed to the BPEL server. Therefore, the validation starts with the BPEL console to ensure that you can find the deployed BPEL process listed in the console. Then, you can log on to Oracle E-Business Suite to manually initiate the processes and to confirm that the departure shipment notice outbound (DSNO) is generated in the XML file.

To test the BPEL process:

1. Log in to Oracle Application Server 10g BPEL Console ( http://<soaSuiteServerHostName>:<port>/BPELConsole). The BPEL Console login page appears.

2. Enter the username and password and click Login. The Oracle Enterprise Manager 10g BPEL Console appears with a list of deployed BPEL processes.

   Oracle Enterprise Manager BPEL Console to View the Deployed Service

   

3. In the BPEL Console, confirm that ShipNotice has been deployed.

4. Click the ShipNotice link to open the Initiate tab.

5. Enter the payload input field and click Post XML Message to initiate the process.

6. The BPEL process is now initiated. You can check the process flow by clicking the Visual Flow icon.

   BPEL Console: BPEL Processes Tab: Initiate Subtab

   

7. Double-click the Invoke_ShipmentNotice icon from the process flow chart and click View XML document link to open the XML file. This file records the Request ID that is returned for the transaction.

Verifying Records in Oracle E-Business Suite

Before verifying the records in Oracle E-Business Suite, you must first ensure that the concurrent request is completed successfully.

1. Log in to Oracle E-Business Suite with the System Administrator responsibility. Select View > Requests to open the Find Requests window.

2. Search for the concurrent request by entering the Request Id that you got from the audit trail and then click Find.

3. The request details page is displayed. You can check the Phase and Status of the request to see if the Status of the request is Complete.

Once the concurrent request is completed successfully, you can validate it in Oracle E-Business Suite.

Since DSNO (departure shipment notice outbound) is an outbound XML message, relevant XML Gateway setup tasks must be configured appropriately in order for the shipment notice to be delivered to the right recipient.

See Oracle XML Gateway User's Guide for details.

You can validate if the ship-to address, purchase order, and requested ship date addressed in the DSNO XML file are the same in your sales order.