Oracle E-Business Suite Integrated SOA Gateway Developer's Guide Release 12.1 Part Number E12065-06

Contents

Previous

Next

Using Java APIs for Forms Services

Overview

Java APIs are business interfaces based on Java classes. Some specialized Java classes are XML document-based integration points wrapped in Java classes for executing business logic in Oracle Forms. These Java classes are categorized with subtype 'Java APIs for Forms'. You can locate them through performing a search with 'subtype of an interface' category and 'Java APIs for Forms' as category value.

Similar to other service enabled integration interface types, Oracle E-Business Suite Integrated SOA Gateway allows these specialized Java classes to be service enabled through SOA Provider.

Once this XML document-based integration point becomes a Web service, the generated Web service can be deployed from the Oracle Integration Repository to Oracle Application Server. Services can then be exposed to customers through service provider and invoked through any of the Web service clients or orchestration tool including Oracle JDeveloper, Apache Axis, .NET Web Service Client, Oracle BPEL Process Manager, and Oracle Enterprise Service Bus (ESB).

To better understand how each individual Web service represented in WSDL URL can be used in inserting or updating application data, detailed design-time and run-time tasks in creating and deploying a BPEL process are 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 Java APIs for Forms Services at Design Time

BPEL Process Scenario

This example uses CreateAndMaintainSalesOrdersoracle.apps.ont.services.oexoeord.OEXOEORDServices_DocStyle Java API for Forms interface to explain the BPEL process creation.

When a create order request is received, the order information including header and line items will be read and passed to create a sales order. Once the order is created, the order number will then be returned to the requestor.

If the BPEL process is successfully executed after deployment, you should find a sales order is created in the Oracle E-Business Suite. The order number should be the same as the payload input value.

Prerequisites to Create a BPEL Process Using a Java API for Forms Web Service

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

• An integration repository administrator needs to successfully generate and deploy a Web service to the application server.

• An integration developer needs to locate and record the deployed WSDL URL for the document-based Java interface exposed as a Web service.

• SOAHeader variables need to be populated for Web service authorization.

Deploying a Java API for Forms WSDL URL

An integration repository administrators must first create a Web service for a selected document-based Java 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 the integration developers use the deployed WSDL in creating a BPEL process:

1. To generate a Web service, locate the Java API for Forms interface definition first (such as CreateAndMaintainSalesOrders oracle.apps.ont.services.oexoeord.OEXOEORDServices_DocStyle) through a search.

   Searching Java APIs for Forms Interfaces

   

   From the main Search page, click Show More Search Options to display more fields for search. Enter the following criteria:

   • Category: Interface Subtype

   • Category Value: Java API for Forms

   Click Go to execute the search. This retrieves all Java APIs for Forms interfaces from the Oracle Integration Repository.

   Click the CreateAndMaintainSalesOrders Java API for Forms link to display the interface details page and click Generate WSDL.

   Once the service is successfully generated, the Web Service - SOA Provider region appears in the interface details page. For detailed instruction on how to generate a Web service, see Generating Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

2. To deploy a generated Web service, select at least one authentication type and click Deploy in the Web Service - SOA Provider region 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, Undeploying, and Redeploying Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Searching and Recording WSDL URL

Apart from the required tasks performed by the administrators, an integration developer also needs to log on to the system to locate and record the deployed Web service WSDL URL for the interface that needs to be orchestrated into a meaningful business process in Oracle JDeveloper using BPEL language.

This WSDL information will be used later in creating a partner link for the interface exposed as a Web service during the BPEL process creation at design time.

Viewing and Recording a Deployed WSDL URL

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 would be used to set applications context during service execution. These SOAHeader elements for Java APIs for Forms interfaces 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:

Note:

• Unlike SOAHeader used in other interface types to set context header, Org_Id is a mandatory value that must be passed when using a Java APIs for Forms service.

• NLS Language is an optional value 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.

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

Detailed information on how to set SOAHeader for the SOAP request, see Assigning SOAHeader Parameters.

BPEL Process Creation Flow

Based on the sales order creation 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 CreateSalesOrder.bpel using an Synchronous BPEL Process template. 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 an order in Oracle E-Business Suite by using the CreateAndMaintainSalesOrders (oracle.apps.ont.services.oexoeord.OEXOEORDServices_DocStyle) API exposed as a Web service.

3. Add a Partner Link for File Adapter

   Use this step to synchronous read order header details passed from the first Assign activity.

4. Add Invoke activities

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

   • Point to the File Adapter to synchronous read order header details that is passed from the first Assign activity.

   • Point to the OEXOEORDServices_DocStyle partner link to initiate the order creation with payload and transaction details received from the Assign activities.

5. Add Assign activities

   Use this step to configure Assign activities in order to pass order header details, payload information and order number to appropriate Invoke activities to facilitate order creation. At the end, pass the order number to the request application through the dummy Reply activity.

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.

   Entering BPEL Project Information

   

7. In the Name field, enter a descriptive name such as CreateSalesOrder.

8. From the Template list, select Synchronous BPEL Process. 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 CreateSalesOrder.bpel) are also generated.

Creating a Partner Link

Use this step to create a Partner Link called OEXOEORDServices_DocStyle.

To create a partner link for CreateOrder 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 deployed WSDL URL corresponding to the CreateAndMaintainSalesOrders service that you recorded earlier in the WSDL File field.

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, Partner Link Type values populated automatically.

   You can select appropriate values for the Partner Role and My Role fields.

   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.

   

4. You can optionally change the default partner link name by double-clicking the icon to open the Edit Partner Link window if you like.

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

   Click Apply.

   Editing the Partner Link

   

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.

   Adding Properties

   

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 reading current contents of a file.

To add a Partner Link for File Adapter to Read Payload:

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 such as ReadPayload. You can add an optional description of the service.

4. Click Next. The Operation dialog box appears.

   Specifying the Operation

   

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 'Input.xml'. Click Next. The Messages dialog box appears.

   Specifying Message Schema

   

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 in the Import Schema File pop-up window.

      Schema location for your service can be found from the service WSDL URL (for example, http://<myhost>:<port>/webservices/SOAProvider/java/oracle/apps/ont/services/oexoeord/OEXOEORDServices_DocStyle/?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 an appropriate schema element by expanding the Imported Schemas folder. Click OK.

      The selected schema location and element values are displayed.

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 ReadPayload.wsdl.

   Completing the 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 ReadPayload Partner Link appears in the BPEL process diagram.

   Adding the Partner Link for File Adapter

   

Adding Invoke Activities

This step is to configure two Invoke activities:

• Read sales order creation details that is passed from the first Assign activity using ReadPayload partner link for File Adapter.

• Send the payload and order details received from the Assign activities to create an sales order by using the CreateSalesOrder partner link.

To add an Invoke activity for ReadPayload Partner Link:

1. In 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 ReadPayload service. The Invoke activity will send invoice data to the partner link. The Edit Invoke dialog box appears.

   Editing the Invoke Activity

   

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.

   Creating a Variable

   

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 to create a new variable. The Create Variable dialog box appears.

   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.

   Adding an Invoke Activity

   

To add an Invoke activity for OEXOEORDServices_DocStyle Partner Link:

1. In 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 OEXOEORDServices_DocStyle 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 'InvokeCreateOrder'. Click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog box appears.

   Creating a Variable

   

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

4. click the Create icon next to the Output Variable field to create a new variable. The Create Variable dialog box appears.

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

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

   Adding an Invoke Activity

   

Adding Assign Activities

This step is to configure four Assign activities:

1. To set the SOAHeader for SOAP request.

   Note: You need to 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 are Responsibility, RespApplication, SecurityGroup, NLSLanguage, and Org_Id.

2. To pass the payload information to the InvokeCreateOrder Invoke activity.

3. To pass the order number information to the InvokeCreateOrder Invoke activity.

4. To pass the order number information back to the dummy Reply activity.

To add the first Assign activity to set SOAHeader for SOAP request:

Assigning SOAHeader Parameters:

1. In JDeveloper BPEL Designer, drag and drop the Assign activity from the Component Palette into the Activity box of the process diagram, between the two 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 'SetHeader'.

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 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 > InvokeCreateOrder_createSalesOrder_InputVariable > header> ns1:SOAHeader and select ns1:Responsibility. The XPath field should contain your selected entry.

     Assigning the Responsibility Parameter

     

   • Click OK.

6. 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 > InvokeCreateOrder_createSalesOrder_InputVariable > header> ns1:SOAHeader and select ns1:RespApplication. The XPath field should contain your selected entry.

   • Click OK.

7. Enter the third pair of parameters:

   • 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 > InvokeCreateOrder_createSalesOrder_InputVariable > header> ns1:SOAHeader and select ns1:SecurityGroup. The XPath field should contain your selected entry.

   • Click OK.

8. Enter the fourth pair of parameters:

   • 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 > InvokeCreateOrder_createSalesOrder_InputVariable > header> ns1:SOAHeader and select ns1:NLSLanguage. The XPath field should contain your selected entry.

   • Click OK.

9. 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 '204' in the Expression box.

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

   • Click OK.

10. The Edit Assign dialog box appears.

    Assign Parameters

    

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

To enter the second Assign activity to pass payload information to the InvokeCreateOrder Invoke activity:

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

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

3. Enter the following information:

   • In the From navigation tree, navigate to Variable > Process > Variables > InvokeReadPayload_SynchRead_OutputVariable and select an appropriate variable.

   • In the To navigation tree, select type Variable and then navigate to Variable > Process > Variables > InvokeCreateOrder_createSalesOrder_InputVariable > Body and select ns1:createSalesOrder_Request. The XPath field should contain your selected entry.

   • Click OK.

4. The Edit Assign dialog box appears.

   Assign Parameters

   

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

Defining Schema for BPEL Process Input Request

Before setting the input request for the SOAP request, you need to define necessary schema for BPEL process request.

1. From the Applications Navigator window, expand the CreateSalesOrder > Integration Content > Schemas folder to open the CreateSalesOrder.xsd file.

2. In the Design mode, expand 'CreateSalesOrderProcessRequest' to view elements within process request.

   Defining Schema for BPEL Process Request

   

3. From element properties, change the name from 'input' to ‘ordernumber’.

4. Right-click on mouse and select Rebuild option.

   Look for compilation messages in Log to ensure the successful compilation.

To enter the third Assign activity to pass the order number to the InvokeCreateOrder Invoke activity:

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 second Assign activity and the InvokeCreateOrder Invoke activity.

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

3. Enter the following information:

   • In the From navigation tree, navigate to Variable > Process > Variables > inputVariable > Payload > client:CreateSalesOrderProcessRequest and select client:ordernumber. The XPath field should contain your selected entry.

   • In the To navigation tree, select type Variable and then navigate to Variable > Process > Variables > InvokeCreateOrder_createSalesOrder_InputVariable > Body > ns1:createSalesOrder_Request > ns3:ViewAndUpdateSalesOrderHeaderDetails and select ns3:OrderNumber. The XPath field should contain your selected entry.

     

   • Click OK.

4. The Edit Assign dialog box appears.

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

To add the fourth Assign activity to reply back customer order number:

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 InvokeCreateOrder Invoke and the Reply activities.

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

3. Enter the following information:

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

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

   • Click OK.

4. The Edit Assign dialog box appears.

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

Deploying and Testing the BPEL Process

After creating a BPEL process using the WSDL URL generated from the Java API for Forms 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 manually initiate the business process and test the interface integration contained in your BPEL process.

Deploying the BPEL Process

You must deploy the Create Sales Order BPEL process (CreateSalesOrder.bpel) that you created earlier before you can run it.

To deploy the BPEL process:

1. In the Applications Navigator of JDeveloper BPEL Designer, select the CreateSalesOrder 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.

3. Look for ‘Build successful’ message in Apache Ant – Log to ensure that 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 validate the process creation.

To test the BPEL process:

1. Log into 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 Control appears. The list of deployed processes is shown under Deployed BPEL Processes. You can confirm that CreateSalesOrder has been deployed.

3. Click the CreateSalesOrder link to open the Initiate tab

4. In the payload section, enter an unique number in the ordernumber field, such as BPEL_1, and click Post XML Message to initiate the process.

5. Verifying Records in Oracle E-Business Suite

   Log on to the Forms-based Oracle E-Business Suite with the Oracle Management Super User, Vision Operation (USA) responsibility.

6. Select Order Returns > Sales Order. Sales Order Forms would open up.

7. Search for an order by entering the order number (such as BPEL_1) in the Customer PO field. This would bring up the details of a newly created order.

Copyright © 2008, 2010, Oracle and/or its affiliates. All rights reserved.