Skip Headers
Oracle® Application Server Adapter for SAP R/3 User's Guide
10g Release 2 (10.1.2)
B14061-02
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

4 Integration with BPEL Process Manager

OracleAS Adapter for SAP integrates seamlessly with Business Process Execution Language (BPEL) Process Manager to facilitate Web service integration. BPEL Process Manager is based on the Service-Oriented Architecture (SOA). It consumes adapter services exposed as Web Service Definition Language (WSDL) documents.

This chapter includes the following topics:

Overview of Adapter Integration with BPEL Process Manager

To integrate with BPEL Process Manager, OracleAS Adapter for SAP must be deployed in the same OC4J container as BPEL Process Manager. The underlying adapter services must be exposed as WSDL files, which are generated during design time in Oracle Application Server Adapter Application Explorer (Application Explorer) for both request-response (outbound) and event notification (inbound) services of the adapter. See Generating Web Service Definition Language (WSDL) (J2CA Configurations Only) for more information.

The generated WSDL files are used to design the appropriate BPEL processes for inbound or outbound adapter services. A completed BPEL process must be successfully compiled in a BPEL designer and deployed to a BPEL server. Upon deployment to the BPEL server, every newly built process is automatically deployed to the Oracle BPEL Console, where you run, monitor, and administer BPEL processes, as well as listen to adapter events.


See Also:

  • Oracle Application Server Adapter Concepts

  • Oracle BPEL Process Manager Developer's Guide


Deployment of Adapter

During installation, OracleAS Adapter for SAP is deployed as a J2CA 1.0 resource adapter within the OC4J J2CA container. The adapter must be deployed in the same OC4J container as BPEL Process Manager.


See Also:

Oracle Application Server Adapter Concepts

Design Time

The following tools are required to complete your adapter design-time configuration:


Note:

The examples in this chapter demonstrate the use of JDeveloper.

Before you design a BPEL process, you must create a schema and generate the respective WSDL file using Application Explorer. See Generating Web Service Definition Language (WSDL) (J2CA Configurations Only) for more information.

Design a BPEL Process for Request-Response Service (Outbound)

An outbound BPEL process consists of PartnerLink, Invoke, and Assign process activities. You must first create a new BPEL Process Manager connection and a synchronous BPEL process template. 

Create a New Connection to BPEL PM Server

To create a new BPEL Process Manager connection:

  1. To display the connections, click the Connections tab at the bottom of the upper left pane in JDeveloper.

    Connections window
    Description of the illustration bpel_30.gif

  2. Right-click BPEL Process Manager Server and select New BPEL Process Manager Connection.

    The Create BPEL Process Manager Connection - Welcome dialog box is displayed.

    Welcome screen
    Description of the illustration bpel_31.gif

  3. Click Next.

    The Create BPEL Process Manager Connection dialog box is displayed.

    BPEL PM Server Connection Wizard -- specify connection name
    Description of the illustration bpel_32.gif

  4. Specify a unique name for your BPEL Server connection and click Next.

    The Create BPEL Process Manager Connection dialog box is displayed.

    Specify connection parameters
    Description of the illustration bpel_33.gif

  5. Specify a valid host name and port number for the BPEL PM Server you wish to connect to.

  6. Click Finish.

    Your newly created server connection is displayed in the Connections tab under the BPEL Process Manager Server node.

    Server connection
    Description of the illustration bpel_34.gif

Create a New BPEL Project for Outbound Interaction (Synchronous Process)

To create a new BPEL project for a synchronous process:

  1. At the bottom of the upper left pane, click the Applications tab and select a workspace for your project.

    JDeveloper Applications tab
    Description of the illustration bpel_35.gif

  2. Right-click the workspace and select New Project.

    The New Gallery window is displayed.

    New Gallery window
    Description of the illustration bpel_1.gif

  3. From the Items list, select BPEL Process Project and click OK.

    The BPEL Process Project dialog box is displayed.

    BPEL Process Project window
    Description of the illustration bpel_2.gif

  4. Perform the following steps:

    1. Specify a name for the BPEL process.

      The Namespace field is updated automatically.

    2. From the Template drop-down list, select Synchronous BPEL Process.

  5. Click OK.

Create an Outbound PartnerLink Activity

When designing a BPEL process, a PartnerLink activity must be created to invoke the SAP service. A PartnerLink describes a set of operations within a Web service. The WSDL document is the external contract to which the Web service conforms. Given a WSDL, any BPEL process can initiate a Web service through a PartnerLink.

To create an outbound PartnerLink using the WSDL file you generated in Application Explorer:

  1. From the Process Activities pane on the right, drag and drop a PartnerLink to the visual editor.

    The Create Partner Link dialog box is displayed.

    Create Partner Link window
    Description of the illustration bpel_4.gif

  2. Click the WSIL browser icon (second icon from the left the WSDL File field).

    The WSDL Chooser dialog box is displayed.

    WSDL Chooser window
    Description of the illustration bpel_5.gif

  3. Expand your new connection, then expand adapters, and then applications.

    The WSDL tree displayed in the WSDL Chooser dialog box lists any WSDL files you have created using Application Explorer. The WSDL tree is generated by a WSDL servlet, which is automatically deployed as part of the BPEL Server installation.

    WSDL tree
    Description of the illustration bpel_6.gif


    Note:

    If you have organized your WSDL files in subfolders, the WSIL browser will display the full tree structure of your WSDL hierarchy. By default, the names of all WSDL files generated for outbound adapter services end with _invoke.

  4. Select BAPI_COMPANYCODE_GETDETAIL_invoke.wsdl and click OK.

    The WSDL File field in the Create Partner Link dialog box displays the name and location of the selected WSDL file. The Partner Link Type field specifies the PartnerLink defined in the WSDL file.

    Create Partner Link
    Description of the illustration bpel_7.gif

    Perform the following steps:

    1. Leave the My Role field unspecified. The role of the PartnerLink is null, as it will be synchronously invoked from the BPEL process.

    2. From the Partner Role drop-down list, select the default value BAPI_COMPANYCODE_GETDETAILRole. This is the role of the BPEL process.

  5. Click OK.

    The new PartnerLink appears in the visual editor.

    New PartnerLink
    Description of the illustration bpel_8.gif

  6. Select Save from the File menu.

Create an Outbound Invoke Activity

This activity enables you to specify an operation you want to invoke for the service identified by its PartnerLink. The Invoke activity opens a port in the process that is used to send and receive data. It uses this port to submit required data and receive a response. For synchronous callbacks, only one port is needed for both the send and the receive functions.

To create an outbound Invoke activity:

  1. From the Process Activities pane on the right, drag an Invoke activity to the visual editor and place it between the Receive activity (receiveInput) and the Reply activity (replyOutput).

  2. Extend a connection between the Invoke activity and your newly-created PartnerLink.

    The Edit Invoke dialog box is displayed. Note that the Partner Link and Operation fields are automatically populated with your WSDL files.

    New PartnerLink
    Description of the illustration bpel_9.gif


    Note:

    Ignore any invalid settings and error warnings.

    Perform the following steps:

    1. In the Name field, provide a meaningful name for the Invoke activity.

    2. Click the first icon to the right of the Input Variable field, then click OK in the Create Variable window that is displayed.

      A global variable is automatically created in the Input Variable field.

    3. Click the first icon to the right of the Output Variable field, then click OK in the Create Variable window that is displayed.

      A global variable is automatically created in the Output Variable field.

    4. Click Apply.

      The Edit Invoke window should no longer display any warnings or errors.

  3. Click OK.

  4. Select Save from the File menu.

Create an Assign Activity

An Assign activity provides a method for simple data manipulation, such as copying the contents of one variable to another. This Assign activity maps the input variable of the SAP process to the SAP PartnerLink input.

To create an Assign activity:

  1. From the Process Activities pane on the right, drag an Assign activity to the visual editor and place it between the Receive activity (receiveInput) and the new Invoke activity (GetCompanyDetail).

  2. Double-click the Assign activity icon.

    The Assign dialog box is displayed.

    Assign dialog box
    Description of the illustration bpel_14.gif


    Note:

    Ignore any invalid settings and error warnings.

  3. In the Copy Rules tab, click Create.

    The Create Copy Rule dialog box is displayed.

    1. In the From pane, expand Variables, then inputVariable, and then highlight payload.

    2. In the To pane, expand Variables, then GetCompanyDetail_BAPI_COMPANYCODE_GETDETAIL_InputVariable, and then highlight input_BAPI_COMPANYCODE_GETDETAIL.

    Your Create Copy Rule dialog box should look as follows:

    Create Copy Rule window
    Description of the illustration bpel_10.gif

  4. To close the Create Copy Rule dialog box and the Assign dialog box, click OK.

Create a Second Assign Activity

This Assign activity maps the output variable of the SAP process to the SAP PartnerLink output.

To create a second Assign activity:

  1. From the Process Activities pane on the right, drag another Assign activity to the visual editor and place it between the Invoke activity (GetCompanyDetail) and the Reply activity (replyOutput).

  2. Double-click the Assign activity icon.

    The Assign settings dialog box is displayed.

    Assign dialog box
    Description of the illustration bpel_14.gif


    Note:

    Ignore any invalid settings and error warnings.

  3. In the Copy Rules tab, click Create.

    The Create Copy Rule dialog box is displayed. Perform the following steps:

    1. In the From pane, expand Variables, then GetCompanyDetail_BAPI_COMPANYCODE_GETDETAIL_OutputVariable, and then highlight output_BAPI_COMPANYCODE_GETDETAIL.

    2. In the To pane, expand Variables, then outputVariable, and then highlight payload.

    Your Create Copy Rule dialog box should look as follows:

    Second Create Copy Rule window
    Description of the illustration bpel_11.gif

  4. To close the Create Copy Rule dialog box and the Assign dialog box, click OK.

  5. Select Save from the File menu.

The following image shows the diagram view of your completed BPEL process.

Completed BPEL process
Description of the illustration bpel_12.gif

See Invoking Adapter Request-Response Service from BPEL Process Manager for information on how to deploy and manage your outbound process.


See Also:

  • Oracle BPEL Process Manager Developer's Guide

  • Oracle Application Server Adapter Concepts


Design a BPEL Process for Event Handling (Inbound)

An inbound BPEL process consists of a PartnerLink and a Receive process activity. You must first create a channel and a new BPEL Process Manager Server connection. See Chapter 5, "BPEL Process Manager Integration Examples" for complete instructions on how to perform these procedures. 


Note:

You must create a separate channel for every inbound J2CA service and select that channel when you generate WSDL for inbound interaction using Application Explorer. Do not start the channel in Application Explorer, as BPEL Process Manager manages endpoint activation independently. See SAP Event Integration for more information.

Create a New BPEL Project for Inbound Interaction (Empty Process)

Before you create a BPEL project, verify that your BPEL Server is running. After you have created a new server connection, you are ready to design an empty process template for your BPEL project.

To create a new BPEL project for inbound interaction:

  1. Click the Applications tab and select a workspace for your project.

    JDeveloper Applications tab
    Description of the illustration bpel_35.gif

  2. Right-click the workspace and select New Project.

    The New Gallery window is displayed.

    New Gallery window
    Description of the illustration bpel_1.gif

  3. From the Items list, select BPEL Process Project and click OK.

    The BPEL Process Project dialog box is displayed.

    BPEL Process Inbound
    Description of the illustration bpel_22.gif

  4. Perform the following steps:

    1. Specify a name for the process.

      The Namespace field is updated automatically.

    2. From the Template drop-down list, select Empty BPEL Process.

    3. Click OK.

Create an Inbound PartnerLink Activity

When designing a BPEL process, a PartnerLink activity must be created to invoke the SAP service. A PartnerLink describes a set of operations within a Web service. The WSDL document is the external contract to which the Web service conforms. Given a WSDL, any BPEL process can initiate a Web service through a PartnerLink.

To create an inbound PartnerLink using the WSDL file you generated in Application Explorer:

  1. From the Process Activities pane on the right, drag and drop a PartnerLink to the visual editor.

    The Create Partner Link dialog box is displayed.

    Create Partner Link window
    Description of the illustration bpel_4.gif

  2. Click the WSIL browser icon (second icon from the left the WSDL File field).

    The WSDL Chooser dialog box is displayed.

    WSDL Chooser window
    Description of the illustration bpel_5.gif

  3. Expand your new connection, then expand adapters, and then applications.

    The WSDL tree displays the WSDL files you created using Application Explorer. The WSDL tree is generated by a WSDL servlet, which is automatically deployed as part of the BPEL Server installation.

    WSDL tree
    Description of the illustration bpel_6.gif


    Note:

    If you have organized your WSDL files in subfolders, the WSIL browser will display the full tree structure of your WSDL hierarchy. By default, the names of all WSDL files generated for inbound adapter services end with _receive.

  4. Select BAPI_COMPANYCODE_GETDETAIL_receive.wsdl and click OK.

    The Create Partner Link dialog box is displayed.

    Create Partner Link Dialog Box
    Description of the illustration bpel_24.gif

    The WSDL File field displays the name and location of the selected WSDL file. The Partner Link Type field specifies the PartnerLink defined in the WSDL file.

    Perform the following steps:

    1. From the My Role drop-down list, select the default value BAPI_COMPANYCODE_GETDETAILRole.

    2. Leave the Partner Role field unspecified.

  5. Click Apply, and then OK.

    The new SAP_2 PartnerLink appears in the visual editor.

    Completed inbound PartnerLink
    Description of the illustration bpel_25.gif

  6. Select Save from the File menu.

Create an Inbound Receive Activity

To create an inbound Receive Activity:

  1. From the Process Activities pane on the right, drag a Receive activity to the visual editor and place it in the designated placeholder labeled Drop Activity Here.

  2. Double-click the Receive activity.

    The Receive dialog box is displayed.

    Receive dialog box
    Description of the illustration bpel_26.gif

    Perform the following steps:

    1. From the Partner Link drop-down menu, select the PartnerLink you created in the previous step.

      The Operation field is automatically populated.

    2. Click the first icon to the right of the Variable field, then click OK in the Create Variable dialog box that is displayed.

    3. Verify that the Create Instance check box is selected.

  3. Click Apply.

    The Receive dialog box should no longer display any warnings or errors.

    Receive dialog box
    Description of the illustration bpel_27.gif

  4. Click OK.

    A connection is created between the PartnerLink and the Receive activity. You have completed the design of your inbound BPEL process.

See Listening to Adapter Events Inside BPEL Process Manager for information on how to deploy and manage your inbound process.


See Also:

  • Oracle BPEL Process Manager Developer's Guide

  • Oracle Application Server Adapter Concepts


Invoking Adapter Request-Response Service from BPEL Process Manager

The OracleAS Adapter for SAP request-response service is used to create, delete, update, and query back-end data as well as to call back-end workflows and transactions. The following section describes how to invoke the adapter synchronous request-response service, also referred to as Outbound Interaction, as well as how to manage the process in Oracle BPEL Console.

Deploy the Outbound BPEL Process

The procedures for deploying an inbound and an outbound BPEL process using the JDeveloper interface are identical.

To deploy your BPEL process in JDeveloper:

  1. Right-click your process flow in the Applications - Navigator pane.

  2. Select Deploy > Your BPEL PM Server connection > Deploy to default domain.

    The Password Prompt dialog box is displayed.

    Password Prompt dialog box
    Description of the illustration bpel_15.gif

  3. In the Domain Password field, enter your BPEL Process Manager password.

    The deployment process starts automatically after you enter the correct password.

  4. Observe the Messages log on the bottom of the window.

    The Messages log displays the deployment status. In this example, it shows a successful deployment message for the process.

    JDeveloper Messages log
    Description of the illustration bpel_16.gif

    If deployment was not successful, click the Compiler tab to view all error and warning messages generated during the deployment process.

Manage the Deployed Outbound Process in Oracle BPEL Console

JDeveloper deploys the developed process directly to the Oracle BPEL Console, which enables youto run, monitor, and administer BPEL processes.

To invoke adapter request-response service:

  1. Start the Oracle BPEL Console by entering the following URL in a browser:

    http://host:port/BPELConsole
    
    
  2. Select a domain and provide a valid password.

    The Oracle BPEL Console main page is displayed. All deployed BPEL processes are listed in the Dashboard tab.

    BPEL Console showing the newly-deployed BPEL process
    Description of the illustration bpel_17.gif

  3. Click the BPEL Processes tab.

    This tab provides a more detailed view of each deployed process.

    BPEL Console BPEL Processes tab
    Description of the illustration bpel_18.gif

  4. Click the SAP process link, demo_process (v. 1.0).

    The Manage window provides options for managing this BPEL process. Do not change any of the following default settings.

    Oracle BPEL Console Manage tab
    Description of the illustration bpel_19.gif

  5. Click the Initiate tab.

    The Initiate tab enables you to test your BPEL process.

    Oracle BPEL Console Initiate window
    Description of the illustration bpel_20.gif

    Perform the following steps:

    1. From the Initiating a test instance drop-down menu, select XML Source.

    2. Enter the following code in the text area provided for XML input:

      <?xml version="1.0" encoding="UTF-8"?>
      <CompanyCode.GetDetail SERVICENAME="CompanyCodeGetDetail" METHODNAME="BAPI_COMPANYCODE_GETDETAIL" LICENSE="test" CompanyCodeId="1000"/>
      
      
  6. Click Post XML Message.

    The response received from the SAP system is displayed in the Initiate window.


See Also:

Oracle Application Server Adapter Concepts

Listening to Adapter Events Inside BPEL Process Manager

The OracleAS Adapter for SAP event notification service, also referred to as Inbound Interaction, is used to listen to events that occur in an EIS. The following section describes how to deploy your inbound BPEL process and listen to adapter events at runtime using Oracle BPEL Console.

Deploy the Inbound BPEL Process

The procedures for deploying an inbound and an outbound BPEL process using the JDeveloper interface are identical.

To deploy your BPEL process in JDeveloper:

  1. Right-click your process flow in the Applications pane.

  2. Select Deploy > Your BPEL PM Server connection > Deploy to default domain.

    The Password Prompt dialog box is displayed.

    Password Prompt dialog box
    Description of the illustration bpel_15.gif

  3. In the Domain Password field, enter your BPEL Process Manager password.

    The deployment process starts automatically after you enter the correct password.

  4. Observe the Messages log on the bottom of the window.

    The Messages log displays the deployment status. In this example, it shows a successful deployment message for the process.

    Messages log
    Description of the illustration bpel_28.gif

    If deployment was not successful, click the Compiler tab to view all error and warning messages generated during the deployment process.

Listen to Adapter Events in Oracle BPEL Console

JDeveloper deploys the developed process directly to Oracle BPEL Console, which enables youto run, monitor, and administer BPEL processes, as well as to listen to adapter events at runtime using Oracle BPEL Console.

To listen to adapter events:

  1. Start the Oracle BPEL Console by entering the following URL in a browser:

    http://host:port/BPELConsole
    
    
  2. Select a domain and provide a valid password.

    The Oracle BPEL Console Dashboard tab is displayed.

  3. Click the Instances tab.

    Upon receiving a runtime event, an instance of the event is displayed under the Instances tab.

    Instances tab
    Description of the illustration bpel_23.gif

  4. To see the event message, click the instance, and then click Audit.

    The event message is displayed.

    Event messages
    Description of the illustration bpel_29.gif

  5. Click More... to view the entire message, or View Raw XML to view the XML source.

See Chapter 5, "BPEL Process Manager Integration Examples" for more information.


See Also:

Oracle Application Server Adapter Concepts