| Oracle® Application Server Adapter for SAP User's Guide 10g Release 3 (10.1.3.1.0) Part Number E10044-01 |
|
|
View PDF |
| Oracle® Application Server Adapter for SAP User's Guide 10g Release 3 (10.1.3.1.0) Part Number E10044-01 |
|
|
View PDF |
OracleAS Adapter for MySAP ERP integrates seamlessly with Business Process Execution Language (BPEL) Process Manager to facilitate Web service integration. Oracle 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 Oracle BPEL Process Manager
Invoking Adapter Request-Response Service from Oracle BPEL Process Manager
Listening to Adapter Events Inside Oracle BPEL Process Manager
To integrate with Oracle BPEL Process Manager, OracleAS Adapter for MySAP ERP must be deployed in the same OC4J container as Oracle 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 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.
When using the adapter with Oracle BPEL Process Manager installed on OracleAS Middle Tier, your middle-tier BPEL PM home directory is OC4J_BPEL, located as follows:
OracleAS_home\j2ee\OC4J_BPEL
See Also:
Oracle Application Server Adapter Concepts
Oracle BPEL Process Manager Developer's Guide
During installation, OracleAS Adapter for MySAP ERP 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 Oracle BPEL Process Manager.
See Also:
Oracle Application Server Adapter ConceptsThe following tools are required to complete your adapter design-time configuration:
OracleAS Adapter Application Explorer (Application Explorer)
Oracle JDeveloper BPEL Designer (JDeveloper) or Eclipse
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 WSDL (J2CA Configurations Only)" for more information.
The purpose of an XML namespace is to allow the deployment of XML vocabularies (where element and attribute names are defined) in a global environment and to reduce the risk of name collisions in a given document when vocabularies are combined. Qualified namespaces are used for stricter schema validation. In documents conforming to this specification, element and attribute names appear as qualified names. Syntactically, they are either prefixed names or unprefixed names. An attribute-based declaration syntax is provided to bind prefixes to namespace names and to bind a default namespace that applies to unprefixed element names. These declarations are scoped by the elements on which they appear so that different bindings may apply in different parts of a document. Processors conforming to this specification must recognize and act on these declarations and prefixes.
In the 10.1.3.1.0 SOA release, the recommendations for BPEL integrations is to perform stricter name space validations. As a result, Application Explorer generates Web services for the backend with the namespace marked as ÒQualifiedÓ. This means that during testing or usage phases of this service by BPEL, the request XML document that is used should adhere to the schema and WSDL document. Once again, it is important to remember that the namespaces are qualified. To further understand this point, the difference is illustrated with the following example:
Input XML for BPEL based on unqualified namespaces:
<?xml version="1.0" encoding="UTF-8"?><CompanyCode.GetDetail><COMPANYCODEID>1000</COMPANYCODEID></CompanyCode.GetDetail>
Input XML for BPEL based on qualified namespaces:
<?xml version="1.0" encoding="UTF-8"?><bapi:CompanyCode.GetDetail xmlns:bapi="urn:sap-com:document:sap:business" CompanyCodeId="1000"></bapi:CompanyCode.GetDetail>
Note: If you are passing an unqualified input against a WSDL document that is expecting qualified namespaces, BPEL will throw the exception as ÒUnable to process input xml...."
An outbound BPEL process consists of PartnerLink, Invoke, and Assign process activities. You must first create a new Application Server connection, Integration Server connection, and a synchronous BPEL process template.
Create a New Application Server Connection
To create a new Application Server connection:
Display the connections by clicking the Connections Navigator tab at the top of the upper left pane in JDeveloper.
Right-click Application Server and select New Application Server Connection.
The Create Application Server Connection - Welcome dialog box is displayed.
Click Next.
The Create Application Server Connection - Step 1 of 4: Type dialog box is displayed.
Specify a unique name and select a connection type for your Application Server connection and click Next.
The Create Application Server Connection - Step 2 of 4: Authentication dialog box is displayed.
Specify a valid user name and password for the Application Server you wish to connect to.
Select Deploy Password.
Click Next.
The Create Application Server Connection - Step 3 of 4: Connection dialog box is displayed.
Select the Single Instance connection option.
Enter localhost as the host name and 6003 for the OPMN port.
Enter home as the OC4J instance name
Click Next.
The Create Application Server Connection - Step 4 of 4: Test dialog box is displayed
Click Test Connection.
When the test is complete and the connection is successful, a Success! message appears in the status area.
Click Finish.
Your newly created Application Server connection is displayed in the Connections Navigator tab under the Application Server node.
Create a New Integration Server Connection
To create a new Integration Server connection:
Display the connections by clicking the Connections Navigator tab at the top of the upper left pane in JDeveloper.
Right-click Integration Server and select New Integration Server Connection.
The Create Integration Server Connection - Welcome dialog box is displayed.
Click Next.
The Create Integration Server Connection - Step 1 of 3: Name dialog box is displayed.
Specify a unique name and click Next.
The Create Integration Server Connection - Step 2 of 3: Connection dialog box is displayed.
Select an Application Server connection, which is already created.
Enter localhost as the host name and 8888 for the port number.
Select Add host name to the list of proxy exceptions and click Next.
The Create Integration Server Connection - Step 3 of 3: Test Connection dialog box is displayed.
Click Test Connection.
When the test is complete and the connection is successful, a Success! message appears in the status area.
Click Finish.
Your newly created Integration Server connection is displayed in the Connections Navigator tab under the Integration Server node.
Create a New BPEL Project for Outbound Interaction (Synchronous Process)
To create a new BPEL project for a synchronous process:
At the top of the upper left pane, click the Applications Navigator tab.
Right-click the Applications node and select New Application.
The Create Application dialog box is displayed.
Enter a unique name for your application and click OK.
The Create Project dialog box is displayed.
Enter a unique name for your project and click OK.
Your new application is displayed in the Applications Navigator tab under the Applications node.
Right-click the application node you created and select New Project.
The New Gallery window is displayed.
From the Items list, select BPEL Process Project and click OK.
The BPEL Project Creation Wizard - Project Settings dialog box is displayed.
Perform the following steps:
Specify a name for the BPEL process project.
The Namespace field is updated automatically.
From the Template list, select Synchronous BPEL Process.
Click Next.
The BPEL Project Creation Wizard - Input/Output Elements dialog box is displayed.
Review the input/output schema elements that are created by the BPEL Project Creation Wizard and click Finish.
Create an Outbound PartnerLink Activity
When designing a BPEL process, a PartnerLink activity must be created to invoke the mySAP ERP 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:
From the Services pane on the right, drag and drop a PartnerLink to the visual editor.
The Create Partner Link dialog box is displayed.
Click the Service Explorer icon (second icon from the left preceding the WSDL File field).
The Service Explorer dialog box is displayed.
Expand your new connection under Adapter Services, followed by adapters, and then applications.
The WSDL tree displayed in the Service Explorer 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.
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.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.
Perform the following steps:
Leave the My Role field unspecified. The role of the PartnerLink is null, as it will be synchronously invoked from the BPEL process.
From the Partner Role list, select the default value GetDetailRole. This is the role of the BPEL process.
Click OK.
The new PartnerLink appears in the visual editor.
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:
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).
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.
In the Name field, provide a meaningful name for the Invoke activity.
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.
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.
Click Apply.
The Edit Invoke window should no longer display any warnings or errors.
Click OK.
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 mySAP ERP process to the mySAP ERP PartnerLink input.
To create an Assign activity:
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).
Double-click the Assign activity icon.
The Assign dialog box is displayed.
Note:
Ignore any invalid settings and error warnings.In the Copy Operation tab, click Create and select Copy Operation.
The Create Copy Operation dialog box is displayed.
In the From pane, expand Variables, then inputVariable, and then highlight payload.
In the To pane, expand Variables, then GetCompanyDetail_BAPI_COMPANYCODE_GETDETAIL_InputVariable, and then highlight input_GetDetail.
Your Create Copy Operation dialog box should look as follows:
To close the Create Copy Operation dialog box and the Assign dialog box, click OK.
Create a Second Assign Activity
This Assign activity maps the output variable of the mySAP ERP process to the mySAP ERP PartnerLink output.
To create a second Assign activity:
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).
Double-click the Assign activity icon.
The Assign settings dialog box is displayed.
In the Copy Operation tab, click Create and select Copy Operation.
The Create Copy Operation dialog box is displayed. Perform the following steps:
In the From pane, expand Variables, then GetCompanyDetail_BAPI_COMPANYCODE_GETDETAIL_OutputVariable, and then highlight output_GetDetail.
In the To pane, expand Variables, then outputVariable, and then highlight payload.
Your Create Copy Operation dialog box should look as follows:
To close the Create Copy Operation dialog box and the Assign dialog box, click OK.
Select Save from the File menu.
The following image shows the diagram view of your completed BPEL process.
See "Invoking Adapter Request-Response Service from Oracle 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
Testing Outbound BPEL and ESB Processes
The BPEL console allows you to test deployed BPEL processes. Once a process is deployed, you can manage, monitor, and run an end-to-end scenario using the Initiate tab in the console. The OracleAS Adapter for mySAP ERP is certified for testing using the XML Payload option and the option of running using Through Java Delivery API. It is recommended that developers use this method for testing the OracleAS Adapter for mySAP ERP.
When testing an outbound BPEL process from the BPEL console or an outbound ESB process from the Enterprise Manager (EM) console, do not use the XML envelopes that are generated by these consoles. Instead, remove them and use the XML payloads that are generated from the schemas, which conform to the WSDLs for namespace qualifications.
The ESB data flows can be tested using the EM console. When creating an ESB data flow and interactions, the Web services are created and registered with the Oracle Application Server. For more information on creating an ESB outbound process, see Chapter 6, "ESB Integration Examples".
An inbound BPEL process consists of a PartnerLink and a Receive process activity. You must first create a channel and a new Oracle BPEL Process Manager Server connection. See Chapter 5, "BPEL Process Manager Integration Examples" for instructions on how to perform these procedures.
Note:
You must create a separate channel for every event and select that channel when you generate WSDL for inbound interaction using Application Explorer. Do not start the channel in Application Explorer, as Oracle BPEL Process Manager manages endpoint activation independently. See "mySAP ERP 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:
Click the Applications Navigator tab and select an application for your project.
Right-click the application and select New Project.
The New Gallery window is displayed.
From the Items list, select BPEL Process Project and click OK.
The BPEL Project Creation Wizard - Project Settings dialog box is displayed.
Perform the following steps:
Specify a name for the BPEL process project.
The Namespace field is updated automatically.
From the Template list, select Empty BPEL Process.
Click Next.
The BPEL Project Creation Wizard - Input/Output Elements dialog box is displayed.
Review the input/output schema elements that are created by the BPEL Project Creation Wizard and click Finish.
Create an Inbound PartnerLink Activity
When designing a BPEL process, a PartnerLink activity must be created to invoke the mySAP ERP 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:
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.
Click the Service Explorer icon (second icon from the left preceding the WSDL File field).
The Service Explorer dialog box is displayed.
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.
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.Select BAPI_COMPANYCODE_GETDETAIL_receive.wsdl and click OK.
The Create Partner Link dialog box is displayed.
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:
From the My Role list, select the default value GetDetailRole.
Leave the Partner Role field unspecified.
Click Apply, and then OK.
The new SAP_2 PartnerLink appears in the visual editor.
Select Save from the File menu.
Create an Inbound Receive Activity
To create an inbound Receive Activity:
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.
Double-click the Receive activity.
The Receive dialog box is displayed.
Perform the following steps:
From the Partner Link menu, select the PartnerLink you created in the previous step.
The Operation field is automatically populated.
Click the first icon to the right of the Variable field, then click OK in the Create Variable dialog box that is displayed.
Verify that the Create Instance check box is selected.
Click Apply.
The Receive dialog box should no longer display any warnings or errors.
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 Oracle 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
The OracleAS Adapter for MySAP ERP 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:
Right-click your process flow in the Applications Navigator tab.
Select Deploy, then Your BPEL PM Server connection, and then Deploy to default domain.
The deployment process starts automatically after you enter the correct password.
Observe the Messages log at the bottom of the window.
The Messages log displays the deployment status. In this example, it shows a successful deployment message for the process.
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:
Start the Oracle BPEL Console by entering the following URL in a browser:
http://host:port/BPELConsole
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.
This tab provides a more detailed view of each deployed process.
Click the mySAP ERP process link, mySAP_outbound_companycode_getdetail (v. 1.0).
The Manage window provides options for managing this BPEL process. Do not change any of the following default settings.
Click the Initiate tab.
The Initiate tab enables you to test your BPEL process.
Perform the following steps:
Select XML Source.
Enter the following code in the text area provided for XML input:
<?xml version="1.0" encoding="UTF-8"?> <CompanyCode.GetDetail CompanyCodeId="1000"/>
Click Post XML Message.
The response received from the mySAP ERP system is displayed in the Initiate window.
See Also:
Oracle Application Server Adapter ConceptsThe OracleAS Adapter for MySAP ERP 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:
Right-click your process flow in the Applications pane.
Select Deploy, then Your BPEL PM Server connection, and then Deploy to default domain.
The deployment process starts automatically after you enter the correct password.
Observe the Messages log at the bottom of the window.
The Messages log displays the deployment status. In this example, it shows a successful deployment message for the process.
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:
Start the Oracle BPEL Console by entering the following URL in a browser:
http://host:port/BPELConsole
Select a domain and provide a valid password.
The Oracle BPEL Console Dashboard tab is displayed.
Click the Instances tab.
Upon receiving a runtime event, an instance of the event is displayed under the Instances tab.
To see the event message, click the instance, and then click Audit.
The event message is displayed.
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