Home / Middleware / Integration Adapters

Using e-Commerce Gateway

This chapter covers the following topics:

• Overview of e-Commerce Gateway Integration
• Design-Time Tasks for e-Commerce Gateway
• Creating a New SOA Composite Application with BPEL Process
• Adding a Partner Link
• Adding a Partner Link for File Adapter
• Configuring Invoke Activities
• Configuring an Assign Activity
• Run-Time Tasks for e-Commerce Gateway
• Deploying the SOA Composite Application with BPEL Process
• Testing the Deployed SOA Composite Application with BPEL Process
• Verifying Records in Oracle E-Business Suite

Overview of e-Commerce Gateway Integration

Oracle e-Commerce Gateway provides a common, standards-based approach for Electronic Data Interchange (EDI) integration between Oracle E-Business Suite and third party applications. EDI is the computer to computer exchange of business documents in a standard format. The EDI format is commonly used for e-commerce transactions between businesses.

Oracle e-Commerce Gateway is the EDI integration enabler for Oracle E-Business Suite. It provides a single integration framework for you to conduct e-business using EDI standards with everyone in your global supply chain. Oracle e-Commerce Gateway provides an application integration infrastructure that is flexible enough to accommodate the integration requirements of any and all applications that must integrate with Oracle E-Business Suite. This allows for seamless flow of information in an ever expanding trading partner base.

Oracle e-Commerce Gateway includes prebuilt transactions of key business documents that can be implemented simply by defining a trading partner and enabling the transaction in test or production mode. You can implement a single transaction, a group of transactions, or a business flow. You can implement the prebuilt transactions as is or configure them to meet your specific industry needs.

Oracle e-Commerce Gateway uses a metadata driven approach to dynamically generate outbound and consume inbound flat files based on user defined trading partner, mapping, transformation, and data validation rules. You can change a rule by changing the metadata stored in the repository. The updated rule takes effect at run-time without any code modifications.

Note: For detailed information about Oracle e-Commerce Gateway, see Oracle e-Commerce Gateway User's Guide. This guide is part of the Oracle E-Business Suite Documentation Library which can be accessed on the Oracle Technology Network (OTN).

Oracle E-Business Suite Adapter can be configured to use e-Commerce Gateway to interact with third party applications. e-Commerce Gateway, like XML Gateway, is primarily used for Business-to-Business (B2B) integration. While XML transactions are mostly based on a single transaction and are event based, EDI transactions are more batch oriented.

Design-Time Tasks for e-Commerce Gateway

Oracle E-Business Suite Adapter is deployed using the BPEL Process Manager (PM) in Oracle JDeveloper. The BPEL PM creates the WSDL interfaces for the e-Commerce Gateway.

This section describes the tasks to configure Oracle E-Business Suite Adapter to use e-Commerce Gateway in Oracle JDeveloper.

SOA Composite Application with BPEL Process Scenario

This example uses IN: Ship Notice/Manifest (ECASNI) EDI concurrent program exposed as a Web service to support the inbound Ship Notice/Manifest transaction.

When a shipment request is received, the shipping details will be retrieved and then imported to the Purchasing system to create an electronic shipment notice as a pre-receipt.

When the SOA Composite application with BPEL process has been successfully executed after deployment, you should be able to validate if the shipment notice has been inserted in Oracle E-Business Suite with the same shipment identifier number.

Prerequisites to Configure e-Commerce Gateway

Populating Applications Context Header Variables

You need to populate certain variables in the BPEL PM in order to provide context information for Oracle E-Business Suite. The context information is required for an EDI transaction in order for an Oracle E-Business Suite user that has sufficient privileges to run the program.

The context is set taking into account the values passed for the header properties including Username, Responsibility, Responsibility Application, Security Group, and NLS Language. If the values for the new header properties Responsibility Application, Security Group, and NLS Language are not passed, context information will be determined based on Username and Responsibility.

The default Username is SYSADMIN, the default Responsibility is SYSTEM ADMINISTRATOR, the default Security Group Key is Standard, and the default NLS Language is US.

You can change the default values specified in the generated WSDL. This is a static way of changing the context information. These values would apply to all invocations of the deployed business process. However, if you need to provide different context information for different invocations of the business process, then you can dynamically populate the header values. The context information can be specified by configuring an Invoke activity.

For more information about applications context, see Supporting for Normalized Message Properties.

Based on the scenario described earlier, the following design-time tasks are discussed in this chapter.

1. Create a new SOA Composite application with BPEL process

2. Add a partner link

3. Add a partner link for File Adapter

4. Configure Invoke activities

5. Configure an Assign activity

Creating a New SOA Composite Application with BPEL Process

The first configuration task is to create a new SOA Composite application with BPEL process.

To create a new SOA Composite application with BPEL process

1. Launch Oracle JDeveloper.

2. Click New Application in the Application Navigator.

   The New Gallery page appears. Select SOA Application from the Items list.

   The New Gallery Page

   

   Click OK.

3. Click New Application in the Application Navigator.

   The Create SOA Application - Name your application page is displayed.

   The Create SOA Application - Name your application Page

   

4. Enter an appropriate name for the application in the Application Name field.

   Click Next. The Create SOA Application - Name your project page is displayed.

5. Enter an appropriate name for the project in the Project Name field. For example, InsertShipNotice.

   Notice that SOA Suite is shown in the Project Features section.

   The Create SOA Application - Name your project Page

   

6. Click Next. The Create SOA Application - Configure SOA settings page is displayed.

   The Create SOA Application - Configure SOA settings Page

   

7. Leave the default Standard Composite selection unchanged for the Start from field.

   Select Composite With BPEL Process from the Standard Composite list, and then click Finish. You have created a new application, and a SOA project. This automatically creates a SOA Composite.

   The Create BPEL Process page is displayed.

   The Create BPEL Process Page

   

8. Leave the default BPEL 2.0 Specification selection unchanged. This creates a BPEL project that supports the BPEL2.0 specification.

   Enter an appropriate name for the BPEL process in the Name field. For example, InsertShipNotice.

   Select Asynchronous BPEL Process in the Template field. Click OK.

   An asynchronous BPEL process is created with the Receive and Reply activities.

   

   The required source files including bpel and wsdl, using the name you specified (for example, InsertShipNotice.bpel and InsertShipNotice.wsdl) and InsertShipNotice (composite.xml) are also generated.

   

Adding a Partner Link

The next task is to add a partner link to the BPEL process. A partner link defines the link name, type, and the role of the BPEL process that interacts with the partner service.

Based on the BPEL process scenario, you need to create a partner link to create a ship notice.

To add a partner link

1. Click BPEL Services in the Component palette.

   Drag and drop Oracle E-Business Suite (formerly known as Oracle Applications) from the BPEL Services list into the right Partner Link swim lane of the process diagram. The Oracle E-Business Suite Reference page appears.

   Enter a reference name in the Name field. For example, ShipNotice.

2. Click Next. The Service Connection page appears.

3. You can perform either one of the following options for your database connection:

   Note: You need to connect to the database where Oracle E-Business Suite is running.

   • You can create a new database connection by clicking the Create a New Database Connection icon.

     How to define a new database connection, see Create a New Database Connection.

   • You can select an existing database connection that you have configured earlier from the Connection drop-down list.

     The Service Connection page will be displayed with the selected connection information. The JNDI (Java Naming and Directory Interface) name corresponding to the database connection appears automatically in the Database Server JNDI Name field. Alternatively, you can specify a JNDI name.

     Note: When you specify a JNDI name, the deployment descriptor of the Oracle E-Business Suite Adapter must associate this JNDI name with configuration properties required by the adapter to access the database.

     The JNDI name acts as a placeholder for the connection used when your service is deployed to the BPEL server. This enables you to use different databases for development and later for production.

     Note: For more information about JNDI concepts, refer to Oracle Fusion Middleware User's Guide for Technology Adapters.

4. Once you have completed creating a new connection for the service, you can add an interface by browsing through the available list in Oracle E-Business Suite.

   Click Next.

   If you are connecting to Oracle E-Business Suite Release 12, then the IREP File not present dialog appears indicating that Adapter could not find the Oracle Integration Repository data file corresponding to the database you are connecting in your workspace. Absence of the data file would make browsing or searching of Integration Repository tree considerably slow. You can choose to extract the data file and create a local copy of the Integration Repository data file. Once it is created successfully, Adapter will pick it up automatically next time and retrieve data from your local Integration Repository.

   You can select one of the following options:

   • Click Yes to extract the Integration Repository data file.

     After the system successfully creates a local copy of the Integration Repository data file, next time when you connect to the database, you will find the IRep Data File field appears in the Operation dialog indicating where your local copy exists with the creation date and time as part of the file name.

   • Click No to query the Integration Repository data file from the live database you are connecting to display the Integration Repository tree.

   In this example, click No. Click Next in the Operation page to open the Oracle E-Business Suite Module Browser.

5. Once you have identified an existing database connection or completed a new connection for the service, you can select an e-Commerce Gateway interface through the Module Browser.

   Note: Oracle E-Business Suite Module Browser includes the various product families that are available in Oracle E-Business Suite. For example, Applications Technology or Order Management Suite are product families in Oracle E-Business Suite. The product families contain the individual products. For example, Applications Technology contains the e-Commerce Gateway product. The product contains the business entities associated with the product. For example, the e-Commerce Gateway product contains the Advanced Shipment Notification business entity.

   Business entities contain the various application modules that are exposed for integration. These modules are grouped according to the interface they provide. EDI programs can be found under the EDI category.

   Specify an Interface from The Oracle E-Business Suite Module Browser

   

   Select an inbound or outbound EDI program. You can select only one EDI program for each adapter service.

   For example, navigate to Product Families > Applications Technology > e-Commerce Gateway > Advanced Shipment Notification > EDI to select EDI > IN: Ship Notice/Manifest (856/DESADV) (ECASNI) EDI concurrent program.

   Note: You can also search for an EDI program by entering the name of the program in the Object Name field. Select the EDI check box and click Search.

6. Click OK.

   The selected EDI concurrent program is added to Operation Objects.

   Adapter Configuration Wizard - Application Interface Page

   

   Click Next.

7. Click Finish to complete the process of configuring a partner link for an application service. The partner link is created with the required WSDL settings. The wizard also generates the WSDL file corresponding to the selected interface. This WSDL file is now available for the partner link.

   Note: When you click Finish, two SQL files may be added to the project if a wrapper does not exist for the function. A wrapper is generated the very first time you create the e-Commerce Gateway based service. Subsequent services reuse the same wrapper.

   Double click the newly generated Partner Link (ShipNotice) icon to view the details.

   Partner Link Configuration Details

   

Adding a Partner Link for File Adapter

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

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

1. In JDeveloper BPEL Designer, click BPEL Services in the Component palette.

   Drag and drop File Adapter from the BPEL Services list into the right Partner Link swim lane of the process diagram before the partner link InsertShipment. The Adapter Configuration Wizard Welcome page appears.

   Click Next.

2. In the Service Name dialog, enter a name for the file adapter service, such as getShippingDetails.

3. Click Next. The Adapter Interface page appears.

   Specifying the Adapter Interface

   

   Select the Define from operation and schema (specified later) radio button and click Next.

   The File Server Connection page appears. Leave the default value unchanged for the File Server JNDI Name field.

   Click Next

   

4. In the Operation dialog, specify the operation type. For example, select the Synchronous Read File radio button. This automatically populates the Operation Name field.

   Specifying the Operation

   

   Click Next to access the File Directories page.

5. Select the Physical Name radio button and specify directory for incoming files, such as /usr/tmp.

   Ensure the Delete files after successful retrieval check box is not selected.

   Configuring the Input File

   

   Click Next to open the File Name page.

6. Enter the name of the file for the synchronous read file operation. For example, enter order_data.xml. Click Next to open the Messages dialog.

7. Select the 'browse for schema file' icon to open the Type Chooser.

   Click Type Explorer and select Project Schema Files > ShipNotice_sp.xsd > InputParameters.

   The selected schema information will be automatically populated in the URL and Schema Element fields.

   Specifying Message Schema

   

8. Click Next and then Finish. This completes the configuration and creates the partner link with the required WSDL settings for the File Adapter service. The wizard also generates the getOrderXML.wsdl WSDL file corresponding to the partner link.

   The getShippingDetails Partner Link appears in the BPEL process diagram. Double click the Partner Link service icon to open the Edit Partner Link dialog and view the details.

   Partner Link Details

   

Configuring Invoke Activities

After adding and configuring the partner link, you can configure the following two Invoke process activities to invoke the EDI concurrent program and File Adapter partner link:

1. To get the shipping details that is received from the Receive activity by invoking the getShippingDetails partner link in an XML file.

2. To create a shipment notice by invoking ShipNotice partner link.

To add the first Invoke activity for a partner link to get shipping details:

1. In Oracle JDeveloper BPEL Designer, expand the BPEL Constructs from the Component Palette. Drag and drop the first Invoke activity into the center swim lane of the process diagram, between the receiveInput and callbackClient activities.

2. Link the Invoke activity to the getShippingDetails service. The Edit Invoke dialog appears.

3. Enter a name for the Invoke activity. In the Input tab, ensure the Input Variable radio button is selected. Click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog box appears.

   Create Input Variable

   

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

5. In the Output tab, ensure the Output Variable radio button is selected. Click the Create icon next to the Output Variable field to create a new variable. The Create Variable dialog box appears.

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

   

7. Click Apply and 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 a partner link to create a shipment notice:

1. In Oracle JDeveloper BPEL Designer, expand the BPEL Constructs from the Component Palette. Drag and drop the third Invoke activity into the center swim lane of the process diagram, between the first Invoke and callbackClient activities.

2. Link the Invoke activity to the ShipNotice service. The Edit Invoke dialog box appears.

   The Operation is automatically selected, depending on the EDI concurrent program that you chose when configuring the partner link.

3. Repeat Step 3 to Step 6 described in the first Invoke activity procedure.

   Click Apply and OK.

   

4. Setting Header Properties for Applications Context

   Use the following steps to set the header message properties required to pass applications context required to complete the BPEL process:

   1. Select the Properties tab to set the Header message properties required to pass applications context required to complete the BPEL process.

   2. Click the Create icon. The To Property dialog appears.

   3. Select the jca.apps.Username property from the Name drop-down list.

      

   4. Select the Expression radio button and enter 'OPERATIONS' as the property value.

      Click OK.

   5. Repeat Step 2 to Step 4 to assign 'Purchasing, Vision Operations (USA)' for jca.apps.Responsibility.

      

5. Click Apply and then OK to complete the Invoke activity.

Configuring an Assign Activity

Use the Assign activity to pass the output of getShippingDetails service as an input to the InsertShipment service.

To add an Assign activity:

1. In Oracle JDeveloper BPEL Designer, expand the BPEL Constructs from the Component Palette. Drag and drop the Assign activity from the Basic Activities section into the center swim lane of the process diagram between the two Invoke activities that you just created earlier.

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

   Click the General tab to enter a name for the Assign activity. For example, setShipInfo.

3. Select the Copy Rules tab and expand the source and target trees:

   • In the From navigation tree, navigate to Variable > Process > Variables > Invoke_SynchRead_OutputVariable > body and select ns3:InputParameters.

   • In the To navigation tree, navigate to Variable > Process > Variables > Invoke_Service_ShipNotice_InputVariable > Input Parameters and select ns3:InputParameters.

     Drag the source node (ns3:InputParameters) to connect to the target node (ns3:InputParameters) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

     Assigning Parameters

     

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

Completed Concurrent Program BPEL Process Project

Click the composite.xml to display the Oracle JDeveloper composite diagram:

Run-Time Tasks for e-Commerce Gateway

After designing the SOA Composite application with BPEL process, the next step is to deploy, run and monitor it.

1. Deploy the SOA Composite application with BPEL process

2. Test the deployed SOA Composite application with BPEL process

3. Verify records in Oracle E-Business Suite

Deploying the SOA Composite Application with BPEL Process

To invoke the service (InsertShipment) from the BPEL client contained in the SOA composite, the SOA composite needs to be deployed to the Oracle WebLogic managed server. This can be achieved using Oracle JDeveloper. Once the composite is deployed, it can be tested from the Oracle Enterprise Manager Fusion Middleware Control Console.

Prerequisites

Before deploying the SOA composite with BPEL process using Oracle JDeveloper, you must have established the connectivity between the design-time environment and the run-time server. For more information, see Configuring the Data Source in Oracle WebLogic Server and Creating an Application Server Connection.

Note: If a local instance of the WebLogic Server is used, start the WebLogic Server by selecting Run > Start Server Instance from Oracle JDeveloper. Once the WebLogic Admin Server "DefaultServer" instance is successfully started, the <Server started in Running mode> and DefaultServer started message in the Running:DefaultServer and Messages logs should appear.

To deploy the SOA Composite application with BPEL process

1. Select the SOA Composite project in the Applications Navigator.

2. Right-click the project name, and then select Deploy > [project name] > [serverConnection] from the menu that appears.

   For example, you can select Deploy > InsertShipNotice > soa-server1 to deploy the process if you have the connection set up appropriately.

   

   Note: If this is the first time to set up server connection, then the Deployment Action window appears. Select 'Deploy to Application Server' and click Next.

   

   In the Deploy Configuration window, ensure the following information is selected before clicking Next to add a new application server:

   • New Revision ID: 1.0

   • Mark composite revision as default: Select this check box.

   • Overwrite any existing composites with the same revision ID: Select this check box.

   The steps to create a new Oracle WebLogic Server connection from JDeveloper are covered in Creating an Application Server Connection.

3. In the Select Server page, select 'soa-server1' that you have established the server connection earlier. Click Next.

4. In the SOA Servers page, accept the default target SOA Server ('soa-server1') selection.

   

   Click Next and Finish.

   If you are deploying the composite for the first time from your Oracle JDeveloper session, the Authorization Request window appears. Enter username and password information specified during Oracle SOA Suite installation. Click OK.

5. Deployment processing starts. Monitor deployment progress and check for successful compilation in the SOA - Log window.

   Verify that the deployment is successful in the Deployment - Log window.

Testing the Deployed SOA Composite Application with BPEL Process

Once the BPEL process contained in a SOA Composite application is deployed, you can manage and monitor the process from the Oracle Enterprise Manager Fusion Middleware Control Console. You can also test the integration by manually initiating the process.

To test the deployed SOA Composite application with BPEL process

1. Navigate to Oracle Enterprise Manager Fusion Middleware Control Console (http://<servername>:<portnumber>/em). The composite you deployed is displayed in the Applications Navigation tree.

   

2. Enter username (such as weblogic) and password and click Login to log in to a farm.

   You may need to select an appropriate target instance farm if there are multiple target Oracle Enterprise Manager Fusion Middleware Control Console farms.

3. From the Farm base domain, expand the SOA > soa-infra > soa-infra (soa_server1) > default to navigate through the SOA Infrastructure home page and menu to access your deployed SOA Composite applications running in the SOA Infrastructure for that managed server.

   Note: The Farm menu always displays at the top of the navigator. As you expand the SOA folder in the navigator and click the links displayed beneath it, the SOA Infrastructure menu becomes available at the top of the page.

   Click the SOA Composite application that you want to initiate (such as 'InsertShipment') from the SOA Infrastructure.

   Click Test at the top of the page.

4. The Test Web Service page for initiating an instance appears. You can specify the XML payload data to use in the Input Arguments section.

   Enter the input string required by the process and click Test Web Service to initiate the process.

   Testing Web Service

   

   The test results appear in the Response tab upon completion.

5. Click Launch Flow Trace in the Test Web Service page. The Flow Trace page is displayed.

   In the Trace section, you should find the sequence of the message flow for the service binding component (insertshipnotice_client_ep), BPEL component (ShipNotice), and reference binding components (getShippingDetails and ShipNotice). All involved components have successfully received and processed messages.

   If any error occurred during the test, you should find it in the Faults section.

6. Click your BPEL service component instance link (such as ShipNotice) to display the Instances page where you can view execution details for the BPEL activities in the Audit Trail tab.

   Click the Flow tab to check the BPEL process flow diagram. Click an activity of the process diagram to view the activity details and flow of the payload through the process.

Verifying Records in Oracle E-Business Suite

To verify retcords in Oracle E-Business Suite

1. Log in to Oracle E-Business Suite as the System Administrator.

2. Select Requests from the View menu.

3. Search for the Request by entering the Request Id that you got from the audit trail, then click Find.

   Find Requests Dialog Box

   

4. The Request details are displayed. You can check for details such as the Phase and Status of the request.

5. If the Status of the request is Complete, you can also query the appropriate table in Oracle E-Business Suite to search for the relevant records that have been inserted.

   Querying Oracle E-Business Suite for a Record