Oracle® Enterprise Data Quality for Product Data Web Service Access to Oracle DataLens Servers Interface Guide

Release 11g R1 (11.1.1.6)

E29146-01

Oracle® Enterprise Data Quality for Product Data

Web Service Access to Oracle DataLens Servers Interface Guide

Release 11g R1 (11.1.1.6)

E29146-01

August 2012

This document describes the Oracle Enterprise Data Quality for Product Data Web Access to Oracle DataLens Servers and contains the following:

- "Overview"

- "Obtaining the EDQP WSDL Document"

- "Communicating with a DSA"

Overview

Web service access is provided to the Oracle DataLens Server as a Document-Literal Web Service. The following sections describe how to set up this access and the Web Service Operations that you can use to interface with Enterprise DQ for Product (EDQP) Data Service Applications (DSAs) including examples.

Obtaining the EDQP WSDL Document

To integrate with an Enterprise DQ for Product DSA as a Web Service, you need software that will interface with the Oracle DataLens Web Services. There are a number of tools available to generate this software from a Web Services Description Language (WSDL) document, which is an XML format for describing network services. You can view the WSDL for the Oracle DataLens Web Services by using an Internet browser.

Browse to the following Web site:

http://server:port/datalens/ws/Processor?wsdl

Where server:port is the hostname and port number of your Oracle DataLens Server.

This displays the WSDL document, which can be saved by right-clicking in the document in the browser, selecting View Source, and then saving the file from within your browser. For instance, the file can be saved as Processor.wsdl.

Client Web Service Software

For your Web Service clients, client-side software can be generated from this WSDL document to access the Oracle DataLens Server.

Communicating with a DSA

There is a single Service called "ProcessorService", which uses a PortType (Interface) called "Processor".

The following three Oracle DataLens Web Services Operations can be used to process data and communicate with a DSA by creating a job:

ProcessorList

This requires an input array of strings, or multiple lines of data, and returns an output array of strings. One DSA job is created.

ProcessorOneLine

This requires a single string of input, or one line of data, and returns a single string of output. If you have several lines of data, use ProcessorList to process them because a single DSA job is created rather than the multiple DSA jobs that would be created using the ProcessorOneLine operation for each line of data. For example, if you have four lines of data to process, the ProcessorList creates one DSA job while the ProcessorOneLine creates four separate DSA jobs.

ProcessorDB

This requires a database query (defined in the Transform Map) and returns a job Id of the DSA Job that handled the request. The output is assumed to be a database update, e-mail, or FTP. One DSA job is created.

Points to Consider

- Reviewing the EDQP WSDL will help you to understand what operations and parameters can be used to communicate with DSAs.

- Simple Object Access Protocol (SOAP) is used to communicate with DSAs. For more information about SOAP, see the W3C SOAP 1.1 Web site:
http://www.w3.org/TR/2000/NOTE-SOAP-20000508/

- You must provide the exact input fields that are defined in the DSA to ensure proper operation and avoid errors. For example, if the input nodes in the DSA are Id, Category, and Description, you must provide all three fields in your SOAP processing operation.

- You must separate input fields using a defined separator; the tab character "î" is recommended. For example, using the tab character to separate the Id, Category, and Description input fields:

<lineOfData>3î2334îres, 37ohm, 39watt, 30%</lineOfData>

- The best practice is to define all of the operation parameters (even those that may be labeled as optional) to avoid errors. The EDQP WSDL and the DSA define the necessary parameters not the SOAP UI you are using; some SOAP UIs erroneously mark parameters as optional as in the examples in the following sections.
The SOAP request structure is the same for each type of request though some of the parameters may not apply. For example, processListRequest and processOneLineRequest do not use the dbparameters parameter; processDBRequest does not use line or linesofdata parameters. The parameters used are dependent on the operation request.

Additionally, defining all parameters allows the most information possible to be related to the DSA job, and then reviewed and verified in the Oracle DataLens Server Administration Web Page.

processListRequest and processOneLineRequest Operations

The difference between these two operations is that processListRequest takes an array of lines and processLineRequest takes a single line of data as a string. The transformed data is returned. This call is synchronous. The parameters are as follows:

dsaName

The name of the DSA to run on the Oracle DataLens Server.

line or linesOfData

One line or multiple lines of input or output data respectively.

dbParameters

Not used.

priority

The priority the DSA job will be given on the Oracle DataLens Server for processing; the default is Medium. The priority is set numerically as follows:

3 for High
2 for Medium (the default)
1 for Low

runtimeLocale

A run time locale must be entered; the default locale of en_US should be entered if not known.

fieldSeparatorChar

A character that will be used to separate fields; the tab character "î" is recommended.

application

This application name initiated the client request to the server. The application name must be a valid LDAP entry in the WebLogic Server to avoid a failure. This name is used to accumulate server statistics on the Oracle DataLens Server Administration Web Page.

description

A description of a particular job and relates to a DSA Job ID.

The Oracle DataLens Server Administration Server Job Status Web page shows the DSA Job ID for both the processListRequest and processLineRequest operations as in Figure 1.

Figure 1 DSA Jobs with Single and Multiple Line Input

Additionally, the priority parameter that was set is displayed in the Priority column.

The following Oracle DataLens Server Administration Server Job Detail Web page illustrates the operation parameters supplied in the processListRequest operation as in Figure 2.

Figure 2 DSA Job Details and Corresponding Request Parameters

The following sections provide examples of request and response operations for both the processListRequest and processLineRequest operations:

SOAP Doc-Lit Multi-Line ProcessList Request Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/ws">
<soapenv:Header/>
<soapenv:Body>
<ws:processList>
<dsaName>sampleDSA</dsaName>
<!--Zero or more repetitions:-->
<linesOfData>1îres, 17ohm, 19watt, 10%</linesOfData>
<linesOfData>2îres, 27ohm, 29watt, 20%</linesOfData>
<linesOfData>3îres, 37ohm, 39watt, 30%</linesOfData>
<!--Zero or more repetitions:-->
<dbParameters>?</dbParameters>
<!--Optional:-->
<priority>1</priority>
<!--Optional:-->
<runtimeLocale>en_US</runtimeLocale>
<!--Optional:-->
<fieldSeparator>î</fieldSeparator>
<!--Optional:-->
<application>dlsadmin</application>
<!--Optional:-->
<description>Example list Doc-Lit client call</description>
</ws:processList>
</soapenv:Body>
</soapenv:Envelope>

SOAP Doc-Lit Multi-Line ProcessList Response Example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:processListResponse xmlns:ns2="http://www.oracle.com/ws">
<return>1îResistor, 17 Ohm, 10%, 19 Wattî32121609îFixed resistorsîResistorîItem_NameîRESISTORîItem_TypeîîResistanceî17 OHMîPowerî19îToleranceî10%îPackage_SizeîîConstructionîîMountingîîPin_Count
îîFor_sale_packagingî</return>
<return>2îResistor, 27 Ohm, 20%, 29 Wattî32121609îFixed resistorsîResistorîItem_NameîRESISTORîItem_TypeîîResistanceî27 OHMîPowerî29îToleranceî20%îPackage_SizeîîConstructionîîMountingîîPin_Count
îîFor_sale_packagingî</return>
<return>3îResistor, 37 Ohm, 30%, 39 Wattî32121609îFixed resistorsîResistorîItem_NameîRESISTORîItem_TypeîîResistanceî37 OHMîPowerî39îToleranceî30%îPackage_SizeîîConstructionîîMountingîîPin_Count
îîFor_sale_packagingî</return>
</ns2:processListResponse>
</S:Body>
</S:Envelope>

SOAP Document-Literal One Line Request Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/ws">
<soapenv:Header/>
<soapenv:Body>
<ws:processOneLine>
<dsaName>sampleDSA</dsaName>
<!--Optional:-->
<line>1îres, 17ohm, 19watt, 20%</line>
<!--Zero or more repetitions:-->
<dbParameters>?</dbParameters>
<!--Optional:-->
<priority>1</priority>
<!--Optional:-->
<runtimeLocale>en_US</runtimeLocale>
<!--Optional:-->
<fieldSeparator>î</fieldSeparator>
<!--Optional:-->
<application>dlsadmin</application>
<!--Optional:-->
<description>Example Doc-Lit client call</description>
</ws:processOneLine>
</soapenv:Body>
</soapenv:Envelope>

SOAP Document-Literal One Line Response Example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:processOneLineResponse xmlns:ns2="http://www.oracle.com/ws">
<return>1îResistor, 17 Ohm, 20%, 19 Wattî32121609îFixed resistorsîResistorîItem_NameîRESISTORîItem_TypeîîResistanceî17 OHMîPowerî19îToleranceî20%îPackage_SizeîîConstructionîîMountingîîPin_Count
îîFor_sale_packagingî</return>
</ns2:processOneLineResponse>
</S:Body>
</S:Envelope>

processDBRequest

This call takes the database parameters as input and returns the DSA Job ID. This call is asynchronous. The parameters are as follows and are the same as described in "processListRequest and processOneLineRequest Operations":

dsaName
dbParameters
priority
runtimeLocale
fieldSeparatorChar
application
description

However, the dbParameters parameter is the value that is input to the DSA database query and is related to the DSA job run.

The following sections provide example request and response operations for the processDb operation:

SOAP Document-Literal processDb Request Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://www.oracle.com/ws">
<soapenv:Header/>
<soapenv:Body>
<ws:processDB>
<dsaName>SampleDSADbInput</dsaName>
<!--Zero or more repetitions:-->
<dbParameters>1</dbParameters>
<dbParameters>2</dbParameters>
<!--Optional:-->
<priority>2</priority>
<!--Optional:-->
<runtimeLocale>en_US</runtimeLocale>
<!--Optional:-->
<fieldSeparator>|</fieldSeparator>
<!--Optional:-->
<application>dlsadmin</application>
<!--Optional:-->
<description>Example Db Input Doc-Lit client call</description>
</ws:processDB>
</soapenv:Body>
</soapenv:Envelope>

The field separator will be used when the output from the database job is a text file.

SOAP Document-Literal processDb Response Example

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:processDBResponse xmlns:ns2="http://www.oracle.com/ws">
<return>16</return>
</ns2:processDBResponse>
</S:Body>
</S:Envelope>

The return value of the preceding processDb call is the DSA Job ID, in this case 16. This job reads data from the database and updates other fields in the database as in Figure 3.

Figure 3 DSA Job ID Database Process Request

Related Documents

For more information, see the following documents in the documentation set:

- The Oracle Enterprise Data Quality for Product Data Getting Started Guide provides information about how to get started with EDQP.

- The Oracle Enterprise Data Quality for Product Data Oracle DataLens Server Installation Guide provides detailed Oracle DataLens Server installation instructions.

- The Oracle Enterprise Data Quality for Product Data R12 PIM Connector Installation Guide provides installation and configuration of Enterprise DQ for Product R12 PIM Connector.

- The Oracle Enterprise Data Quality for Product Data R12 PIM Connector User's Guide provides highlights of the core process steps and features of Enterprise DQ for Product R12 PIM Connector.

See the latest version of this and all documents in the Oracle Enterprise Data Quality for Product Data Documentation Web site at

http://docs.oracle.com/cd/E35636_01/index.htm

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Oracle Enterprise Data Quality for Product Data Web Service Access to Oracle DataLens Servers Interface Guide, Release 11g R1 (11.1.1.6)

E29146-01

Copyright © 2011, 2012,  Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Copyright © 2011, 2012, Oracle and/or its affiliates. All rights reserved.