Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Data Integrator
11g Release 1 (11.1.1)

Part Number E12643-06
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

15 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:

15.1 Introduction to Web Services in Oracle Data Integrator

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

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

Figure 15-1 Web Services in Action

Description of Figure 15-1 follows
Description of "Figure 15-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:

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.

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

15.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 21.11, "Managing Executions Using Web Services". Section 21.11 also provides examples of SOAP requests and responses.

15.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:

15.4.1 Introduction to Web Service Invocation

Web Services can be invoked:

  • In Oracle Data Integrator packages or procedures 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 15.4.2, "Using the OdiInvokeWebService Tool" for more information.

15.4.2 Using the OdiInvokeWebService Tool

The OdiInvokeWebService tool invokes a web service using the HTTP or HTTPS protocol and is able to write the returned response to an XML file, which can be an XML payload or a full-formed SOAP message including a SOAP header and body. The OdiInvokeWebService 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 in the tool command. The response of the web service request is written to an XML file that can be used in Oracle Data Integrator.

Note:

If the web service operation is one-way and does not return any response, no response file is generated.

How to create a web service request is detailed in Section 15.4.3, "Web Service Invocation in Integration Flows".

Note:

When using the XML payload format, the OdiInvokeWebService tool does not support the SOAP headers of the request. In order to work with SOAP headers, for example for secured web service invocation, use a full SOAP message and modify manually the SOAP headers.

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

The OdiInvokeWebService tool provides an Advanced editor for generating its code. This Advanced editor is available when using the OdiInvokeWebService tool in a package or when performing a Data Service test. 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 15-2 gives an overview of the Advanced Editor.

Figure 15-2 OdiInvokeWebService Advanced Editor

Description of Figure 15-2 follows
Description of "Figure 15-2 OdiInvokeWebService Advanced Editor"

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

Table 15-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 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.

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. Default timeout is 15 seconds.

  • 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 XML 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 structure of the request, the right part shows the structure of the response. This arrangement can be changed clicking Switch Panel Position. The request is displayed either in a hierarchical editor view (SOAP Editor tab), or in XML format (Source tab). When using the SOAP Editor tab, it is only possible to edit the body of the SOAP envelope. To edit or view the whole envelope, including the SOAP headers, you must use the Source tab.

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

WARNING:

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.

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 15-3 Result Section for the OdiInvokeWebService tool

Description of Figure 15-3 follows
Description of "Figure 15-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.

  • Result File Format (-RESPONSE_FILE_FORMAT): The format of the web service response file. Possible values are XML (default) and SOAP.

  • 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.23, "OdiInvokeWebService" for more information on these parameters.

Note:

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

15.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 (for example: http://host:8080/services/WSCustomer?wsdl)

    • A local file location (for example: 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 payload. The OdiInvokeWebService tool supports two web service request formats: the XML body of the SOAP request only or the full-formed SOAP envelope, including the SOAP header and body.

    Note:

    Input format (request) and output format (response) are independant. Oracle Data Integrator recognizes the input message format automatically and writes the response according to the RESPONSE_FILE_FORMAT (default is XML).However, in the Advanced editor the request file format determines the response file format. If you test the invocation using a XML payload message, the response will be XML payload. If you test using a full-formed SOAP message, the response will be a full-formed SOAP message.How to generate a web service request file with Oracle Data Integrator 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.

Note:

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

There are several ways to create a request file:

  • Create the request directly in the SOAP Editor on the Advanced tab of the OdiInvokeWebService tool. The possible format is XML.

  • Use the XML driver, similarly to what is performed for processing the response file. If generating a request file using the XML driver, the request is not a full SOAP but a simplified XML format. Use the SOAP editor for generating a template request.

  • Use an external request file that has been previously generated with ODI. The possible formats are XML and SOAP.

  • Create a SOAP request. To generate a SOAP request, you have to use a third-party tool such as, for example, the HTTP Analyzer provided by JDeveloper. See "Using the HTTP Analyzer" in the Oracle SOA Suite Developer's Guide for more information.

    To call a web service with a SOAP request, perform the standard procedure as described in Calling a Web Service using the OdiInvokeWebService tool and perform the following steps for creating the web service request in SOAP format:

    1. Create the SOAP request in the third-party tool.

    2. Copy the SOAP request and paste the entire SOAP message into the Source tab of the SOAP Editor in ODI Studio.

    3. Optionally, edit the request.

    Note that the web service response will be in SOAP format.

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.