8 Working with JD Edwards EnterpriseOne as a Web Service Consumer

This chapter contains the following topics:

• Section 8.1, "Understanding JD Edwards EnterpriseOne as a Web Service Consumer"

• Section 8.2, "Setting Up OCM for Business Functions Calling Business Services"

• Section 8.3, "Developing a Business Service for Consuming an External Web Service"

• Section 8.4, "Testing a Business Service That Consumes an External Web Service"

8.1 Understanding JD Edwards EnterpriseOne as a Web Service Consumer

JD Edwards EnterpriseOne can call and process external web services. Being a native consumer of web services enables JD Edwards EnterpriseOne to integrate with other Oracle products and third-party systems and products, such as order promising. To enable JD Edwards EnterpriseOne as a web services consumer, you create a business service that uses a web service proxy to call an external web service. A method in that business service can be called by a JD Edwards EnterpriseOne business function. The business service resides on the business services server and is written in the Java programming language. The business service contains a web service proxy that you generate using JDeveloper. The business function resides in your enterprise server and is written in the C programming language. The business function calls the business service method.

Note:

Do not use JDK 1.6-specific APIs in any of the published business services code if you want to be able to build business services packages for OAS, WAS, and WebLogic.

8.1.1 Communicating Between JD Edwards EnterpriseOne Servers

The business function, which resides in your enterprise server, uses an API to call the business service method, which resides on the business services server. JDENet is the communication mechanism between the servers. An Object Configuration Manager (OCM) mapping tells the enterprise server the business services server name and port for sending the JDENet messages.

8.1.1.1 Business Function APIs for Calling a Business Service

These APIs are available for a business function to call a business service method:

• jdeCallBusinessService

• jdeCallBusinessServiceNoResponse

• jdeFreeBSSVPayloadReturn

• jdeGetBusinessServiceErrorText

Two APIs are available for calling a business service method from a business function:

• jdeCallBusinessService

  This API makes a synchronous call to the business services server passing in an XML document that represents the value object for the called business service method. The call waits until the business service method finishes before processing.

• jdeCallBusinessServiceNoResponse

  This API makes an asynchronous call to the business services server passing in an XML document that represents the value object for the called business service method. The API returns immediately after sending the message without waiting for a response.

For both of these APIs, the caller must allocate the bssvPayloadInput structure. In addition, the caller must free the bssvPayloadReturn structure with the provided API.

This example code provides a typical C business function call to a business service method:

* jdeCallBusinessService (lpBhvrCom, 
*               lpVoid, 
*               _J("oracle.e1.sbf.JXXXXX") 
*               _J("bssv_method_name_to_call")
*               TRUE, 
*               bssvPayload, 
*               &bssvPayloadReturn);
* 
* /* caller must free the space allocated for the return payload when 
*    finished with it */
* jdeFreeBSSVPayloadReturn (&bssvPayloadReturn); 
*

Both APIs take the same set of parameters, which is shown in this example code:

* lpBhvrCom - BSFN structure pointer.
* lpVoidInfo - holds error info returned from BSFN.
* bssvName - fully qualified name of business service to be called
* bssvMethod - method within business service to be called
* autocommitTransaction - type of transaction the business service should use 
*                         on the business services server. 
*                         True if auto commit - False for manual commit.
* bssvPayloadInput - string representation of an XML document that represents
*                    the value object for the business service. Populated 
*                    with input values to pass to the business service.
* bssvPayloadReturn - string representation of XML document representing the 
*                     value object returned from the business service call 
*                     populated with both return values and original input 
*                     values. The caller must free the space allocated for 
*                     the return payload by calling the 
*                     jdeFreeBSSVPayloadReturn API.

Both APIs have the same return values, which are shown in this example code:

* CallBSSVNoError                     100L 
* CallBSSVServiceDoesNotExist         101L 
* CallBSSVMethodDoesNotExist          102L 
* CallBSSVInvalidMethodSignature      103L 
* CallBSSVNoDefaultConstructor        104L 
* CallBSSVErrorUnMarshal              105L 
* CallBSSVErrorMarshal                106L 
* CallBSSVConnectionException         107L 
* CallBSSVInvalidPacketNum            108L 
* CallBSSVInvaldUserName              109L 
* CallBSSVInvalidEnv                  110L 
* CallBSSVInvalidRole                 111L 
* CallBSSVInvalidToken                112L 
* CallBSSVAuthenticationFailure       113L 
* CallBSSVNoErrorWithMessages         114L 
* CallBSSVInvalidParamError           201L 
* CallBSSVSystemConfigurationError    202L 
* CallBSSVSystemNetworkFailedError    203L 
* CallBSSVSystemInternalServerError   204L

See Also:

• JD Edwards EnterpriseOne Tools API Reference Guide on the My Oracle Support Web site.

8.1.2 Xerces APIs

You can use any one or more Xerces APIs in combination with other XML generation and editing APIs to generate the XML payload for calls to a business service. You can use any of these Xerces APIs, which have been added to the Xerces wrapper:

• Xerces APIs for working with MathNumeric data types:

  • XRCS_createElementFromMathNumeric

  • XRCS_setMathNumericElementValue

  • XRCS_getMathNumericFromElement

• Xerces APIs for working with JDEDATE data types:

  • XRCS_createElementFromJDEDate

  • XRCS_setJDEDateElementValue

  • XRCS_getJDEDateFromElement

• Xerces APIs for working with JDEUTIME data types:

  • XRCS_createElementFromJDEUTIME

  • XRCS_setJDEUTIMEElementValue

  • XRCS_getJDEUTIMEFromElement

• Xerces APIs for parsing/serialization ignoring encoding tags:

  • XRCS_serializeDocumentToXMLStringNoEncoding

  • XRCS_parseXMLStringRemoveEncoding

See Also:

• JD Edwards EnterpriseOne Tools API Reference Guide on the My Oracle Support Web site.

8.2 Setting Up OCM for Business Functions Calling Business Services

This section provides an overview of setting up OCM for business functions calling business services and discusses how to:

• Configure OCM for business functions calling business services.

• Ping the business services server.

8.2.1 Understanding OCM Setup for Business Functions Calling Business Services

Typically, a system administrator configures OCM so that your enterprise server can find the business services server. After OCM is configured with the business services server information, you can ping the business services server from OCM to ensure that the business services server is running and listening for messages.

See Also:

• "Object Configuration Manager" in the JD Edwards EnterpriseOne Tools Configurable Network Computing Implementation Guide.

8.2.2 Forms Used to Set Up OCM for Business Functions Calling Business Services

Form Name	FormID	Navigation	Usage
Machine Search and Select	W986110D	Expand the System Administration Tools folder on the EnterpriseOne Life Cycle Tools / All My Roles menu, and then select Environment / Service Configuration from the Environment Management folder.	Select the appropriate machine name and data source combination.
Work with Service Configurations	W986110J	On Machine Search and Select, select the machine name and data source combination and then click Select.	Find and select an existing configuration for the business services server and server port, or access the Service Configuration Revisions form to add a new configuration record. Also ping the business services server to determine whether the business services server is available.
Service Configuration Revisions	W986110K	On Work with Service Configurations, click Add.	Add a new configuration in OCM with the location of the business services server.

8.2.3 Configuring OCM for Business Functions Calling Business Services

Access the Service Configuration Revisions form.

Figure 8-1 Service Configuration Revisions form

Description of "Figure 8-1 Service Configuration Revisions form"

Environment Name

A name that uniquely identifies the environment.

Service Name

A name that identifies the type of server. For example, BSSV identifies the business services server.

User/Role

A specific JD Edwards EnterpriseOne user name, role name, or *PUBLIC to whom the record applies.

Server

The name of the local host where the business services server is running.

Port

The port number of the business services server. This is the JDENet listening port.

8.2.4 Pinging the Business Services Server

Access the Work with Service Configurations form.

1. In the grid area, highlight the server.

2. From the Row menu, select Change Status to activate the configuration.

3. From the Row menu, select Ping Server.

   You receive a Ping message indicating whether the Ping test was successful or failed.

8.3 Developing a Business Service for Consuming an External Web Service

This section provides an overview of how to develop a business service for consuming an external web service and discusses how to:

• Identify an external web service.

• Create a business service object.

• Create a web service proxy prior to JDeveloper 11g.

• Create a web service proxy for a web service deployed in WebLogic Server using JDeveloper 11g with JAX-RPC.

• Create a value object class.

• Create a business service class.

• Generate a sample XML document.

8.3.1 Understanding How to Develop a Business Service for Consuming an External Web Service

You create a business service that consumes an external web service in the same way that you create a business service that provides a web service for public consumption. But instead of using a published business service as the web service, the business service is used to consume the web service. As part of the process, you create a web service proxy and an XML document. This business service is called by a business function. The following tasks provide a scenario for creating a JD Edwards EnterpriseOne business service that consumes an external web service.

8.3.2 Identifying an External Web Service

Before you create a business service to consume an external web service, you need to identify the external web service and its location. The external web service definition determines the data to be sent to the web service and the result that is received.

8.3.3 Creating a Business Service Object

Using Object Management Workbench (OMW), create the object that will contain the business service being developed. Start JDeveloper from OMW to work with this project.

8.3.4 Creating a Web Service Proxy Prior to JDeveloper 11g

A web service proxy is a collection of classes generated by JDeveloper and is used to call external web services. JDeveloper uses the target WSDL to create all necessary classes. A JD Edwards EnterpriseOne business service method uses the web service proxy to call the external web service. You use JDeveloper to create a web service proxy in the business service project that you created using OMW.

Note:

When you create a new business service proxy project in JDeveloper 10g to consume a web service running on the Oracle Application Server (OAS), JDeveloper includes the web service WSDL in the proxy project. When you check in the business service proxy project through OMW, the WSDL file must also be checked in as part of the project. If the WSDL file includes an XSD schema, the XSD schema file must be placed in the business service proxy folder and checked in as part of the business service project through OMW. This is required when you want to run the Migration Utility on a newly created OC4J-based business service proxy.

To be able to check in WSDL & XSD files along with the business service consumer projects through OMW, ensure that the UDC H95/CA includes records for WSDL & XSD files as BSSV artifacts that can be checked in.

When you create a new business service proxy project in JDeveloper 11g to consume a web service running on the WebLogic Application Server (WLS), JDeveloper 11g includes certain XML files in the proxy project. When you check in the business service proxy project through OMW, the XML files in the proxy project must also be checked in as part of the project.

To be able to check in XML files along with the business service consumer projects through OMW, ensure that the UDC H95/CA includes records for XML files as business services artifacts that can be checked in.

Also ensure that any new business service proxy project created in JDeveloper 11g to consume a web service running on WLS is checked in through OMW with the JDeveloper install path specified as the JDeveloper 11g install path.

After JDeveloper creates the web service proxy, you must rename the package folder, and then rebuild the code to ensure that no errors occurred.

To create a web service proxy:

1. Open JDeveloper from OMW.

2. Select the business service package for which you want to create a web service proxy, and then select New from the File menu.

3. On New Gallery, select All Technologies from the Filter By drop-down menu.

4. Expand the Business Tier category, and then select Web Services.

5. In the Items pane, select Web Service Proxy, and then click OK.

   The Create Web Service Proxy Wizard opens.

6. On the Welcome page, click Next.

7. On Web Service Description, enter a web service WSDL URL in the WSDL Document URL field, and then click Next.

   This is an example of a WSDL URL:

   http://denqwb3.mlab.jdedwards.com:7777/orabpel/default/BPELFlowToSendEmail/1.0/BPELFlowToSendEmail?wsdl

   Important:

   Be sure that you open the URL in your browser and copy the URL from the browser address to the WSDL Document URL field in JDeveloper.

8. On Available Services, select the name of the service that you want to call, and then click Next.

9. On Port Endpoints, click Next.

10. On Custom Mappings, click Next.

11. On Defined Handlers, click Next.

12. On Default Mapping Options, deselect the Map Headers to Parameters option, and then click Next.

13. On Support Files, click Next.

14. On Finish, click Finish.

JDeveloper generates a proxy and places it under the business services package that you selected. A portion of the proxy package name must be in upper case; however, JDeveloper named the proxy using lower case. You must rename the proxy package.

8.3.4.1 Renaming the Business Service Package

You must rename the package so that the name matches the case of the rest of the business service. After you rename the package, you should rebuild the code to ensure that no errors exist. To rename the business service package.

1. In the business service project on JDeveloper, select the business service package, and then click Replace in Files on the Search menu.

2. On the Replace in Files window, enter the name in lowercase (for example, jrh90i20).

3. Enter the name in uppercase (for example, JRH90I20).

4. In the Search Path pane, select the Active Project option.

5. Click OK.

   The uppercase name appears.

6. Save the renamed file by selecting Save All from the File menu.

You should rebuild the code to make sure no errors occurred.

8.3.5 Creating a Web Service Proxy for a Web Service Deployed in WebLogic Server Using JDeveloper11g with JAX-RPC Client

You can create a proxy that consumes a web service that is deployed in the WebLogic server. This section explains how to create the proxy in the development environment.

To create a web service proxy:

1. From OMW, open JDeveloper 11g.

2. Under the BSSV package (created for the proxy project), create a subfolder named Proxy.

   For example, Oracle uses the following package structure for reference implementations:

   oracle.e1.bssv.JRH90I33.proxy

3. Select the OMW project and then open the project properties.

4. Add the proxy path that corresponds to the package structure in the java source path.

   For example, the following structure might be added to the java source path:

   c:\e812\DV812\Java\source\oracle\e1\bssv\ JRH90I33\proxy

5. Select the BSSV package for which you want to create a proxy, and then click File, and then click New.

6. On New Gallery, select All Technologies from the drop-down menu.

7. Expand the Business Tier category, and then select Web Services.

8. In the Items pane, select Web Services Proxy, and then click OK.

   The Create Web Service Proxy wizard opens.

9. On the Welcome page, click Next.

10. If you receive a prompt to select a web service option, select JAX-RPC, and then click OK.

11. Enter the web service URL address.

12. On the Specify Default Mapping Option page, enter the package name or select the name using the Browse button.

    For example, to use the JRH90I33 reference implementation, select oracle.e1.bssv. JRH90I33.proxy.

13. Click Next.

14. Select the name of the service that you want to call, and then click Next.

15. Verify that the default options are selected on the remaining pages, and then click Finish.

16. Select the newly created proxy folder.

    This folder is the destination folder for the files that are created.

    The proxy files are created.

8.3.5.1 Rearranging and Renaming Packages

You can compile and build the project you have created

To rearrange and rename packages:

1. Locate the folder path "proxy\oracle\e1\bssv\JRH90I33\proxy" in the project folder.

   After you copy the files, ensure that you cross check that the package name and the folder structure match.

2. Select the newly created projects in which you place your newly created proxy files in OMW.

3. Select the value object java files that have been generated under the proxy folder.

4. Rename the value object files package name and place it in the appropriate folder.

   You can use the JDeveloper refactor option to change the package name and place the files in the corresponding folder.

   For example, select jpr01000.bssv.e1.oracle.RI_Address and click Refractor. Then, change the package name to:

   oracle.e1.bssv.JRH90I33.proxy.valueobject.oracle.e1.bssv.jpr01000.valueobject.RI_Address

5. Check for all references and change the package structure as appropriate.

6. Compile the project and rebuild the code to ensure no error has occurred.

8.3.6 Creating a Value Object Class

After you create the web service proxy, you create the value object class. You create the value object class based on data objects in the JD Edwards EnterpriseOne business function that will be used to call this business service. Then, you must write the code to map between data types in the value object class and the data types required by the external web service.

8.3.6.1 Passing Data

You design your business service method so that it gets the data that will be passed to the web service from either the business services server or the enterprise server. When you design your business service method, you need to consider the amount of data being passed. The more data that is passed to the business service method, the larger the memory requirements are on the enterprise server. Consuming memory on the enterprise server can significantly impact other users of the enterprise server. Creating the value object that is passed to the business service method requires careful consideration. Here are some questions you might consider:

• Is it better to assemble the data from the business services server instead of the enterprise server?

• Can key information be passed instead of constructing the entire data set on the C (enterprise server) side?

• Is one approach clearly better than the other based on the requirements?

Depending on your business service design, data is either received in the business service value object, or the business service retrieves the data from a table or business function call. Either way, data type conversions occur within the business service method. Everything that is specific to the web service being called, including data type conversions, should be contained within the business service method that wraps the web service call.

8.3.7 Creating a Business Service Class

After you create the web service proxy and the value object class, you create a business service class. This business service is a wrapper for the web service proxy. The business service wrapper is necessary because:

• Only internal business services that match the JD Edwards EnterpriseOne business service methodology can be called from the enterprise server.

• Most likely some conversion between the JD Edwards EnterpriseOne data types and the data types required by the web service provider will be required.

To create a business service class:

1. Add classes to the business service object.

   • Create the business service class.

   • Name the business service class.

   • Create a transaction, if necessary (IConnection object).

   • Declare a business service public method.

2. Add business service logic:

   • Map from the value object to the format needed by the external web service.

   • Create a call to the web service proxy.

   • Use business service properties.

   • Use softcoding.

   • Handle errors.

   • Format data.

After you create the business service for calling an external web service, you can create a JD Edwards EnterpriseOne business function that calls this business service. You can also create or use an existing JD Edwards EnterpriseOne application to call the business function.

8.3.8 Generating a Sample XML Document

You use the XML Template utility to create a sample XML document. The sample XML document is based on the value object of the business service method that is calling an external web service. This XML document provides a model for creating the XML payload in the JD Edwards EnterpriseOne business function. The XML document represents the structure of the data that is sent from the business function. The XML Template utility is provided in JDeveloper, and you access the utility by selecting a value object Java file in the JDeveloper Application Navigator pane.

To invoke the XML Template utility that generates a sample XML document:

1. Start JDeveloper from OMW.

2. In the JDeveloper navigator pane, right-click the value object of the business service method that you want to call.

3. Select Generate XML Document Template from the context menu.

   The XML Template utility creates a new XML file in the same directory as the value object. The XML file has the same name as the value object, with an extension of XML instead of Java.

4. Click the refresh icon in the JDeveloper navigator pane.

5. Open the sample XML document by double-clicking the new XML file.

8.4 Testing a Business Service That Consumes an External Web Service

You can test a business service that calls an external web service using one of these methods:

• Create a test business service.

• Use the development business services server.

Guidelines for using these methods are provided in Appendix B: Testing a Business Service That Calls an External Web Service.

See Also:

• Creating a Test Business Service.