21 Using Oracle Orchestration Systems

This chapter contains the following topics:

Section 21.1, "Understanding Oracle Orchestration Systems"
Section 21.2, "Configuring Orchestration Cross References"
Section 21.3, "Using Password Indirection (Optional)"
Section 21.4, "Setting Up the Cross-Reference Java Binding Service"

21.1 Understanding Oracle Orchestration Systems

JD Edwards EnterpriseOne can provide and consume web services using Oracle's BPEL-PM and ESB orchestration systems. JD Edwards EnterpriseOne can also send event notifications to third-party systems using the BPEL-PM and ESB orchestration systems.

See Oracle BPEL Process Manager Developer's Guide.

See Oracle ESB Developer's Guide.

See JD Edwards EnterpriseOne Tools Transaction Server Reference Guide on My Oracle Support.

See "JD Edwards EnterpriseOne Tools Business Services Development Overview" in the JD Edwards EnterpriseOne Tools Business Services Development Guide.

21.1.1 BPEL-PM

You can use Oracle's BPEL-PM to create a web service. BPEL-PM provides high-performance, reliable execution of service-oriented business processes that are defined with the BPEL standards. BPEL-PM is primarily used to create integrated business processes. It contains native support of BPEL, SML, XSLT, XPATH, JMS, JCA, and web services.

BPEL is an XML-based language for enabling task-sharing across multiple enterprises using a combination of web services. BPEL is based on XML schema, simple object access protocol (SOAP), and web services description language (WSDL). BPEL provides enterprises with an industry standard for business process orchestration and execution. Using BPEL, you design a business process that integrates a series of discrete services into an end-to-end process flow.

You can consume JD Edwards EnterpriseOne web services in a BPEL business process using BPEL-PM. You can also use the JD Edwards EnterpriseOne transaction server to publish and deliver event notifications to BPEL-PM. In addition, you can consume a BPEL-PM web service in JD Edwards EnterpriseOne using the business services server. You use the JDeveloper BPEL Designer, a tool that is part of the Oracle BPEL-PM product, to build, deploy, and test a BPEL PM process that consumes JD Edwards EnterpriseOne web services.

21.1.2 ESB

Oracle Enterprise Service Bus (ESB) is a component of the Oracle Service-Oriented Architecture (SOA) suite delivering loosely coupled data and enterprise application integration. Oracle ESB features a multiprotocol message bus with centralized monitoring and management of distributed services where all services are exposed as standard web services. Oracle ESB contains message flows that use adapters, transformations, and routing rules to distribute data throughout and beyond the enterprise.

You can consume JD Edwards EnterpriseOne web services in an ESB flow. You can also use the JD Edwards EnterpriseOne transaction server to publish and deliver event notifications to ESB. In addition, you can consume an ESB web service in JD Edwards EnterpriseOne using the business services server. You use the JDeveloper ESB Designer to build, deploy, and test a BPEL PM process that consumes JD Edwards EnterpriseOne web services.

21.1.3 Orchestration

Orchestration enables you to map and transform data between two disparate systems. This allows data in a JD Edwards EnterpriseOne format to be transformed to the data format of another application or system and the data format of another application or system to be transformed to the data format of JD Edwards EnterpriseOne. Orchestration is a key component that enables you to plug and play different software modules to complete your integration solution. Much of the orchestration system is based on SOA.

Oracle provides applications that help you create cross-reference utilities. The cross-reference utilities are used within the orchestration system.

Note:

If the orchestration system that you use provides features to do dynamic cross-referencing, static cross-referencing, or both, you should use them.

21.2 Configuring Orchestration Cross References

This section provides an overview of the orchestration cross-reference configuration and discusses how to:

Register cross-reference XPATH functions in JDeveloper.
Configure access to orchestration cross-reference APIs.
Create a data source in OC4J.

21.2.1 Understanding the Orchestration Cross-Reference Configuration

Orchestration cross-references are key/value data pairs that are used for referencing corresponding values between disparate systems. The orchestration system uses two types of cross-references: code and key. Code cross-references pertain to static references; for example, in JD Edwards EnterpriseOne, the country code US might be equivalent to USA in another software system. Key cross-references are dynamic cross-references that are added during orchestration runtime, such as sales orders across systems. For example, the sales order number 9876 in JD Edwards EnterpriseOne is equivalent to sales order number 1234 in a third-party application.

Cross-reference utilities provide a way to read, add, modify, and delete cross-reference entries at runtime. Before you can use the Orchestration Cross Reference Admin tool to add cross-references, you must perform preliminary tasks to configure the orchestration system. This chapter identifies the tasks that a system administrator and developer must perform to configure the system for cross-reference orchestration. The system administrator performs certain tasks (for example, cross-reference API access, OC4J data source creation, cross-reference Java binding service setup) to enable developers to add, modify, and delete cross-references. The developer registers cross-reference XPATH functions in JDeveloper. These configuration tasks enable interaction between JD Edwards EnterpriseOne and third-party applications in the orchestration system.

21.2.1.1 How the Orchestration System Uses Cross-References

This diagram shows the dynamic cross-referencing in the orchestration process. In this scenario, a third-party application calls an orchestration system as part of order processing and passes the order number in the payload. The orchestration system calls a JD Edwards EnterpriseOne web service to create an order and to get an EnterpriseOne order number. Upon successful response from JD Edwards EnterpriseOne, the orchestration system creates and stores mapping information for the order numbers from the third-party system and JD Edwards EnterpriseOne.

Figure 21-1 Creating a cross-reference key

Description of "Figure 21-1 Creating a cross-reference key"

This diagram shows the orchestration system dynamically updating an existing cross-reference. In this scenario, a third-party application calls the orchestration system as part of updating or deleting an existing order and sends the order number in the payload. The orchestration system gets the JD Edwards EnterpriseOne order number from the cross-reference table and calls a JD Edwards EnterpriseOne web service to update or delete the order.

Figure 21-2 Getting a cross-reference key

Description of "Figure 21-2 Getting a cross-reference key"

21.2.1.2 Common Notations and Variables in This Document

You should be familiar with these notations and variables before performing the tasks in this chapter:

Notation / Variable	Definition
ORACLE_HOME	Orchestration tool install directory.
OC4J_HOME	Orchestration tool OC4J directory. Typical values include: BPEL – ORACLE_HOME/bpel/system/appserver/ocrj/j2ee/home ESB – ORACLE_HOME/j2ee/home
JDEVELOPER_HOME	JDeveloper home directory. This must be JDeveloper with the BPEL/ESB extensions MTR.

21.2.2 Registering Cross-Reference Read XPATH Functions in JDeveloper

Cross-reference Read XPATH functions provide common syntax and semantics for addressing parts of an XML document. To access Cross-Reference Read XPATH functions, you must register the XPATH functions in JDeveloper. The XPATH functions reside in the CrossReferenceRead.xml file. You must register the XPATH functions for both JDeveloper and runtime.

Note:

This is a one-time setup that a developer performs.

To register the XPATH functions:

Copy the CrossRefenceRead.xml file and paste it in the JDEVELOPER_HOME directory:
Open JDeveloper.

//delivery/production/Orchestration/WSDL_Schema

In Microsoft Windows, this file is located in:

//system/classes/Orchestration/WSDL_Schema
On the Preferences form, navigate to Tools, Preferences, XSL Maps.
In the User Defined Extension Functions Config File field, enter the path to the CrossReferenceRead.xml file, and then click OK.
Restart JDeveloper.

21.2.3 Configuring Access to Orchestration Cross-Reference APIs

For the orchestration system to access the cross-reference APIs, you must register the XPATH function in JDeveloper for runtime.

Note:

The orchestration cross-reference APIs are for use with orchestration cross-references only; they are not used for business service properties.

This is a one-time setup that an administrator performs.

This example XML document is referred to in Step 2 of the task:

Figure 21-3 XML document for registering XPATH functions in JDeveloper

Description of "Figure 21-3 XML document for registering XPATH functions in JDeveloper"

To register the XPATH functions in JDeveloper for runtime.

Copy FS_SCCR_JAR from the following location and paste it in the OC4J_HOME/applib directory:

//delivery/production/orchestration

In Microsoft Windows, this file is located in:

//system/classes/orchestration
Open OC4J_HOME/config/application.xml in a text editor.
If the following line is not already in the XML document, add it between the start and end tags of the orion-application:

<library path=”../../home/applib” />
Restart OC4J.

21.2.4 Creating a Data Source in OC4J

Cross-reference access APIs connect to the JD Edwards EnterpriseOne database using the JNDI data source defined in OC4J. A system administrator must define the data source based on the database platform being used. Before you can define the data source, you must create the data source in OC4J.

To create a data source in OC4J:

Open OC4J_HOME/config/application.xml in a text editor.
Add the following line between the start and end tags of the orion-application if it is not already there:

<library path=”../../home/applib” />
Place the required database driver in OC4J_HOME/applib directory.
Open OC4J_HOME/config/data-sources.xml in text editor.
Add native data source definition for the database platforms as described in this section.
Restart OC4J.

After you create the data source in OC4J, you can define it for any one of these database platforms:

Oracle
UDB/DB2 for IBM i
DB2 for IBM i
SQL Server

21.2.4.1 Defining an Oracle Data Source in OC4J

Use the Oracle JDBC driver provided with OC4J. If you prefer a different driver, place the driver in the applib directory.

<native-data-source user="user" password="password" 
   url="jdbc:oracle:thin:@//dbserver:dbport/SID" 
   data-source-class="oracle.jdbc.pool.OracleDataSource" 
   jndi-name="jdbc/abcoraDS" name="abcoraDS"/>

21.2.4.2 Defining a UDB/DB2 for IBM i Data Source in OC4J

Use UDB universal driver db2java.zip. This is a type 2 jdbc driver. The UDB client must be present and the database must be cataloged for the connection to work.

<native-data-source user="user" password="password"
   url="jdbc:db2:dbname" 
   data-source-class="COM.ibm.db2.jdbc.DB2DataSource" 
   jndi-name="jdbc/udbDS" name="udbDS">
       <property name="databaseName" value="dbname"/>
       <property name="serverName" value="dbservername"/>
</native-data-source>

21.2.4.3 Defining a DB2 for IBM i Data Source in OC4J

Use IBM i access driver version 7.0 or greater

The jt400.jar must be in the applib directory.

<native-data-source user="user" password="password"
   url="jdbc:as400://as400machine" 
   data-source-class="com.ibm.as400.access.AS400JDBCDataSource" 
   jndi-name="jdbc/asDS" name="asDS">
      <property name="databaseName" value="dbname"/>
      <property name="serverName" value="servername"/>
      <property name="libraries" value="database library to access"/>
</native-data-source>

21.2.4.4 Defining a SQL Server Data Source in OC4J

This data source definition is for use with the Microsoft JDBC driver. These files must be in the applib directory:

msbase.jar
msutil.jar
mssqlserver.jar

<native-data-source user="username" password="password"
   url="jdbc:microsoft:sqlserver://databaseserver:TCP/IP port;databaseName=DBName" 
   data-source-class="com.microsoft.jdbcx.sqlserver.SQLServerDataSource" 
   jndi-name="jdbc/abcDS" name="abcDS">
        <property name="databaseName" value="DBName"/>
        <property name="serverName" value="servername\databaseinstancename"/>
</native-data-source>

21.3 Using Password Indirection (Optional)

This section provides an overview of password indirection and provides the tasks for setting up password indirection in OC4J, which include how to:

Edit the default application.xml to use system-jazn data.
Add a JAZN user.
Add password indirection in the data source.

Note:

Oracle recommends setting up password indirection for preventing security vulnerabilities. However, it is not required.

21.3.1 Understanding Password Indirection

The data-sources.xml file requires passwords for authentication. Embedding these passwords without some kind of obfuscation poses a security risk. To avoid this problem, OC4J supports password indirection.

An indirect password is made up of a special indirection symbol (->) and a user name (or user name and realm). When OC4J encounters an indirect password, it retrieves the password associated with the specified user from the security store provided by a user manager.

21.3.2 Editing the Default Application.xml to Use System-jazn Data

You must edit the default application.xml file to use system-jazn data.

To edit the default application.xml to use system-jazn data:

Open OC4J_HOME/config/application.xml in a text editor.
Find this line, <jazn provider="XML"/>, and replace it with this line:

<jazn provider= ="XML" location="system-jazn-data.xml" default-realm="jazn.com"/>

21.3.3 Adding a JAZN User

To add a JAZN user:

Enter the following URL in a web browser to open OC4J EM:

http://oc4jserver:port/em
Navigate to Administration, Security, Security providers.
On the Security Providers page, click the Instance Level Security button and then select the Realms tab.
On the Instance Level Security page, click the link in the Users column for the default realm jazn.com.
On the Users page, click the Create button and then complete these fields on the Add User page:
- Username
- Password
- Confirm Password

21.3.4 Adding Password Indirection in the Data Source

To add password indirection in the data source:

Open the data-sources.xml file in a text editor.
Find the data source definition to edit.

In the password field for the data-source, enter the indirection symbol (->) followed by the JAZN user that you added, for example:

->jazn.com/xrefuser

The data source definition should look like this when complete:

<native-data-source user="xrefuser" password="->jazn.com/xrefuser"
     url="jdbc:microsoft:sqlserver://localhost:1050;databaseName=JDELocal" 
     data-source-class="com.microsoft.jdbcx.sqlserver.SQLServerDataSource" 
     jndi-name="jdbc/eoneDS" name="eoneDS">
        <property name="databaseName" value="JDELocal"/>
        <property name="serverName" value="localhost\JDELocal"/>
  </native-data-source>

Save the file and restart OC4J.

21.4 Setting Up the Cross-Reference Java Binding Service

The cross-reference Java binding service provides access to cross-reference utilities from the orchestration system. You can register the Java binding service using either of these methods:

Registering in the shared library (BPEL-PM or ESB)
Putting Java binding classes in BPEL-PM classpath (BPEL-PM only)

This service is delivered as two files: CrossReferenceJavaBinding.wsdl and CrossReferenceAccess.xsd. You can locate the files in this directory:

//delivery/production/Orchestration/WSDL_Schema

In Microsoft Windows client, the files are located in this directory:

/system/classes/Orchestration/WSDL_Schema

21.4.1 Registering the Java Binding Service

To register the Java binding service in the BPEL-PM or ESB shared library:

Copy the FIS_SCCR_JAR.jar to the following directory:
- For BPEL-PM:
  
  ORACLE_HOME/bpel/system/classes
- For ESB:
  
  ORACLE_HOME/integration/esb/lib
Copy the CrossReferenceJavaBinding.wsdl and CrossReferenceAccess.xsd files to the ORACLE_HOME directory.
Open the server.xml file in a text editor. You can locate this file in OC4J_HOME/config folder of BPEL/ESB.
In the server.xml file, locate shared-library name="oracle.bpel.common".
Add FIS_SCCR_JAR.jar in this shared library to the following location:
- For BPEL-PM:
  
  <code-source path="D:\OraBPEL_1\bpel/system/classes/FIS_SCCR_JAR.jar"/>
- For ESB:
  
  <code-source path="../../../integration/esb/lib/FIS_SCCR_JAR.jar"/>

21.4.2 Placing Java Binding Classes in the Classpath

To place the Java binding classes in the classpath for either BPEL-PM or ESB.

Unzip the contents of the FIS_SCCR_JAR.jar file to this directory:

ORACLE_HOME/bpel/system/classes
Copy the provided CrossReferenceJavaBinding.wsdl and CrossReferenceAccess.xsd to the ORACLE_HOME directory.

21.4.3 Using Cross-Reference Read Services from XSL Mapper

The JD Edwards EnterpriseOne read services for cross-references are available from XSL Mapper in both BPEL and ESB. The steps in this section describe how to use these read services.

To use the cross reference read service from XSL Mapper:

Invoke XSL Mapper.

In BPEL-PM, add the Transform activity to the BPEL-PM flow and provide the input and output document.

In ESB, use the transform function in routing rules for any ESB service.
In the XSL Mapper, from the Component Palette drop-down menu, select the User Defined Extension Functions component.

The system should display two functions: getCrossReferenceE1Val and getCrossReferenceThirdPartyVal.
Select the required function and drag it to the mapping area.
Define inputs for the function using any one or a combination of these methods:
- Double-click the function and provide string inputs using double or single quotes.
- Double-click the function and provide the XPATH expression as input.
- Link elements from input schema to function inputs.
Map the output to the required element in output schema.
Save the XSL Map.

21.4.4 Using JD Edwards EnterpriseOne Cross-Reference Services

You can use the JD Edwards EnterpriseOne Cross Reference Service to add, modify, and delete cross-reference information.

21.4.4.1 BPEL-PM

You can use the JD Edwards EnterpriseOne Cross Reference Service to add, modify, and delete cross-reference information in Oracle's BPEL-PM orchestration system. The BPEL project must be created in JDeveloper BPEL-PM designer.

To create a partner link in JDeveloper BPEL-PM designer using the service WSDL file.

In the JDeveloper BPEL-PM designer, select the PartnerLink activity and drag it to the BPEL-PM process page.
On the Create Partner Link dialog box, enter the name of the WSDL file for the Java binding service:

ORACLE_HOME/CrossReferenceJavaBinding.wsdl
Click Yes when asked to make a local copy of the file.
Click Yes when asked to create a new Partner Link type.
From the Partner Role drop-down menu, select the default generated role.
Click OK.

The system creates the Partner Link. The Partner Link can now be used to invoke cross-reference services.

21.4.4.2 ESB

You can use the JD Edwards EnterpriseOne Cross Reference Service to add, modify, and delete cross-reference information in ESB. You use ESB JDeveloper.

To invoke cross-reference services from ESB:

Import web service schema EoneXrefAccessWSSchema.xsd in the project using the File, Import utility.

The xsd file should have been copied to your ORACLE_HOME directory during the web service deployment step.
Right-click the ESB system design page and select Create ESB Service, SOAP Service.
Name the service EOneXrefAccessWS.
Select ESB System/group if you are not using the default.
For the Java binding service, enter the WSDL file as provided in the example:

ORACLE_HOME/CrossReferenceJavaBinding.wsdl
Click OK.

The system creates the SOAP service and displays all available operations.
To create the routing service for the required operation, right-click the system page and select Create ESB Service, Routing Service.
Enter an appropriate name for the service, such as EOneXrefAddRec_RS.
Select ESB System/group if you are not using the default.
Click the Generate WSDL from the Schemas option.
On the Request tab, for Schema Location, click Browse.
Select the operation input element from EoneXrefAccessWSSchema.xsd under Project Schema Files and click OK.
On the Reply tab, repeat the preceding steps and select the response element for the chosen operation, and then click OK.
Double-click Routing service, expand the Routing Rules tab, and then click the Add button.
Select the web service operation as the target service.
Add filter rules and transformations as needed.
Save the project.

This routing service can be called from other ESB services for executing cross-reference operations.