14 Working with Web Services in Oracle Data Integrator

This chapter describes how to work with web services in Oracle Data Integrator.

This chapter includes the following sections:

14.1 Introduction to Web Services in Oracle Data Integrator

Oracle Data Integrator provides the following entry points into a service-oriented architecture (SOA):

Figure 14-1 gives an overview of how the different types of Web services can interact.

Figure 14-1 Web Services in Action

Description of Figure 14-1 follows
Description of "Figure 14-1 Web Services in Action"

It shows a simple example with the Data Services, Run-Time Web services (Public Web Service and Agent Web Service) and the OdiInvokeWebService tool.

The Data Services and Run-Time Web Services components are invoked by a third-party application, whereas the OdiInvokeWebService tool invokes a third-party Web service:

  • The Data Services provides access to data in data stores (both source and target data stores), as well as changes trapped by the Changed Data Capture framework. This web service is generated by Oracle Data Integrator and deployed in a Java EE application server.

  • The Public Web Service connects to the repository to retrieve a list of context and scenarios. This web service is deployed in a Java EE application server.

  • The Agent Web Service commands the Oracle Data Integrator Agent to start and monitor a scenario and to restart a session. Note that this web service is built-in the Java EE or Standalone Agent.

  • The OdiInvokeWebService tool is used in a package and invokes a specific operation on a port of the third-party Web service, for example to trigger a BPEL process.

Oracle Data Integrator Run-Time Web services and Data Services are two different types of Web services. Oracle Data Integrator Run-Time Web services enable you to access the Oracle Data Integrator features through Web services, whereas the Data Services are generated by Oracle Data Integrator to give you access to your data through Web services.

14.2 Data Services

Data Services are specialized Web Services that provide access to data in datastores, and to changes captured for these datastores using Changed Data Capture. These Web Services are automatically generated by Oracle Data Integrator and deployed to a Web Services container in an application server.

For more information on how to set up, generate and deploy Data Services refer to Chapter 8, "Working with Data Services".

14.3 Oracle Data Integrator Run-Time Services

Oracle Data Integrator Run-Time Services are web services that enable users to leverage Oracle Data Integrator features in a service-oriented architecture (SOA). These web services are invoked by a third-party application manage start scenarios developed with Oracle Data Integrator.

How to perform the different ODI execution tasks with the ODI Run-Time Services such as executing a scenario, restarting a session, listing execution contexts and scenarios is detailed in Section 19.7, "Managing Executions Using Web Services". Section 19.7 also provides examples of SOAP requests and responses.

14.4 Invoking Third-Party Web Services

This section describes how to invoke third-party web services in Oracle Data Integrator.

This section includes the following topics:

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".


The OdiInvokeWebService tool does not support customizing the SOAP Headers of the request. Therefore, it does not support secured web service invocation.

This tool is used as a regular Oracle Data Integrator tool in a tool step of a package. Refer to Section, "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 follows
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




Enter here the WSDL location




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 icon

Invoke Web Service

toolbar icon

Invokes immediately the current Web Service, displaying the response in the SOAP editor.

Switch Panel Position icon

Switch Panel Position

toolbar icon

Tiles vertically or horizontally the SOAP editor.

Export Reponse XSD

Export Response XSD

toolbar icon

Saves the current response XML schema description to a file.

Restore Default Request icon

Restore Default Request

toolbar icon

Discards the current request and reverts to a default, blank request structure.

Delete Empty Optional Components

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 icon

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

Use Request File

toolbar icon

Uses a SOAP request stored in a file instead of the parameters specified in the SOAP editor.

Timeout (ms) icon

Timeout (ms)

toolbar icon

Specifies a maximum period of time to wait for the request to be complete.



The list of operations for the selected port.



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.


An empty element is passed as is to the Web service. For strings, this corresponds to an empty string. For numbers or date types, this may cause an error. If you want to send a null string, number or date, it is recommended to use the nil="true"attribute. To remove empty elements, click Remove blank optional elements in the Advanced editor toolbar.

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.


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 follows
Description of "Figure 14-3 Result Section for the OdiInvokeWebService tool"


  • 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.


The result file parameters are only taken into account at run-time. No result file is generated when clicking Invoke Web Service.

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.


Each XML file is defined as a model in Oracle Data Integrator. When using XML file processing for the request or response file, model will be created for each request or response file. It is recommended to use model folders to arrange them. See Section 16.2, "Organizing Models with Folders" for more information.

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.


If generating a request file manually or using the XML driver, note that the request is not a full SOAP but a simplified XML format. Use the SOAP editor for generating a template request.

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.