14 Working with Web Services in Oracle Data Integrator

14.4.1 Introduction to Web Service Invocation

Web Services can be invoked:

• In Oracle Data Integrator packages using the OdiInvokeWebService tool: This tool allows you to invoke any third party web service, and save the response in a XML file that can be processed with Oracle Data Integrator.

• For testing Data Services: The easiest way to test whether your generated data services are running correctly is to use the graphical interface of the OdiInvokeWebService tool. See Section 14.4.2, "Using the OdiInvokeWebService Tool" for more information.

14.4.2 Using the OdiInvokeWebService Tool

The OdiInvokeWebService tool invokes a web service using the HTTP or HTTPS protocol and writes the returned response to an XML file. This tool invokes a specific operation on a port of a web service whose description file (WSDL) URL is provided. If this operation requires a SOAP request, it is provided either in a request file, or directly written out in the tool call (in the XMLRequest parameter). The response of the web service request is written to an XML file that can be used in Oracle Data Integrator. How to create a web service request is detailed in Section 14.4.3, "Web Service Invocation in Integration Flows".

This tool is used as a regular Oracle Data Integrator tool in a tool step of a package. Refer to Section 10.3.1.4, "Adding Oracle Data Integrator Tool Steps" for information on how to create a tool step in a package and to Appendix A, "OdiInvokeWebService" for details on the OdiInvokeWeb Service tool parameters.

The OdiInvokeWebService tool provides an Advanced editor for generating its code. In this Advanced editor you can:

• Connect to the WSDL

• Specify parameters for the tool in addition to the parameters specified in the Properties pane

• Select a specific operation on the automatically selected port and specify request parameters in the SOAP editor

• Invoke a Web Service

• Consult the Web service response in the SOAP editor

Figure 14-2 gives an overview of the Advanced Editor.

Figure 14-2 OdiInvokeWebService Advanced Editor

Description of "Figure 14-2 OdiInvokeWebService Advanced Editor"

The Advanced Editor consists of the sections described in Table 14-1.

Table 14-1 Advanced Editor Sections

Section	Icon Name	Location in Figure	Description
Web Service Description File (WSDL) URL		top	Enter here the WSDL location
Port		left	The port of the web service is set by default. If more than one port is available for the web service, select the appropriate port.
	Invoke Web Service	toolbar icon	Invokes immediately the current Web Service, displaying the response in the SOAP editor.
	Switch Panel Position	toolbar icon	Tiles vertically or horizontally the SOAP editor.
	Export Response XSD	toolbar icon	Saves the current response XML schema description to a file.
	Restore Default Request	toolbar icon	Discards the current request and reverts to a default, blank request structure.
	Delete Empty Optional Components	toolbar icon	Removes all blank optional elements from the query. This may be necessary to construct a valid query.
	Clean up before execution	toolbar icon	Automatically deletes empty optional elements in the SOAP request when Invoke Web Service is clicked. This checkbox has no effect on package steps at run-time.
	Use Request File	toolbar icon	Uses a SOAP request stored in a file instead of the parameters specified in the SOAP editor.
	Timeout (ms)	toolbar icon	Specifies a maximum period of time to wait for the request to be complete.
Operation			The list of operations for the selected port.
Options			The HTTP request options: Timeout: The web service request waits for a reply for this time before considering that the server will not provide a response and an error is produced. HTTP Authentication: If you check this box, you should provide a user and password to authenticate on your HTTP server.
SOAP Editor		middle and right	Displays the web service request on the left pane in the SOAP Editor or Source tab and the SOAP response on the right pane.

SOAP Editor

The SOAP Editor allows you to graphically build the SOAP request for the Web Service and display the response.

If creating an OdiInvokeWebService step, this SOAP request filled in the SOAP editor is saved with the step.

The left part of the editor shows the hierarchical structure of the query, the right part shows the structure of the response. This arrangement can be changed clicking Switch Panel Position. The raw XML source of the SOAP request and response are shown on the Source tab.

In the Editor, you can fill in the Value (and optionally the Attributes) for each element of your request.

Optional elements are displayed in italic. Repeatable elements are labelled with ...(n*) after the name.

Right-click any element to perform one of the following operations, if possible:

• Duplicate content - copies the structure and content of the element.

• Duplicate structure - copies the structure but leaves all fields blank.

• Delete - deletes the element.

• Export Request - exports the entire soap request to an XML file.

Results

This part of the interface appears only when using an OdiInvokeWebService tool step in a package, to control how the response is written to a XML file.

Figure 14-3 Result Section for the OdiInvokeWebService tool

Description of "Figure 14-3 Result Section for the OdiInvokeWebService tool"

• File Mode (-RESPONSE_MODE): One of NEW_FILE, FILE_APPEND, NO_FILE

• Result File (-RESPONSE_FILE): The name of the result file to write.

• XML Charset (-RESPONSE_XML_ENCODING): The name of the character encoding to write into the XML file.

• Java Charset (-RESPONSE_FILE_CHARSET): The name of the character encoding used when writing the file.

Refer to Section A.5.22, "OdiInvokeWebService" for more information on these parameters.

14.4.3 Web Service Invocation in Integration Flows

Calling a Web Service using the OdiInvokeWebService tool

To call a Web Service:

1. Create an OdiInvokeWebService tool step in a package, or right-click a datastore and select Test Web Service in the contextual menu.

2. Fill in the location of the WSDL. You can use either:

   • A URL for a WSDL that has been deployed to a server (e.g. http://host:8080/services/WSCustomer?wsdl)

   • A local file location (e.g. c:/DataServices/WSCustomer.wsdl )

3. Choose a Port, if more than one is available.

4. Choose an Operation from the list on the left.

5. In the SOAP Editor, enter the web service request. You can also use an external request file instead. This request file can be generated with ODI. How to generate a web service request file with ODI is covered in "Generating the Request File".

6. (Optional) Click Remove blank optional elements to delete optional request parameters which have not been specified. Some Web Services treat blank elements as invalid.

7. Click Invoke Web Service to immediately invoke the Web Service. The response is shown in right pane of the SOAP Editor.

8. If you are creating an OdiInvokeWebService tool step, define the response file parameters.

9. From the File menu, select Save.

Processing the Response File

When using the OdiInvokeWebService tool to call a web service, the response is written to an XML file.

Processing this XML file can be done with Oracle Data Integrator, using the following guidelines:

1. Invoke the web service once and use the Export Response XSD option to export the XML schema.

2. Create an XML model for the response file, based on this XML schema file and reverse-engineer the XSD to have your model structure.

3. You can now process the information from your responses using regular Oracle Data Integrator interfaces sourcing for the XML technology.

Refer to the Connectivity and Modules Guide for Oracle Data Integrator for more information on XML file processing.

Oracle Data Integrator provides the OdiXMLConcat and OdiXMLSplit tools for processing the web service response. Refer to the XML section of the Appendix A, "ODI Tools per Category" for details on how to use these tools.

Generating the Request File

To generate the request file, it is also possible to use the XML driver, similarly to what is performed for processing the response file.

Using the Binding Mechanism for Requests

It is possible to use the Binding mechanism when using a web service call in a Procedure. With this method, it is possible to call a web service for each row returned by a query, parameterizing the request based on the row's values. Refer to "Binding Source and Target Data" for more information.