This chapter describes how to work with web services in Oracle Data Integrator.
This chapter includes the following sections:
Section 15.1, "Introduction to Web Services in Oracle Data Integrator"
Section 15.4, "JRF-ODI Asynchronous Web Services with Callback"
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.
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.
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".
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.
When you invoke a web service synchronously, the invoking client application waits for the response to return before it can continue with its work. In cases where the response returns immediately, this method of invoking the web service might be adequate. However, because request processing can be delayed, it is often useful for the client application to continue its work and handle the response later on. By calling a web service asynchronously, the client can continue its processing, without interrupt, and will be notified when the asynchronous response is returned.
invokeStartScenWithCallback and invokeRestartSessWithCallback are ODI asynchronous web service operations, which are implemented on a JRF platform. The asynchronous nature of these operations allows the client to continue its processing and is notified when the response is returned. For more information on these web services, see Section 21.11.14, "Using Asynchronous Web Services with Callback".
To install the asynchronous web services, select the template for ODI JRF asynchronous web services when installing Oracle Data Integrator. This template extends the domain to the infrastructure used by JRF, like JMS queues and message-driven beans (MDB), and will deploy JRF-based ODI web services and other dependencies. The JRF asynchronous web services are packaged with one request and response processor MDB. For information on the asynchronous method call using a request-response queue see, "Asynchronous Web Service Using a Request and a Response Queue" in Oracle Fusion Middleware Developer's Guide for Oracle Infrastructure Web Services.
The JRF asynchronous web services can be secured through internal and external authentication methods. See Section 24.3.3, "Configuring OWSM Policies for JRF-ODI Asynchronous Web Services with Callback".
Note:
By default, the ODI JRF Asynchronous web services require the OracleSystemUser to be present in the Security Realm. If OracleSystemUser is not present, the User or Subject, as obtained from OPSS or OWSM, is used. Also, the role of the User or OracleSystemUser must be Admin, Operator, Monitor, or Deployer.This section describes how to invoke third-party web services in Oracle Data Integrator.
This section includes the following topics:
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.5.2, "Using the OdiInvokeWebService Tool" for more information.
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.5.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
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 |
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:
|
||
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. |
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.
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
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.Calling a Web Service using the OdiInvokeWebService tool
To call a Web Service:
Create an OdiInvokeWebService tool step in a package, or right-click a datastore and select Test Web Service in the contextual menu.
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
)
Choose a Port, if more than one is available.
Choose an Operation from the list on the left.
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 independent. Oracle Data Integrator recognizes the input message format automatically and writes the response according to theRESPONSE_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".
(Optional) Click Remove blank optional elements to delete optional request parameters which have not been specified. Some Web Services treat blank elements as invalid.
Click Invoke Web Service to immediately invoke the Web Service. The response is shown in right pane of the SOAP Editor.
If you are creating an OdiInvokeWebService tool step, define the response file parameters.
From the File menu, select Save.
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:
Invoke the web service once and use the Export Response XSD option to export the XML schema.
Create an XML model for the response file, based on this XML schema file and reverse-engineer the XSD to have your model structure.
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.
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:
Create the SOAP request in the third-party tool.
Copy the SOAP request and paste the entire SOAP message into the Source tab of the SOAP Editor in ODI Studio.
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.