Professional Documents
Culture Documents
Informatica PowerCenter
(Version 8.1.1)
Informatica PowerCenter Web Services Provider Guide Version 8.1.1 April 2007 Copyright (c) 19982006 Informatica Corporation. All rights reserved. Printed in the USA. This software and documentation contain proprietary information of Informatica Corporation and are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright law. Reverse engineering of the software is prohibited. No part of this document may be reproduced or transmitted in any form, by any means (electronic, photocopying, recording or otherwise) without prior consent of Informatica Corporation. Use, duplication, or disclosure of the Software by the U.S. Government is subject to the restrictions set forth in the applicable software license agreement and as provided in DFARS 227.7202-1(a) and 227.7702-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14 (ALT III), as applicable. The information in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Informatica Corporation does not warrant that this documentation is error free. Informatica, PowerCenter, PowerCenterRT, PowerCenter Connect, PowerCenter Data Analyzer, PowerMart, SuperGlue, Metadata Manager, Informatica Data Quality and Informatica Data Explorer are trademarks or registered trademarks of Informatica Corporation in the United States and in jurisdictions throughout the world. All other company and product names may be trade names or trademarks of their respective owners. Portions of this software and/or documentation are subject to copyright held by third parties, including without limitation: Copyright DataDirect Technologies, 1999-2002. All rights reserved. Copyright Sun Microsystems. All Rights Reserved. Copyright RSA Security Inc. All Rights Reserved. Copyright Ordinal Technology Corp. All Rights Reserved. Informatica PowerCenter products contain ACE (TM) software copyrighted by Douglas C. Schmidt and his research group at Washington University and University of California, Irvine, Copyright (c) 1993-2002, all rights reserved. Portions of this software contain copyrighted material from The JBoss Group, LLC. Your right to use such materials is set forth in the GNU Lesser General Public License Agreement, which may be found at http://www.opensource.org/licenses/lgpl-license.php. The JBoss materials are provided free of charge by Informatica, as-is, without warranty of any kind, either express or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose. Portions of this software contain copyrighted material from Meta Integration Technology, Inc. Meta Integration is a registered trademark of Meta Integration Technology, Inc. This product includes software developed by the Apache Software Foundation (http://www.apache.org/). The Apache Software is Copyright (c) 1999-2005 The Apache Software Foundation. All rights reserved. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit and redistribution of this software is subject to terms available at http://www.openssl.org. Copyright 1998-2003 The OpenSSL Project. All Rights Reserved. The zlib library included with this software is Copyright (c) 1995-2003 Jean-loup Gailly and Mark Adler. The Curl license provided with this Software is Copyright 1996-2004, Daniel Stenberg, <Daniel@haxx.se>. All Rights Reserved. The PCRE library included with this software is Copyright (c) 1997-2001 University of Cambridge Regular expression support is provided by the PCRE library package, which is open source software, written by Philip Hazel. The source for this library may be found at ftp://ftp.csx.cam.ac.uk/pub/software/programming/ pcre. InstallAnywhere is Copyright 2005 Zero G Software, Inc. All Rights Reserved. Portions of the Software are Copyright (c) 1998-2005 The OpenLDAP Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted only as authorized by the OpenLDAP Public License, available at http://www.openldap.org/software/release/license.html. This Software is protected by U.S. Patent Numbers 6,208,990; 6,044,374; 6,014,670; 6,032,158; 5,794,246; 6,339,775 and other U.S. Patents Pending. DISCLAIMER: Informatica Corporation provides this documentation as is without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of non-infringement, merchantability, or use for a particular purpose. The information provided in this documentation may include technical inaccuracies or typographical errors. Informatica could make improvements and/or changes in the products described in this documentation at any time without notice.
Table of Contents
List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv Other Informatica Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Visiting Informatica Customer Portal . . . . . . . . . . . . . . . . . . . . . . . . . . xv Visiting the Informatica Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Visiting the Informatica Developer Network . . . . . . . . . . . . . . . . . . . . . xv Visiting the Informatica Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . xv Obtaining Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Integration Service in Safe Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Web Services Hub Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Web Services Hub Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Configuring the Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Viewing the Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 SOAP Fault Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 SOAP Fault Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 SOAP Fault Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
iv
Table of Contents
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Writing a Client Application in Java for Realtime Web Services . . . . . . . . . . 50 Step 1. Generate Client Proxy Classes in Axis . . . . . . . . . . . . . . . . . . . . 51 Step 2. Initialize the Web Service Objects . . . . . . . . . . . . . . . . . . . . . . . 51 Step 3. Create the Request Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Step 4. Send the Request and Handle the Response . . . . . . . . . . . . . . . . 52 Using Parameter Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Parameter Array Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Rules and Guidelines for Using Parameter Arrays . . . . . . . . . . . . . . . . . 56
vi
Table of Contents
Configuring Commit Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Configuring Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Running Sessions and Web Service Workflows . . . . . . . . . . . . . . . . . . . . . . 90 Working with XML and Flat File Sessions . . . . . . . . . . . . . . . . . . . . . . . 90 Understanding Service Timeout and Flush Latency . . . . . . . . . . . . . . . . 90 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Table of Contents
vii
viii
Table of Contents
List of Figures
Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure Figure 1-1. 2-1. 3-1. 3-2. 3-3. 3-4. 6-1. 6-2. 6-3. 6-4. 6-5. 6-6. 6-7. 7-1. 7-2. 7-3. 7-4. Building Blocks of a Web Service . . . . . . . . . . . . . . . . Web Services Provider Architecture . . . . . . . . . . . . . . . Web Services Hub Console . . . . . . . . . . . . . . . . . . . . . Batch Web Services Page . . . . . . . . . . . . . . . . . . . . . . Realtime Web Services Page . . . . . . . . . . . . . . . . . . . . Realtime Service Description Page . . . . . . . . . . . . . . . Web Service Source Definition . . . . . . . . . . . . . . . . . . Web Service Target Definitions . . . . . . . . . . . . . . . . . Columns Tab for a Web Service Definition . . . . . . . . . Attributes Tab for a Web Service Definition . . . . . . . . Metadata Extensions Tab for a Web Service Definition XML Editor Views of Web Service Definition . . . . . . . Request-Response Mapping . . . . . . . . . . . . . . . . . . . . Creating a Web Service Workflow . . . . . . . . . . . . . . . . Web Service Configuration . . . . . . . . . . . . . . . . . . . . . Web Services Provider Reader Properties . . . . . . . . . . . Web Services Provider Writer Properties . . . . . . . . . . . .................. .................. .................. .................. .................. .................. .................. .................. .................. .................. .................. .................. .................. .................. .................. .................. .................. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 10 15 16 17 18 59 61 67 68 69 70 73 79 80 83 85
List of Figures
ix
List of Figures
List of Tables
Table Table Table Table Table Table Table Table Table Table 3-1. 3-2. 6-1. 6-2. 6-3. 6-4. 6-5. 7-1. 7-2. 7-3. Columns in Realtime Web Services Page . . . . . . . . . . . . . Realtime Service Description Page . . . . . . . . . . . . . . . . . Web Services Definition Groups . . . . . . . . . . . . . . . . . . . Message Header Ports . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced Options for Importing Web Service Definitions Required Sources and Targets in a Service . . . . . . . . . . . Attachment Group Ports . . . . . . . . . . . . . . . . . . . . . . . . Web Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . Web Services Provider Reader Properties . . . . . . . . . . . . . Web Services Provider Writer Properties . . . . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . .. .. .. .. .. .. .. .. .. .. . . . . . . . . . . . . . . . . . . . . 17 18 60 60 63 72 76 80 83 86
List of Tables
xi
xii
List of Tables
Preface
Welcome to PowerCenter, the Informatica software product that delivers an open, scalable data integration solution addressing the complete life cycle for all data integration projects including data warehouses, data migration, data synchronization, and information hubs. PowerCenter combines the latest technology enhancements for reliably managing data repositories and delivering information resources in a timely, usable, and efficient manner. The PowerCenter repository coordinates and drives a variety of core functions, including extracting, transforming, loading, and managing data. The Integration Service can extract large volumes of data from multiple platforms, handle complex transformations on the data, and support high-speed loads. PowerCenter can simplify and accelerate the process of building a comprehensive data warehouse from disparate data sources.
xiii
Document Conventions
This guide uses the following formatting conventions:
If you see It means The word or set of words are especially emphasized. Emphasized subjects. This is the variable name for a value you enter as part of an operating system command. This is generic text that should be replaced with user-supplied values. The following paragraph provides additional facts. The following paragraph provides suggested uses. The following paragraph notes situations where you can overwrite or corrupt data, unless you follow the specified procedure. This is a code example. This is an operating system command you enter from a prompt to run a task.
xiv
Preface
Informatica Customer Portal Informatica web site Informatica Developer Network Informatica Knowledge Base Informatica Technical Support
support@informatica.com for technical inquiries support_admin@informatica.com for general customer service requests
WebSupport requires a user name and password. You can request a user name and password at http://my.informatica.com.
North America / South America Informatica Corporation Headquarters 100 Cardinal Way Redwood City, California 94063 United States Europe / Middle East / Africa Informatica Software Ltd. 6 Waltham Park Waltham Road, White Waltham Maidenhead, Berkshire SL6 3TN United Kingdom Asia / Australia Informatica Business Solutions Pvt. Ltd. Diamond District Tower B, 3rd Floor 150 Airport Road Bangalore 560 008 India Toll Free Australia: 1 800 151 830 Singapore: 001 800 4632 4357 Standard Rate India: +91 80 4112 5738
Standard Rate Belgium: +32 15 281 702 France: +33 1 41 38 92 26 Germany: +49 1805 702 702 Netherlands: +31 306 022 797 United Kingdom: +44 1628 511 445
xvi
Preface
Chapter 1
Overview, 2 Simple Object Access Protocol (SOAP), 4 Web Services Description Language (WSDL), 5
Overview
Web services are business functions that operate over the Web. They describe a collection of operations that are network accessible through standardized XML messaging. The PowerCenter Web Services Provider lets you integrate the PowerCenter metadata and data integration functionalities and expose them as web services. You can write applications that can communicate with Integration Services using any language and platform. You can embed these applications easily in existing components and products. Web services are based on open standards, such as XML, SOAP, and WSDL, which offer greater interoperability than traditional proprietary applications. Examples of web services include business services, such as stock quotes, airline schedules, and credit checks. The components that enable web services include:
Simple Object Access Protocol (SOAP). SOAP is the communications protocol for web services. It is the specification that defines the XML format for web service messages. Web Service Definition Language (WSDL). WSDL is an XML document that describes web service operations. Registry. Directory of published web services. Some web service providers publish services in Universal Description, Discovery, and Integration (UDDI). Registering a web service in the UDDI is optional.
Note: The PowerCenter Web Services Provider does not use the UDDI registry.
To build a web service client for the PowerCenter Web Services Provider, you select the web service you want to interface with and retrieve the WSDL file for the selected web service. Using a web service tool kit such as Axis, generate the client proxies. The client proxies contain all of the function calls required to interact with a web service. You can determine what functions a web service offers, the data the web service requires, and the location of the service by examining the WSDL. The WSDL describes the web service interfaces and the operations available for the service. Use the information in the WSDL to build a client application to use the services. For more information about writing client applications, see Writing Client Applications on page 35.
Overview
SOAP envelope. The envelope defines the framework of the message, including the content of the message, who or what should handle it, and whether it is optional or mandatory. SOAP header. The header is an element of the SOAP envelope that lets you add features to a SOAP message in a decentralized manner. SOAP body. The body is the container for mandatory information that provides a mechanism for exchanging information with the intended recipient.
Authentication and transaction management are typical examples of extensions that can be implemented as header entries. The SOAP header helps to process the data in the body of the SOAP message. Information related to authentication or transactions is usually contained in the header because this information identifies the entity that sent the SOAP message body and the context in which it will be processed. Use a SOAP toolkit to create and parse SOAP messages. A SOAP toolkit translates function calls from another language to a SOAP message. For example, the Apache Axis toolkit translates Java function calls to SOAP. Use SOAP to implement web services on different platforms both inside and outside an organization. Each SOAP implementation supports different function calls and parameters. Therefore, a function that works with one toolkit may not work with another.
Chapter 2
Overview
PowerCenter, with its service-oriented architecture, is a collection of services that interact to provide data integration functionality. A domain is the basic administration unit for the PowerCenter services. The services include a Service Manager that supports domain administration and application services that provide PowerCenter data integration functionality. The application services include the Integration Service, Repository Service, SAP BW Service, and the Web Services Hub. The Web Services Hub is a web service gateway that makes PowerCenter data integration functionality available to external client applications through web services. The Web Services Hub and the web services hosted by the Web Services Hub comprise the Web Services Provider.
Batch web services. Services that enable you to run and monitor workflows and access metadata information. Realtime web services. Services that enable you to access the PowerCenter data integration functionality from a web service client and run workflows.
For more information about the Web Services Hub, see Understanding the Web Services Hub on page 13.
Data Integration web services. Use the Data Integration web services to connect to the Integration Service and run and monitor PowerCenter workflows. The Data Integration web services provides operations that allow you to get details on the Integration Service, schedule and run workflows, start and stop tasks in a workflow, and monitor and get statistics on sessions. For more information about the Data Integration web services, see Data Integration Web Service Operations on page 29. Metadata web services. Metadata web services provide operations that retrieve metadata from PowerCenter repositories. Use the Metadata web services to get information about repository objects such as folders, workflows, and workflow tasks to help you run and
monitor workflows in a repository. For more information about the Metadata web services, see Metadata Web Service Operations on page 27. For more information about Batch web services operations, see Batch Web Service Operations on page 25.
Overview
Web Services Hub Realtime Web Services Batch Web Services Integration Service
Workflow
The Web Services Hub processes service requests in similar ways for Realtime web services and Batch web services. The following process describes the architecture of the Web Services Provider: 1. 2. 3. A web service client sends a SOAP message to the Web Services Hub to run a service. For Batch web services or protected Realtime web services, the Web Services Hub authenticates the web service client based on the repository user name and password. The Web Services Hub generates a message ID for the request. If the service request is for a realtime service, the Web Services Hub generates a message ID and sends the SOAP request to the Integration Service. If the service request is for a batch service, the Web Services Hub sends the request to the Integration Service or Repository Service to process. The request may be to run or monitor a workflow, start or stop the server, or get log information. 4. The Integration Service processes the request. If the request is for a realtime service, the Integration Service sends the processed data to the Web Services Hub which uses the message ID to correlate the request with the response. The Web Services Hub sends a SOAP response to the web service client.
10
If the service request is for a batch service, the Web Services Hub sends a response based on the request. For example, if you request statistics for a session running on the Integration Service, the Web Services Hub response includes session information such as the folder and workflow name, session and task run status, and the number of applied, affected, and rejected rows. The Integration Service and Web Services Hub communicate with the Repository Service throughout the process.
11
12
Chapter 3
Overview, 14 Using the Web Services Hub Console, 15 Web Services Hub and Integration Service, 19 Web Services Hub Security, 20 Web Services Hub Logs, 21 SOAP Fault Handling, 22
13
Overview
The Web Services Hub is a gateway that makes PowerCenter functionality accessible to external clients as web services. It receives requests from web service clients and passes them to the Integration Service. The Integration Service processes the requests and sends a response to the web service client through the Web Services Hub. The Web Services Hub hosts Batch web services and Realtime web services. For more information about the Batch web services, see Batch Web Services on page 8. For more information about the Realtime web services, see Realtime Web Services on page 9. When you install PowerCenter, the PowerCenter installer installs the Web Services Hub. The Web Services Hub is an application service in the PowerCenter domain. After installation, use the Administration Console to create a Web Services Hub and enable it as you would other application services in the domain. For more information about creating and enabling a Web Services Hub, see Creating and Configuring the Web Services Hub in the PowerCenter Administrator Guide. The Web Services Hub connects to the Repository Service and the Integration Service through TCP/IP. Web service clients log in to the Web Services Hub through HTTP or HTTPS. All services are stateless services. The Web Services Hub authenticates the web service client based on the repository user name and password included in every service request. Use the Web Services Hub console to view web service information and download the WSDL files necessary for running services and workflows.
14
Figure 3-1 shows the main page for the Web Services Hub console:
Figure 3-1. Web Services Hub Console
15
Figure 3-2 shows the main page for the Batch web services page:
Figure 3-2. Batch Web Services Page
Use the Metadata WSDL to write client applications that call Metadata web service operations. Use the DataIntegration WSDL to write client applications that call Data Integration web service operations. For more information about the Metadata web service operations, see Metadata Web Service Operations on page 27. For more information about the Data Integration web service operations, see Data Integration Web Service Operations on page 29.
16
Figure 3-3 shows the main page for the Realtime Web Services page:
Figure 3-3. Realtime Web Services Page
Table 3-1 describes the columns displayed on the Realtime Web Services page:
Table 3-1. Columns in Realtime Web Services Page
Column Service Name Domain Name Repository Name Folder Name Workflow Name WSDL Description Service name defined in the web service workflow. Domain containing the Repository Service. Name of the Repository Service. Folder containing the service. Workflow associated with the web service. WSDL published by the Web Services Hub for the service.
To view additional service information, such as the Runnable and Protected properties, you can click on a service name.
17
Table 3-2 describes the properties on the Realtime Service Description page:
Table 3-2. Realtime Service Description Page
Property Service Name Repository Name Folder Name Workflow Name Is Runnable Description Service name defined in the web service workflow. Repository containing the service. Folder containing the service. Workflow associated with the web service. Indicates the runnable value. For more information about runnable services, see Creating and Configuring a Web Service Workflow on page 79. Indicates whether the service is protected or public. For more information about protected services, see Creating and Configuring a Web Service Workflow on page 79. Indicates whether the service is one-way or request-response. WSDL published by the Web Services Hub to run the service.
Is Protected
Before you can build a client application to run a web service, you need to know the service name and the protected status of the service. If the web service is protected, the client application must call the Login operation and pass the user name and password through the HTTP header. If the web service is public, the client application does not need authentication.
18
service workflows with an Integration Service running in safe mode, the Web Services Hub does not take advantage of high availability features such as failover and automatic recovery.
19
Encryption. The Web Services Hub encrypts the repository login information in the configuration file used to connect to the repository. The Web Services Hub also supports the HTTPS protocol for encryption of web service client requests. Authentication. The Web Services Hub authenticates requests from web service clients based on the user name and password. A web service client must embed the repository user name, and password in every SOAP request sent to the Web Services Hub. For Batch web services and protected Realtime web services, the web service client application must call the Login operation before it calls other operations. The Web Services Hub authenticates a request based on the user name and password. Authorization. A web service client with repository access must have execute permission on a folder to run a service. For protected realtime services, a web service client with execute permission on a folder can run a service in that folder based on service configuration. For example, if the service is not runnable, a web service client cannot start the service, but it can invoke the service if the web service workflow is running. For more information about user access to the web service workflow, see Creating and Configuring a Web Service Workflow on page 79.
For more information about user access to services, see Managing Users and User Accounts in the PowerCenter Administrator Guide.
Note: If a realtime web service is public, the Web Services Hub does not authenticate web
service requests.
20
when it cannot process the request. For more information about fault handling, see SOAP Fault Handling on page 22.
21
If the Web Services Hub cannot process the header element of a SOAP request message, it returns error information related to the header entries of the SOAP request message in a child element of the SOAP response header element. If the Web Services Hub encounters any error with the header element of a SOAP request, it does not process the body element. The SOAP response to the request contains the header fault element in the SOAP header and a SOAP fault element without the detail element. If the Web Services Hub cannot process the contents of the body element, the SOAP fault element in the SOAP response message contains a detail element with error information. The Integration Service receives requests from the Web Services Hub to run web service workflows. If the web service workflow is configured to send error data to the target, the Integration Service writes messages to fault targets.
Messages contain a message code that includes a prefix and code number and the message text. For example, the message code WSH_95002 has the following associated message text:
Invalid request parameter. Workflow name cannot be null.
The message code is the ErrorCode element in the detail element of a SOAP fault, and the message text is the faultstring element of the SOAP fault. For a listing of error codes related to the Web Services Hub, see WSH Messages in the PowerCenter Troubleshooting Guide.
22
Faultcode. The faultcode determines if the error originates at the web service client or the Integration Service. If the error originates at the web service client, the message may have the wrong structure. Faultstring. The faultstring provides a description of the error. The faultstring value indicates that the error originated from the Integration Service, Web Services Hub, or Repository Service. Detail. The detail element contains error information that includes an error code, and the extended details provide detailed error information when the faultstring is a Web Services Hub or repository error.
The Web Services Hub uses the following SOAP fault schema:
<SOAP-ENV: Fault> <faultcode> Client/Server </faultcode> <faultstring>Brief Description of Error</faultstring> <detail> <ns:WSHFaultDetails xmlns:ns="www.informatica.com/wsh"> <ErrorCode> Error Code </ ErrorCode > <ExtendedDetails> Actual Error </ ExtendedDetails > </ns:WSHFaultDetails> </detail> </SOAP-ENV: Fault>
23
24
Chapter 4
Overview, 26 Metadata Web Service Operations, 27 Data Integration Web Service Operations, 29
25
Overview
You can schedule, start, or stop existing workflows and tasks using Batch web service operations. You can get session statistics and performance data. You can retrieve workflow and session logs. The Batch web services consist of two groups of services defined in separate WSDLs:
Metadata web services. The operations for the Metadata web services are defined in the Metadata WSDL file available on the Batch Web Services page of the Web Services Hub console. Data Integration web services. The operations for the Metadata web services are defined in the DataIntegration WSDL file available on the Batch Web Services page of the Web Services Hub console.
This chapter explains the operations provided by the Batch web services. For more information about the request and response XML documents for these operations, refer to the WSDL files.
Note: Log segments obtained by Batch web services operation calls are either in Integration
26
All folders in a repository associated with the Web Services Hub All workflows in a folder All worklets and session tasks in a workflow All Integration Services registered for a repository All repositories associated with Web Services Hub
The following section lists all operations available for the Metadata web services.
getAllDIServers
You can associate one or more Integration Services with a repository to run workflows and sessions. In a multiple Integration Service environment, it is important to enter descriptive service names for each associated service to help users differentiate among Integration Services. Each Integration Service associated with a repository must have a service name and a combination of host name and port number that is unique among the services associated with the repository. This operation returns the names of all Integration Services associated with a given repository.
getAllFolders
Use the getAllFolders operation to retrieve all folders in a repository.
getAllRepositories
Use the getAllRepositories operation to view all repositories associated with the Web Services Hub. Before a Web Services Hub client application can use a repository, you must associate the repository with the Web Services Hub. Use the Administration Console to associate a repository with a Web Services Hub. For more information about associating a repository with the Web Services Hub, see Creating and Configuring a Web Services Hub in the PowerCenter Administrator Guide.
Note: Since the getAllRepositories operation is not associated with a specific repository, you
do not need to log in to a repository to use the operation. You can call the getAllRepositories operation without calling the Login operation. For more information about the Login operation, see Login on page 28.
27
getAllTaskInstances
Use the getAllTaskInstances operation to get information about all worklets and session task instances in a workflow for a specified depth.
getAllWorkflows
Use the getAllWorkflows operation to get information about all workflows in a folder. A workflow is a set of instructions that tells the Integration Service how to execute tasks, such as sessions, email notifications, and shell commands. Workflow information includes the name of the workflow, the name of the folder in which the workflow resides, and whether the workflow is valid.
Login
The Login operation authenticates the user name and password for a specified repository. The client application must call this operation before calling any other operations. After calling the Login operation, the web service client application can call any Batch web service operations. The Login operation requires a repository name, user name, and password and returns an encrypted session ID. If the domain for the repository is different from the domain for the Web Services Hub, you must provide the domain name for the repository. Otherwise, the Web Services Hub assumes that the domain for the repository is the same as the domain for the Web Services Hub.
Note: Since the getAllRepositories operation is not associated with a specific repository, you
do not need to log in to a repository to use the operation. You can call the getAllRepositories operation without calling the Login operation. For more information about the getAllRepositories operation, see getAllRepositories on page 27.
Logout
The Logout operation disconnects you from the repository and Integration Service connections. Call this operation at the end of a client application run to release resources in the Web Services Hub.
28
Connect to and get details regarding the Integration Service. You can use the following operations to verify that the Integration Service is running and connect to or get information about the Integration Service:
Schedule and run workflows. You can use the following operations to control how workflows run:
Start and stop tasks in a workflow. You can use the following operations to control the tasks in a workflows:
Monitor and get statistics on sesstions. You can use the following operations to get details on a session or workflow run:
29
startWorkflowLogFetch
This section lists all operations available for the Data Integration web services. These operations are defined in the di.wsdl.
deinitializeDIServerConnection
This operation disconnects the client application from the Integration Service. Use this operation in conjunction with initializeDIServerConnection to manage the connection from the client application to the Integration Service. The Logout operation also releases connections to the Integration Service acquired by the client application and performs cleanup operations.
Note: This operation is equivalent to the disconnect pmcmd command. For more information
about the pmcmd command line program, see the PowerCenter Command Line Reference.
getDIServerProperties
Use this operation to get the properties of the Integration Service. The Integration Service properties include the following information:
Integration Service name Integration Service version Product name Integration Service startup time Name of the repository associated with the Integration Service Data movement mode (ASCII or Unicode) Whether the Integration Service can debug mappings
getNextLogSegment
The getNextLogSegment operation returns a portion of a session or workflow log. You can use this operation if you want to get the information in a session or workflow log in increments. Use this operation with the startSessionLogFetch or startWorkflowLogFetch operation. Call the getNextLogSegment operation with the log handle generated by the startSessionLogFetch or startWorkflowLogFetch operation until the end of log is reached. For more information about the startSessionLogFetch operation, see startSessionLogFetch on page 33. For more information about the startWorkflowLogFetch operation, see startWorkflowLogFetch on page 34. To get session log information in one operation, see getSessionLog on page 31. To get workflow log information in one operation, see getWorkflowLog on page 32.
30
getSessionLog
When a service session runs, the Integration Service writes information to the session log, such as initialization of processes, session validation, creation of SQL commands for reader and writer threads, errors encountered, and load summary. The amount of detail in the session log depends on the tracing level that you set. The getSessionLog operation returns the information in the session log. You can use this operation if you want to get all the information in the session log in one operation. To get session log information in increments, see getNextLogSegment on page 30.
getSessionPerformanceData
Use this operation to retrieve the performance data of a session running on the Integration Service. The performance details provide counters that help you understand the session and mapping efficiency.
Note: Call this operation only for Session tasks.
getSessionStatistics
Use this operation to get the statistics of a session running on the Integration Service. When the session is not running, this operation provides the statistics of the most recently run session. Session statistics includes the folder and workflow name, session and task run status, error information, the number of successful and failed rows for source and target, and the number of applied, affected, and rejected rows.
Note: Call this operation only for Session tasks.
getTaskDetails
Use this operation to retrieve the details of a task from the Integration Service. If the parent workflow is running and the task has already run, the operation returns the details of the current task in the running workflow. If the parent workflow is not running, the operation returns the task details of the last workflow run. The task detail information includes folder and workflow name, task name and type, start time, run status, and run error codes and messages.
getWorkflowDetails
Use this operation to get the details of a given workflow. If the workflow is running, the operation returns the details of the running workflow. If the workflow is not running, the operation returns the details of the last run of this workflow. Workflow details include the name of the folder, workflow, workflow log file, and the user that runs the workflow. It includes workflow run type, log file code page, start and end time, run status, and run error codes and messages.
Data Integration Web Service Operations 31
getWorkflowLog
When the web service workflow runs, the Integration Service writes information to the workflow log, such as initialization of processes, workflow task run information, errors encountered, and workflow run summary. The amount of detail in the workflow log depends on the tracing level. The getWorkflowLog operation returns the information in the workflow log. You can use this operation if you want to get all the information in the workflow log in one operation. To get workflow log information in increments, see getNextLogSegment on page 30.
initializeDIServerConnection
You can use this operation to initialize a connection to an Integration Service. This operation requires the Integration Service name. If the domain for the Integration Service is different from the domain for the repository, you must provide the domain name for the Integration Service. Otherwise, the Web Services Hub uses the same domain for the repository and Integration Service. If you call this operation at the start of the client application run, you do not need to pass the Integration Service name when you call other Data Integration web service operations. If you do not call this operation, you must pass the Integration Service name when you call Data Integration web service operations.
Note: This operation is equivalent to the pmcmd connect command. For more information about the pmcmd command line program, see the PowerCenter Command Line Reference.
monitorDIServer
Use this operation to retrieve the status of the Integration Service, details of active and scheduled workflows, details of the tasks and links within the workflows. You can call this operation in the following modes:
RUNNING. Returns status details for active workflows. Active workflows include running, suspended, and suspending workflows. SCHEDULED. Returns status details for scheduled workflows. ALL. Returns information for all scheduled and active workflows.
pingDIServer
Use this operation to determine whether a Integration Service is running. The return values are ALIVE or FAIL.
32
recoverWorkflow
Recovers suspended workflows. The Integration Service recovers the workflow from all suspended and failed worklets and all suspended and failed Command, Email, and Session tasks.
resumeWorkflow
Deprecated operation. Use the recoverWorkflow operation.
scheduleWorkflow
Use this operation to schedule a workflow. You can schedule any workflow that does not run on demand.
startSessionLogFetch
The startSessionLogFetch generates a log handle for use with the getNextLogSegment operation. After you call the startSessionLogFetch operation, call the getNextLogSegment operation with the log handle generated by startSessionLogFetch until the end of log is reached. For more information about the getNextLogSegment operation, see getNextLogSegment on page 30.
startTask
Use this operation to start a specific task within a workflow.
startWorkflow
Use this operation to start a workflow.
startWorkflowFromTask
Use this operation to stop a workflow from a task. When you start a workflow from a task, the Integration Service runs the workflow from the selected task to the end of the workflow. You must specify the task instance path for the task to be started. The task instance path uniquely identifies a task instance inside a workflow. A task within a workflow is identified by its task name alone. A task within a worklet is identified by its worklet and task names separated by periods: <WorkletName>.<TaskName>. For example, a workflow contains worklet A which contains another worklet, B. Task C is a task within worklet B. The task instance path for task C is A.B.C.
33
startWorkflowLogFetch
The startWorkflowLogFetch generates a log handle for use with the getNextLogSegment operation. After you call the startWorkflowLogFetch operation, call the getNextLogSegment operation with the log handle generated by startWorkflowLogFetch until the end of log is reached. For more information about the getNextLogSegment operation, see getNextLogSegment on page 30.
stopTask
Use this operation to stop a task running on an Integration Service. You can stop or abort a task, workflow, or worklet at any time. When you stop a task in the workflow, the Integration Service stops processing the task and all other tasks in its path. You can also abort a running task by setting the isAbort parameter to true. Normally, you abort tasks only if the Integration Service fails to stop the task. You must specify the task instance path for the task to be aborted. For more information about the task instance path, see startWorkflowFromTask on page 33.
stopWorkflow
Use this operation to stop a running workflow. When you stop a workflow, the Integration Service tries to stop all the tasks that are currently running in the workflow. If the workflow contains a worklet, the Integration Service also tries to stop all the tasks that are currently running in the worklet. In addition to stopping a workflow, you can abort a running workflow by setting the isAbort parameter to true. Normally, you abort workflows only if the Integration Service fails to stop the workflow.
unscheduleWorkflow
Use this operation to unschedule a workflow.
waitTillTaskComplete
Use this operation to wait for a task running on an Integration Service to complete.
waitTillWorkflowComplete
Use this operation to wait for a workflow running on an Integration Service to complete. You can prevent the client from starting the next workflow until the running workflow completes. Otherwise, you can run workflows concurrently.
34
Chapter 5
Overview, 36 Client Applications for Batch Web Services, 37 Writing a Client Application in Java for Batch Web Services, 40 Writing a Client Application in C# for Batch Web Services, 44 Client Applications for Realtime Web Services, 48 Writing a Client Application in Java for Realtime Web Services, 50 Using Parameter Arrays, 53
35
Overview
This chapter provides an overview of how you can write client applications to use the web services offered by the PowerCenter Web Services Provider. The general discussion on the steps to create a client application is followed by examples of how to create client applications in the Java and .NET frameworks. To create a client application for the PowerCenter web services, you need the web service WSDL files and a web service toolkit. Web services toolkits make it easy to create client applications by generating client-side proxy classes from the web service WSDL files. You can use the Microsoft .NET and Apache Axis web services toolkits to write client applications for the PowerCenter web services. You can create a client application to run PowerCenter Batch or Realtime web services. The application development follows the same basic steps.
36
Client proxy classes Initialization Session maintenance Operation calls Resource cleanup Error handling Proxy objects
For more information about writing a client application in Java using the Axis Web Services Toolkit to access the PowerCenter Batch web services, see Writing a Client Application in Java for Batch Web Services on page 40. For more information about writing a client application in C# using the .NET Web Services Toolkit to access the PowerCenter Batch web services, see Writing a Client Application in C# for Batch Web Services on page 44.
Initialization
The client application performs an initialization step before it makes calls to Metadata and Data Integration web services operations.
37
To perform initialization, complete the following steps: 1. Instantiate the proxy class for the Metadata API. In the example, the name of the Metadata API proxy object is MWSProxy. This section uses the name MWSProxy to refer to the Metadata API proxy object. 2. Instantiate the proxy class for the Data Integration API. In the example, the name of the Data Integration API proxy object is DIWSProxy. This section uses the name DIWSProxy to refer to the Data Integration API proxy object. 3. Call the Login operation using the MWSProxy object. The Login operation requires a repository name, user name, and password and returns a session ID. This operation call associates the MWSProxy object with the repository name and user name pair. All subsequent requests made to the Batch web services operations using the MWSProxy object use these repository and user names.
Session Maintenance
The Web Services Hub requires session maintenance to cache resources. The SOAP header in the SOAP message carries the session information facilitating session maintenance. To set up and perform session maintenance, complete the following steps: 1. Extract the header with the root element name Context and namespace http://www.informatica.com/wsh from the response of the Login operation call. This SOAP header contains the session ID sent by the Web Services Hub. Set the SOAP header in the MWSProxy object after the Login operation call. This will send the session ID in the SOAP header for all subsequent requests using the MWSProxy object. Set the SOAP header in the DIWSProxy object with the same session ID so that the same session ID will be sent for all subsequent requests made using the DIWSProxy object.
2.
3.
Operation Calls
You are now ready to call Metadata web service and Data Integration web service operations using the MWSProxy and DIWSProxy objects. Use the MWSProxy object to call Metadata web service operations. Use the DIWSProxy object to call Data Integration web service operations. For more information about using the Metadata web service operations, see Metadata Web Service Operations on page 27. For more information about using the Data Integration web service operations, see Data Integration Web Service Operations on page 29.
38
Resource Cleanup
The Web Services Hub implements session expiry for performance and resource clean up. The Logout operation releases the Web Services Hub resources acquired by client applications and performs cleanup operations. To release resources, call the Logout operation using the MWSProxy object. If you log in to a repository but do not call the Logout operation, the Web Services Hub performs resource cleanup after the session expiration period.
Error Handling
SOAP fault elements in the SOAP response contain the errors that occur during calls to web services. While calling any of the Batch web services operations, the client application should implement the appropriate error handling scheme to retrieve the SOAP fault. This scheme varies according to the toolkit. A web services toolkit provides an exception handling scheme to get the faultcode and faultstring field of a fault element. However, you might need an XML parser to parse the detail element field to obtain the error code and extended details. For more information about error handling schemes used in the Axis Web Services Toolkit, see Error Handling in Axis on page 43. For more information about error handling schemes used in the .NET Web Services Toolkit, see Error Handling in .NET on page 46.
Proxy Objects
The Login operation call creates a session for the repository and user name you provide. The session ID (which corresponds to the Metadata proxy object) that you get from the Login operation call identifies this session. This session (and Metadata proxy object) is valid as long as the session ID is valid. After you call the Logout operation, the session ID becomes invalid along with the corresponding Metadata and Data Integration proxy objects.
39
Services sample programs shipped with the Web Services Hub. You can view the sample programs for the PowerCenter web services in the following directory:
<PowerCenterInstallationDir>/server/samples/BatchWebServices/samples/axis
The -W option turns off support for wrapped document literal services. For example, for WSDL files named Metadata.wsdl and DataIntegration.wsdl, run the following commands:
java org.apache.axis.wsdl.WSDL2Java --NStoPkg http://www.informatica.com/wsh=ProxyClasses -W Metadata.wsdl. java org.apache.axis.wsdl.WSDL2Java --NStoPkg http://www.informatica.com/wsh=ProxyClasses -W DataIntegration.wsdl.
These commands generate the client proxy classes in the folder /ProxyClasses in the ProxyClasses package. The commands generate two proxy classes:
MetadataInterface.java. Contains the interface for the Metadata web services. DataIntegrationInterface.java. Contains the interface for the Data Integration web services.
Initialization in Axis
The client application must perform an initialization step before it makes calls to Metadata web services and Data Integration web services.
40
To perform initialization, complete the following steps: 1. Create MetadataService and DataIntegrationService objects by instantiating the service locator classes:
MetadataService mdService = new MetadataServiceLocator(); DataIntegrationService diService = new DataIntegrationServiceLocator();
2.
Get a MetadataInterface object (MWSProxy) from the MetadataService object created in step 1. If the Metadata service endpoint URL in the Metadata.wsdl has the correct URL, get the MWSProxy object as follows:
MWSProxy=mdService.getMetadata();
MWS_URL is a variable containing the endpoint URL for the Metadata web services. Use the MWSProxy object to call Metadata web service operations. 3. Get a DataIntegrationInterface object (DIWSProxy) from the DataIntegrationService object created in step 1. If the service endpoint URL in the DataIntegration.wsdl has the correct URL, get the DIWSProxy object as follows:
DIWSProxy=diService.getDataIntegration();
DIWS_URL is a variable containing the endpoint URL for the Data Integration web services. Use the DIWSProxy object to call Data Integration web service operations. 4. Call the Login operation with the MWSProxy object to create a session ID for the client application user account. The Login operation takes a domain, repository, user name, and password, wrapped in an object LoginRequest and returns a session ID.
LoginRequest loginReq = new LoginRequest(); loginReq.setRepositoryDomainName(REPO_DOMAIN_NAME); loginReq.setRepositoryName(REPO_NAME); loginReq.setUserName(USER_NAME); loginReq.setPassword(PASSWORD); String sessionID = MWSProxy.login(loginReq);
REPO_DOMAIN_NAME is a string containing a PowerCenter domain name, REPO_NAME is a string containing the name of a repository in the domain, USER_NAME is a string containing a user name valid for the repository, and PASSWORD is a string containing the password for the user to log in to the repository.
41
5.
Associate the MWSProxy and DIWSProxy objects with the repository and user name in the session ID. All subsequent requests made to the Batch web services using the MWSProxy or DIWSProxy object use the repository and user name in the session ID.
((org.apache.axis.client.Stub)MWSProxy).setHeader(createSessionHeader(sessionID)); ((org.apache.axis.client.Stub)DIWSProxy).setHeader(createSessionHeader(sessionID));
2.
Set the SOAP header in the DIWSProxy object with the same SOAP header:
((org.apache.axis.client.Stub)DIWSProxy).setHeader(MWSHeader);
You can call the pingDIServer operation to check the state of an Integration Service:
DIServiceInfo diInfo = new DIServiceInfo(); diInfo.setDomainName(DI_DOMAIN_NAME); diInfo.setServiceName(SERVICE_NAME);
42
DI_DOMAIN_NAME is a variable containing the name of the domain that contains the Integration Service. SERVICE_NAME is a variable containing the Integration Service name.
Clean Up in Axis
Clean up operations release the Web Services Hub resources acquired by client applications. To clean up and release resources, call the Logout operation using the MWSProxy object:
MWSProxy.logout(new VoidRequest());
43
Services sample programs. You can view the sample programs in the following directory:
<PowerCenterInstallationDir>\server\samples\BatchWebServices\samples\dotnet\csharp
2.
For example, for WSDL files named Metadata.wsdl and DataIntegration.wsdl, run the following commands:
wsdl Metadata.wsdl wsdl DataIntegration.wsdl
MetadataService.cs. Contains the interface for the Metadata web services. DataIntegrationService.cs. Contains the interface for the Data Integration web services.
Initialization in .NET
The client application must perform an initialization step before it makes calls to Metadata web services and Data Integration web services. To perform initialization, complete the following steps: 1. Instantiate a MetadataServiceSoapBinding class object (MWSProxy):
MWSProxy= new MetadataServiceSoapBinding();
If the Metadata service endpoint URL in the Metadata.wsdl does not have the correct URL, you can set the URL with the following code:
MWSProxy.Url = MWS_URL;
44
MWS_URL is a variable containing the endpoint URL for the Metadata web services. Use the MWSProxy object to call Metadata web service operations. 2. Instantiate a DataIntegrationServiceSoapBinding class object (DIWSProxy):
DIWSProxy= new DataIntegrationServiceSoapBinding ();
If the Data Integration service endpoint URL in the DataIntegration.wsdl does not have the correct URL, you can set the URL with the following code:
DIWSProxy.Url = DIWS_URL;
DIWS_URL is a string containing the Data Integration web service endpoint URL. Use the DIWSProxy object to call the Data Integration web service operations. 3. Call the Login operation using the MWSProxy object to create a session ID for the client application user account. The Login operation takes a domain, repository, user name, and password, wrapped in an object LoginRequest and returns a session ID.
LoginRequest loginReq = new LoginRequest(); loginReq.RepositoryDomainName = REPO_DOMAIN_NAME; loginReq.RepositoryName = REPO_NAME; loginReq.UserName = USER_NAME; loginReq.Password = PASSWORD; String sessID = MWSProxy.Login(loginReq);
REPO_DOMAIN_NAME is a string containing a PowerCenter domain name, REPO_NAME is a string containing the name of a repository in the domain, USER_NAME is a string containing a user name valid for the repository, and PASSWORD is a string containing the password for the user to log in to the repository. 4. Associate the MWSProxy and DIWSProxy object with the repository and user name in the session ID. All subsequent requests made to the Batch web services using the MWSProxy or DIWSProxy object use the repository and user name in the session ID.
MWSProxy.Context.SessionId = sessID; DIWSProxy.Context.SessionId = sessID;
45
For example, you can call the getAllDIServers operation to get a list of Integration Services:
DIServerInfo[] servers = MWSProxy.GetAllDIServers(null); if (servers != null) { for(int i=0; i < servers.Length ; i++) { Console.WriteLine("("+(i+1)+") "+servers[i].Name); } }
You can call the pingDIServer operation to check the state of an Integration Service:
PingDIServerRequest pingReq = new PingDIServerRequest(); pingReq.TimeOut = (PING_TIME_OUT); DIServiceInfo diInfo1 = new DIServiceInfo(); diInfo1.DomainName = DI_DOMAIN_NAME; diInfo1.ServiceName = DI_SERVICE_NAME1; pingReq.DIServiceInfo = diInfo1; EPingState pingResult = DIWSProxy1.pingDIServer(pingReq);
DI_DOMAIN_NAME is a variable containing the name of the domain that contains the Integration Service. DI_SERVICE_NAME is a variable containing the Integration Service name.
46
XmlElement ErrorCode= WSHFaultDetails [ErrorCode]; XmlElement ExtendedDetails= WSHFaultDetails [ExtendedDetails]; // Display error code Console.WriteLine (error code is : + ErrorCode.InnerText); // Display extended details Console.WriteLine (extended detail is : + ExtendedDetails.InnerText); }
47
Web service workflows Client proxy classes Initialization Operation calls Error handling
For more information about writing Java client applications to access Realtime web services in PowerCenter, see Writing a Client Application in Java for Realtime Web Services on page 50.
Web Service. Enable the Web Service option to turn a workflow into a web service workflow. Runnable. Enable the Runnable option to allow a client application to run the web service workflow. Visible. Enable the Visible option so that the Web Services Hub publishes the WSDL for the web service in the Web Services Hub console.
Initialization
The client application must instantiate the web service object in the client proxy classes and get the port for the web service before the application can make calls to the web service operations.
48 Chapter 5: Writing Client Applications
Operation Calls
To invoke a web service operation, the client application must create a request object and pass it to the port operation. When the web service sends back a response, the client application must handle the response as needed.
Error Handling
Error handling in a Realtime web services client application is the same as in a Batch Web Services client application. SOAP fault elements in the SOAP response contain the errors that occur during calls to web services. The client application should implement the appropriate error handling scheme to retrieve the SOAP fault.
49
Before you create the client application that calls a PowerCenter web service workflow, you must first create the web service workflow and generate the WSDL for the web service. You then create the client application based on the web service WSDL. To create a PowerCenter web service and generate the WSDL, complete the following steps: 1. Create a mapping for the web service workflow. You can create a mapping to receive a message from a web service client, transform the data, and send the response back to the web service client or write it to any target that PowerCenter supports. For more information about creating a PowerCenter mapping to use in a web service, see Working with Mappings on page 57. Create a workflow and enable it as a web service. Create a workflow to run the mapping and enable the Web Services option in the workflow properties. Select the Runnable option so that client applications outside of PowerCenter can run the workflow. For more information about creating and configuring a web service workflow, see Working With Web Service Workflows on page 77. Locate and download the WSDL for the web service workflow. When you create the web service workflow, PowerCenter generates a WSDL for the web service. If you configure the web service to be visible, you can view the WSDL on the console of the Web Services Hub associated with the web service. For more information about configuring the web service workflow, see Configuring the Web Service Workflow on page 80.
2.
3.
After you create the web service, you can develop a client application to run the web service workflow. To create a client application that calls Realtime web services, complete the following steps: 1. Generate the client proxy classes for the web service. After you create the proxy classes, create the Java application to call the web service. Perform the next steps within the Java application. 2. 3. 4. Initialize the web service objects. Create the request object. Pass the request object to the port operation and handle the response.
50
Note: The sample code snippets in the following sections are taken from the Realtime web
services sample program for multiple row lookup. You can view the example in the following directory:
<PowerCenterInstallationDir>/server/samples/RealtimeWebServices/samples /axis/CustomerLookup_MULTIPLEROW
For example, for a WSDL file named SampleWS.wsdl, run the following command:
java org.apache.axis.wsdl.WSDL2Java -W SampleWS.wsdl
The -W option turns off support for wrapped document literal services. WSDL2Java generates a class for each data type defined in the WSDL. By default, WSDL2Java generates package names based on the namespaces in the WSDL. Typically, if the namespace is of the form http://x.y.com or urn:x.y.com, the corresponding package will be com.y.x.
To get the port for the web service, use the proxy class created for the port type. In the sample program, the following code gets the port for the web service:
CustomerLookup_MULTIPLEROWPort port = service.getCustomerLookup_MULTIPLEROWPort());
51
52
<complexType name="ParameterArray"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="Parameters" nillable="true" type="impl:Parameter" /> </sequence> </complexType>
[WSH_Folder.s_m_B] $d=4
The SOAP request for a web service call to the StartWorkflow operation with the same parameters in a parameter array would include the following elements:
<StartWorkflow> <Parameters> <Parameter> <Scope>s_m_A</Scope> <Name>$a</Name> <Value>1</Value> </Parameter> <Parameter> <Scope>s_m_A</Scope> <Name>$b</Name> <Value>2</Value> </Parameter> <Parameter> <Scope>s_m_A</Scope> <Name>$c</Name> <Value>3</Value> </Parameter> <Parameter> <Scope>WSH_Folder.s_m_B</Scope> <Name>$d</Name> <Value>4</Value> </Parameter> </StartWorkflow>
The WorkflowRequest and TaskRequest types contain ParameterArray elements. You can specify any number of parameters in a parameter array. The following sample code from a web service client application in Axis shows how to create the parameter array in a WorkflowRequest:
Parameter[] parameters = new Parameter[4];
54
55
Use a parameter file OR a parameter array. Do not specify a parameter file name and a parameter array in the a SOAP request when you make a web service operation call. If you specify both a parameter file and parameter array in the SOAP request, the Web Services Hub returns the following fault:
ERROR: Error: Both parameter list and parameter file are specified.
The parameter array in a SOAP request overrides any parameter file defined in the properties of a task or workflow. If you specify a parameter array in a web service request to start a workflow and the workflow has an associated parameter file defined in the workflow properties, the Integration Service uses the parameter array in the web service request when it runs the workflow.
56
Chapter 6
Overview, 58 Importing Web Service Source and Target Definitions, 59 Viewing and Editing Web Service Definitions, 66 Working with Web Service Mappings, 72 Attachments, 75
57
Overview
Before you can define a web service workflow in the Workflow Manager, use the Designer to complete the following tasks:
Import definitions. Import operations from a WSDL file to create web service source and target definitions. When you import a source, the Designer imports the input message. When you import a target, the Designer imports output and fault messages. The Designer creates multiple groups in a definition based on the XML hierarchy of the file. View and edit definitions. Most properties of a web service definition are read-only. You can edit properties such as description, metadata extensions, and precision for String and Binary datatypes. You can edit the definition in the Designer workspace. You can view the groups and relationships in the XML Editor. Create mappings. You can create a mapping to receive a message from a web service client, transform the data, and send the response back to the web service client or write it to any target PowerCenter supports. Based on the source and target definitions, PowerCenter can receive and send attachments as part of the SOAP request. You can also create a mapping using flat file or XML sources and targets and use it in a web service workflow. This allows you receive message data through a SOAP call by attachment instead of reading it from a file.
58
When you import a WSDL file in the Source Analyzer, the Designer imports the input message of an operation. This represents the metadata for a web service SOAP request. When you import a WSDL file in the Target Designer, the Designer imports output message of an operation. This represents the metadata for a web service SOAP response. You can import definitions that contain MIME attachments. If the Designer detects an attachment, it creates an attachment group in definition.
Note: You can import definitions from a WSDL file with document/literal encoding.
59
When you import a web service source definition, the Designer creates ports in the message header that are not part of the XML hierarchy. When you run a web service workflow, the Web Services Hub uses this information to identify the web service client and generate a message ID. Table 6-2 describes the message header ports in a web service definition:
Table 6-2. Message Header Ports
Port Name PK_Message MessageID ClientID ClientIP Description Generated primary key for the root group. Web Services Hub generates the message ID when it receives a request. It uses this ID to correlate the incoming request with the outgoing response. User ID of the web service client. TCP/IP address of the web service client.
For information about importing web service source definitions, see Steps for Importing Web Service Sources and Targets on page 61.
60
Note: When the Designer imports a web service target definition, it names the definition based
on the operation and the target type, such as output or target. If you rename the definition, you can verify the target type on the Metadata Extensions tab. For information about importing web service target definitions, see Steps for Importing Web Service Sources and Targets on page 61.
Create entity relationships. Use this option to create views for multiple-occurring or referenced elements and complex types. You create relationships between views instead of creating one large hierarchy. For more information about entity relationships, see the PowerCenter XML Guide. Create hierarchical relationships. This is the default option for importing WSDLs. Use this option to create a root and expand the XML components under the root. If you choose to create a hierarchical relationship, then you create a normalized view. In a normalized view, every element or attribute appears once. One-to-many relationships become separate XML views with keys to relate the views. For more information about hierarchical relationships, see the PowerCenter XML Guide.
61
From the Source Analyzer, click Sources > Import from WSDL (Provider). - or From the Target Designer, click Targets > Import from WSDL (Provider).
Select a URL.
Click Advanced Options to configure the default precision for String datatype fields.
62
Table 6-3 describes the options you can configure when you choose Advanced Options.
Table 6-3. Advanced Options for Importing Web Service Definitions
Option Override all infinite lengths Generate names for XML columns Description You can specify a default length for fields with undefined lengths, such as strings. You can choose to name XML columns with a sequence of numbers or with the element or attribute name from the schema. If you use names, choose from the following options: - When the XMLColumn refers to an attribute, prefix it with the element name. PowerCenter uses the following format for the name of the XML column:
NameOfElement_NameOfAttribute
- Prefix the XML view name for every XML column. PowerCenter uses the following format for the name of the XML column:
NameOfView_NameOfElement
- Prefix the XML view name for every foreign-key column. PowerCenter uses the following format for the name of a generated foreign key column:
FK_NameOfView_NameOfParentView_NameOfPKColumn
Maximum length for a column name is 80 characters. PowerCenter truncates column names longer than 80 characters. If a column name is not unique, PowerCenter adds a numeric suffix to keep the name unique. 3.
Select whether to import from a local file or a URL. If you choose to import from a URL, select a URL from the Address list and click Open. If you choose to import from a local file, select a file and click Open.
63
4.
5.
Click Next. The Web Services Definition Creation Options dialog box appears.
64
6.
Choose to generate XML views as entity relationships or as hierarchy relationships. Hierarchy relationships with normalized XML views is the default option.
7.
65
Table. On the Table tab, you can provide the owner name and description, and you can change the name of the definition. You cannot change the table type. Columns. On the Columns tab, you can edit the precision for String datatypes. You can also add business names and column descriptions. Attributes. On the Attributes tab, you can view attribute values for each column in a source or target definition. Metadata Extensions. On the Metadata Extensions tab, you can view the Web Services Domain metadata extensions. You can also add metadata extensions in the User Defined Metadata Domain.
Columns Tab
The Columns tab displays column information, such as port name, datatype, precision, and scale. You can edit precision for String and Binary datatypes, and you can add business names and column descriptions. You can set the precision for String datatypes when you import the source or target. When you set the precision, the Designer uses the new value the next time you import a definition. You can also modify the precision of individual columns after you import a definition.
Note: The Mapping Designer invalidates mappings that use source and target web service
definitions with a total column length greater than 500 MB. For more information about modifying the precision when you import a definition, see Steps for Importing Web Service Sources and Targets on page 61.
66
Figure 6-3 shows the Columns tab for a web service source definition:
Figure 6-3. Columns Tab for a Web Service Definition
67
Attributes Tab
The Attributes tab is a read-only tab that displays the XPath and XMLDataType values for each field in a source or target definition. If the definition has an Attachment group, the Attributes tab displays the MIME type in the data field. Figure 6-4 shows the Attributes tab for a web service target definition:
Figure 6-4. Attributes Tab for a Web Service Definition
68
69
Figure 6-6 shows the XML Editor view of the source definition shown in Figure 6-1 on page 59:
Figure 6-6. XML Editor Views of Web Service Definition
All input. When you set the load scope to all input, the Integration Service generates a response after it receives all incoming data. Different groups in the target can receive data from different transaction generators. The Integration Service ignores commits when the load scope is all input. Transaction. When you set the load scope to transaction, the Integration Service generates a response when it receives all data in the transaction. All groups in the target must receive data from the same transaction generator.
70
You must set the load scope to transaction if you enable real-time flush and set the realtime flush latency to a value greater than zero. For more information about transformation scope, see Understanding Commit Points in the Workflow Administration Guide.
71
Request-response service. A request-response service receives an incoming request from the web service client, transforms the data, and sends the response back to the web service client. A request-response service uses both a web service source and a web service target. When you create mappings for a request-response service, you must propagate the message ID from the source to the target. You can create one mapping or multiple mappings to process a request-response service.
One mapping. Create one mapping that contains both the web service source and web service target definitions. You receive an incoming request, transform the data, and send the response back in a single session. Multiple mappings. Create multiple mappings if you need to stage data before sending a response back to the web service client. You can create a workflow that contains a session for each mapping.
One-way service. If you receive updates and notifications from a web service client, but do not need to send back a response, you can create a one-way mapping. A one-way mapping uses a web service client for the source. The Integration Service loads data to a target, often triggered by a real-time event through a web service request. When you create a one-way mapping, you do not need to propagate the message ID to the target.
The web service source and target definitions you include in the mapping depend on the type of mapping you create. Table 6-4 describes the web service source and target definitions you use based on the mapping type:
Table 6-4. Required Sources and Targets in a Service
Service Type Request-Response One-way Web Service Source Must have one instance of one web service source definition. Must have one instance of one web service source definition. Web Service Target Can have multiple instances of one target output definition. Can have multiple target fault definitions. Contains no web service target definition.
Note: You can also create mappings with flat file or XML source or targets and run them in
web service workflows. For more information, see Running Sessions and Web Service Workflows on page 90.
72
Request-Response Mappings
A request-response mapping uses a web service source and target. When you create a requestresponse mapping, use source and target definitions imported from the same WSDL file. When you create a request-response mapping, you must propagate the message ID to the target. For example, an organization has an online order service. When a customer places an order, you want to store all order information in a log and pass confirmation and order totals back to the customer. Figure 6-7 shows a sample request-response mapping:
Figure 6-7. Request-Response Mapping
Note: When you create request-response mappings, use source and target definitions imported
from the same WSDL file. If you do not import source and target definitions from the same WSDL file, you might get unexpected results. You can use an SQL transformation to update a database or to retrieve multiple database rows midstream in a request-response mapping. The SQL transformation can return multiple database rows to the target. When database errors occur in processing, the SQL transformation receives the errors from the database and outputs the error text to the target. For more information about the SQL transformation, see SQL Transformation in the PowerCenterTransformation Guide.
Staged Mappings
If you want to run a request-response session, but you need to stage the data first, you can create multiple mappings to process the data. For example, you receive message data that you need to process. You must make an asynchronous call to an external system through IBM MQSeries. You create the following mappings: 1. 2. Create a request mapping with a web service source definition. This mapping has a flat file target and an MQSeries target. You write all message data to both targets. An external application receives messages from the MQSeries target, processes them, and sends messages to another MQSeries queue.
73
3.
Create a response mapping with a web service target definition. This mapping uses the flat file target as a source. It also uses the MQSeries queue with the processed data as a source. You can join the MQSeries source with the flat file source to propagate the message ID to the web service target.
74
Attachments
The Web Services Provider supports attachments in web service client messages.
Change the reader to Web Services Provider Reader for Flat File.
Attachments
75
For example, you can extract an XML document from an Oracle database and pass it to a web service client as an attachment to a response message. Or, you might set up a client application to allow web service clients to send PDF attachments in a request. Table 6-5 describes the attachment group ports in a web service definition:
Table 6-5. Attachment Group Ports
Port Name FK_Att_Name Att_Data_Name Att_Index_Name Att_Type_Name Description Generated foreign key pointing to PK_Message in the root group. Contains the attachment. You can view the MIME type for the attachment on the Attributes tab. Unique identifier for each attachment in the message. Type of attachment.
Use the following rules and guidelines when you work with attachments:
A request or response can contain zero or more attachments. If you want to pass attachments through requests or responses, you must connect all ports in the attachment group. If a definition in the mapping contains an attachment group, but you do not want to send or receive attachments, connect none of the ports in the group. If you receive more than one attachment in a request, you must propagate the index to the target if you pass the attached request to the response. If you do not pass the attached request to the response, you do not need to propagate the index to the target. If you receive messages from other sources, and each message contains the same number of attachments, use a Sequence Generator transformation to generate a unique index for each attachment you send in a response. To send or receive attachments, you must create a client application using a toolkit that supports MIME attachments.
76
Chapter 7
Overview, 78 Creating and Configuring a Web Service Workflow, 79 Creating and Configuring a Service Session, 82 Running Sessions and Web Service Workflows, 90 Troubleshooting, 92
77
Overview
You configure web service workflows in the Workflow Manager. To create a web service workflow, you must enable it for web services. You configure the service within the workflow properties. For more information about creating web service workflows, see Creating and Configuring a Web Service Workflow on page 79. When you create a session to add to the workflow, use a mapping that contains web service, flat file, or XML sources or targets. If you use a flat file or XML source or target, you change the reader or writer type. For more information about creating sessions, see Creating and Configuring a Service Session on page 82. For more information about running sessions, see Running Sessions and Web Service Workflows on page 90.
Note: Before you can run a web service workflow, you must create and configure a Web
Services Hub on the Administration Console and associate it with a repository. For more information, see Creating and Configuring a Web Services Hub in the PowerCenter Administrator Guide.
78
79
Table 7-1 describes the properties you can configure for a web service:
Table 7-1. Web Service Properties
Option Service Name Description Name of the web service. The Web Services Hub publishes this name when you check in the workflow and the service is visible. The default name is a concatenation of the repository name, folder name, and workflow name. This name must be unique. Maximum number of seconds between the time the Web Services Hub receives a SOAP request and generates a SOAP response. If the Web Services Hub is unable to generate a response, the request fails. Set this to a value greater than the real-time flush latency in the reader properties. Set to 0 to disable the timeout period. Default is 60 seconds. For more information about timeout and flush latency, see Understanding Service Timeout and Flush Latency on page 90. Limits the service to repository users. You can choose to protect the service or make it public. When you protect the service, the web service client must log in to the repository through the Web Services Hub before it can start the service. The Web Services Hub authenticates the user based on the PowerCenter repository user name and password. The user must have execute permissions on the folder containing the workflow. Any PowerCenter user who can run a workflow can run a protected web service workflow using the Workflow Manager, pmcmd, or LMAPI. If you do not protect the service, any web service client can start the service without authentication. For more information about authentication, see Web Services Hub Security on page 20.
Timeout
Protected
80
Runnable
81
Web Services Provider reader. When you configure the reader for a service session, you configure terminating conditions, such as idle time and message count. For more information about configuring the reader, see Configuring the Web Services Provider Reader on page 82. Web Services Provider writer. When you configure the writer for a service session, you configure caching information that the Integration Service uses to cache target data. You can also configure the output format for the target data. For more information about configuring the writer, see Configuring the Web Services Provider Writer on page 85. Recovery. When you enable recovery, the Integration Service stores messages in the cache directory. For more information about message recovery, see Recovering Messages on page 87. Commit type. Configure real-time sessions for a source-based commit. For more information about commit behavior, see Configuring Commit Type on page 88. Partitioning. You can configure partitioning properties based on the source and target type in the mapping. For more information about partitioning, see Configuring Partitions on page 88.
82
Figure 7-3 shows the properties you configure for the Web Services Provider reader:
Figure 7-3. Web Services Provider Reader Properties
Table 7-2 describes the properties you configure for the different Web Services Provider readers:
Table 7-2. Web Services Provider Reader Properties
Property Idle Time* Source Type - Web Service - Web Services Provider Reader Flat File - Web Services Provider Reader XML File - Web Service - Web Services Provider Reader Flat File - Web Services Provider Reader XML File Description Amount of time in seconds the Integration Service waits to receive messages before it stops reading from the source and ends the session. Default is -1 and indicates an infinite period of time. The number of messages the Integration Service reads before it ends the session. If the session uses flat file or XML sources, always configure the message count to 1. A value of -1 indicates an infinite number of messages. For more information, see Running Sessions and Web Service Workflows on page 90. Default is 1.
Message Count*
83
Web Service
- Web Service - Web Services Provider Reader Flat File - Web Services Provider Reader XML File Web Services Provider Reader XML File
The session fails if a pipeline contains a Transaction Control transformation. The session fails if a pipeline contains any transformation with Generate Transactions enabled. The session fails if a pipeline contains any transformation with the transformation scope set to all input. The session fails if the load scope is set to all input. Configure the flush latency greater than the service timeout. The session fails if a pipeline contains any transformation that has row transformation scope and receives input from multiple transaction control points. The Integration Service ignores flush latency when you run a session in debug mode. If the mapping contains a relational target, configure the Target Load Type to be Normal.
85
Table 7-3 describes the properties you configure for a Web Services Provider writer:
Table 7-3. Web Services Provider Writer Properties
Property XML DateTime Format Target Type Web Services Provider Writer XML File Description Datetime format for the data passed to the service target. Select from the following datetime formats: - Local Time. The time according to the Integration Service server time zone. - Local Time with Time Zone. The difference in hours between the Integration Service time zone and Greenwich Mean Time. - UTC. Greenwich Mean Time. Determines how null content is represented in the target. Select from the following options: - No Tag. Do not output a tag. - Tag with Empty Content. Output just the tag. Default is No Tag. Determines how an empty string is represented in the target. Select from the following options: - No Tag. Do not output a tag. - Tag with Empty Content. Output just the tag. Default is Tag with Empty Content. Determines how the Integration Service handles duplicate group rows during a session. Select from the following options: - First Row. The Integration Service passes the first duplicate row to the target. The Integration Service rejects rows with the same primary key that it processes after this row. - Last Row. The Integration Service passes the last duplicate row to the target. - Error. The Integration Service passes the first row to the target. Rows that follow with duplicate primary keys increment the error count. The session fails when the error count exceeds the error threshold. Default is Error. Determines how the Integration Service handles orphan rows during a session. Select from the following options: - Ignore. The Integration Service ignores orphan rows. - Error. The session fails when the error count exceeds the error threshold. Total size in bytes for the memory cache used by writer. Default is 10,000,000 bytes.
Cache Size
- Web Service - Web Services Provider Writer XML File - Web Service - Web Services Provider Writer XML File
Cache Directory
Directory for the target cache files. Default is the $PMCacheDir server variable.
86
Use the following rules and guidelines when you change the writer type to a Web Services Provider writer:
When you change the writer type for a flat file target, the Integration Service does not cache the target messages. When you change the writer type for a flat file or an XML target, use the target as a web service output message, but not as a fault message. When you change the writer type for an XML target, you still configure XML writer properties. For more information about XML writer properties, see the PowerCenter XML Guide.
To send or receive attachments you must create a client application using a toolkit that supports MIME attachments.
Recovering Messages
When you enable recovery, you can recover read messages from a failed session. The Integration Service stores all read messages in a cache before processing the messages for the target. If the session fails, you can recover the messages that the Integration Service could not process. The Integration Service reads and processes the messages from the cache. It does not continue to receive messages from the Web Services Hub. The Integration Service removes messages from the message cache files after the flush latency period expires. It empties the cache files at the end of the session.
87
Note: The Integration Service ignores the reader time limit, idle time, and message count
when it reads messages from the cache. For more information about recovery, see the PowerCenter Workflow Administration Guide.
Configuring Partitions
When you set up multiple partitions in a session that contains web service source and target definitions, the Integration Service creates a connection to the Web Services Hub based on the number of sources, targets, and partitions in the session. For example, if you configure three partitions in a session that contains one source and one target, the Integration Service creates six connections to the Web Services Hub, three for each source and target. When you run a multi-partitioned session, the Web Services Hub uses a source connection to pass a request to the Integration Service. The Integration Service uses a target connection to send a response to the Web Services Hub. The Web Services Hub and the Integration Service use the source and target connections in a round-robin fashion.
88
When you configure partitions for a service mapping, you can configure pass-through partitioning for web service sources and targets. For information about configuring partitioning for XML sources or targets or flat file sources or targets, see the PowerCenter Workflow Administration Guide.
89
Configure the message count to 1 in the reader properties. Include one session in a workflow when you change the reader or writer type to Web Services Provider. When you change the reader or writer type in the session properties, you must create a client application using a toolkit that supports MIME attachments.
90
If the Integration Service sends a response message to the Web Services Hub after the timeout period, the Web Services Hub drops the response and writes the following message to the Web Services Hub log:
WSH_95571 Unable to find invocation for message id <message ID>. Discarding the response.
The following situations describe some session configurations that can result in dropped response messages:
You configure flush latency to be greater than the service timeout period. For example, you set flush latency to 90 and the service timeout to 60. The Web Services Hub reaches the timeout period and drops the connection to the web service client before the Integration Service flushes any response message to the Web Services Hub.
You disable flush latency and configure terminating conditions to infinite values. For example, if you disable flush latency, the Integration Service sends a response message to the Web Services Hub when the session reaches one of the terminating conditions or when the reader buffer fills. If you set the terminating conditions to infinite values, the session runs continuously and never ends. The Integration Service sends response messages when the buffer fills. If the Web Services Hub reaches the timeout period before the reader buffer fills, it drops the connection to the web service client and cannot send response messages received from the Integration Service.
You disable flush latency and use message count as the terminating condition. For example, you want the session to end after the Integration Service processes 10 messages. You set the message count to 10, and you disable flush latency to flush all the messages at the end of the session. If the Integration Service does not process all 10 messages in the service timeout period, the Web Services Hub drops the connection to the web service client and cannot send response messages received from the Integration Service.
To help ensure that the Web Services Hub does not reach the timeout period, set the flush latency value to less than the service timeout.
91
Troubleshooting
I am trying to run the Debugger against a service session, but the session fails, and I get the following message in the session log:
WSP_34030 Must have workflow context to run this session.
If you want to debug a service session, you must run the Debugger against the web service workflow. You cannot run the Debugger against a service mapping or a reusable session without the workflow. I updated the source WSDL file and reimported my source and target definitions. The workflow is valid, but the service WSDL is not updated. Changes to a mapping are not dynamically reflected in the Web Services Hub. To generate WSDL to reflect the mapping changes, you need to edit and save the workflow. When you save the workflow, the Web Services Hub generates WSDL to run the service. My web service workflow was valid in the Workflow Manager, but became invalid when I started the Web Services Hub. After you start the Web Services Hub, it validates each web service workflow according to its own validation rules in addition to those of the Workflow Manager. The Web Services Hub validates web service workflows according to the following rules:
There can be only one web service source definition in the mapping. There can be no more than one web service target definition in the mapping. If there are no web service target definitions in the mapping, the Web Services Hub treats the service as a one-way service. A repository must be associated with the Web Services Hub. A server must be associated with the workflow.
See the Validate tab in the Workflow Manager for Web Services Hub error messages, and correct the problem indicated by the error message. I am not able to start a protected web service workflow even though I am sending the proper repository name, user name, and password. When you invoke a protected web service workflow, you must ensure that the repository user name and password is correctly set in the HTTP header. For more information, see Web Services Hub Security on page 20.
92
I received the following error while trying to fetch a workflow on a Web Services Hub:
ERROR Thu Mar 23 08:45:51 2006 http-52962-Processor4 [WSH_501] Service Workflow [wf_amazon_actor_search] in Repository [zeus_RS1_sun920] and Folder [WSTest] is invalid. This workflow cannot be accessed using WSH. ERROR Thu Mar 23 08:45:50 2006 http-52962-Processor4 [WSH_735] DI Service is not specified for workflow [wf_amazon_actor_search].
You must assign an Integration Service when you create a web service workflow. See Creating a Web Service Workflow on page 79.
Troubleshooting
93
94
Appendix A
Overview, 96 Using the Batch Web Services Sample Programs, 97 Examples for Batch Web Services, 99 Using the Realtime Web Services Sample Programs, 106 Examples for Realtime Web Services, 109
95
Overview
Informatica ships sample client application programs that demonstrate how to use PowerCenter web services. The examples include programs in Java and C#. The Java sample programs use proxy classes generated by the Axis Web Services Toolkit. The C# sample programs use proxy classes generated for the .NET platform with the wsdl.exe tool. The sample programs work with the PowerCenter Batch web services and Realtime web services. The web services sample programs are installed in the following directory:
/<PowerCenterInstallDir>/server/samples/
Before running the web services sample programs, create and enable a Web Services Hub on the PowerCenter domain. Use the PowerCenter Administration Console to create, configure, and enable a Web Services Hub. For more information about creating, configuring, or enabling a Web Services Hub, see the PowerCenter Administrator Guide.
96
/samples/axis/proxyclasses /samples/dotnet/csharp/<SampleProgramDirectory>
/samples/dotnet/csharp/proxyclasses
97
98
C#:
/WebServices/BatchWebServices/samples/dotnet/csharp/<SampleProgramDirectory>
The same set of sample programs are shipped for Java and C#. Each platform has the same directories and each directory contains sample programs that demonstrate a different usage for web services. This section describes the Java and C# sample programs.
Browsing
The sample programs in the /browsing directory demonstrate the use of web services operations that get information from the repository.
Host name Port number Repository domain name Repository name User Name Password
99
Host name Port number Repository domain name Repository name User Name Password Integration Service domain name Integration Service name
Data Integration
The sample program in the /dataintegration directory demonstrates the use of the workflow and task operations available in the Data Integration web services.
100
The following table describes the parameters you use to run the Sample1 application:
Parameter Security mode Description Indicates the security mode in which to run the application. Pass the argument -ns to run the application in unsecure mode (HTTP). The examples do not support secure mode (HTTPS). Name or IP address of the machine on which the Web Services Hub is running. Port number on which the Web Services Hub is running. Name of the domain that contains the Repository Service. Name of the Repository Service. User name to log in to the repository. Password for the user name to log in to the repository. Name of the domain that contains the Integration Service. Name of the Integration Service. Name of a folder in the repository. Name of the workflow that contains the session. Name of the task to start.
Host name Port number Repository domain name Repository name User Name Password Integration Service domain name Integration Service name Folder Name Workflow name Task name
Logs
The sample program in the /logfetching directory demonstrates the use of Data Integration web services operations to access the workflow and session logs.
101
The following table describes the parameters you use to run the Sample1 application:
Parameter Security mode Description Indicates the security mode in which to run the application. Pass the argument -ns to run the application in unsecure mode (HTTP). The examples do not support secure mode (HTTPS). Name or IP address of the machine on which the Web Services Hub is running. Port number on which the Web Services Hub is running. Name of the domain that contains the Repository Service. Name of the Repository Service. User name to log in to the repository. Password for the user name to log in to the repository. Name of the domain that contains the Integration Service. Name of the Integration Service. Name of the folder in the repository that contains the workflow. Name of the workflow that contains the task. Name of a task in the workflow.
Host name Port number Repository domain name Repository name User Name Password Integration Service domain name Integration Service name Folder Name Workflow name Task name
services to log in to two Integration Services. Create one proxy object for each Integration Service that you want to log in to. Directory: /multiservers File to compile Java and C# samples: CompileSample1.bat or CompileSample1.sh File to run Java sample: RunSample1.bat or RunSample1.sh File to run C# sample: Sample1.exe
102
The following table describes the parameters you use to run the Sample1 application:
Parameter Security mode Description Indicates the security mode in which to run the application. Pass the argument -ns to run the application in unsecure mode (HTTP). The examples do not support secure mode (HTTPS). Name or IP address of the machine on which the Web Services Hub is running. Port number on which the Web Services Hub is running. Name of the domain that contains the Repository Service. Name of the Repository Service. User name to log in to the repository. Password for the user name to log in to the repository. Name of the domain that contains the Integration Service. Name of the an Integration Service associated with the repository. Name of a second Integration Service associated with the repository.
Host name Port number Repository domain name Repository name User Name Password Integration Service domain name Integration Service name 1 Integration Service name 2
Multithreading
The sample program in the /multithreaded directory demonstrates the use of proxy objects in multiple threads to perform operations in parallel. You can use the same technique to enable a client application to continue running and calling other operations as it waits for an operation to complete. For example, if a client application calls the WaitTillWorkflowComplete operation on thread, the application can continue to perform other operations on other threads.
103
The following table describes the parameters you use to run the Sample1 application:
Parameter Security mode Description Indicates the security mode in which to run the application. Pass the argument -ns to run the application in unsecure mode (HTTP). The examples do not support secure mode (HTTPS). Name or IP address of the machine on which the Web Services Hub is running. Port number on which the Web Services Hub is running. Name of the domain that contains the Repository Service. Name of the Repository Service. User name to log in to the repository. Password for the user name to log in to the repository. Name of the domain that contains the Integration Service. Name of the Integration Service. Name of the folder in the repository that contains the workflow. Name of a workflow in the repository.
Host name Port number Repository domain name Repository name User Name Password Integration Service domain name Integration Service name Folder Name Workflow name
104
The following table describes the parameters you use to run the Sample1 application:
Parameter Security mode Description Indicates the security mode in which to run the application. Pass the argument -ns to run the application in unsecure mode (HTTP). The examples do not support secure mode (HTTPS). Name or IP address of the machine on which the Web Services Hub is running. Port number on which the Web Services Hub is running. Name of the domain that contains the Repository Service. Name of the Repository Service. User name to log in to the repository. Password for the user name to log in to the repository. Name of the domain that contains the Integration Service. Name of the Integration Service.
Host name Port number Repository domain name Repository name User Name Password Integration Service domain name Integration Service name
105
The Realtime web services examples include the files to create the lookup tables and web service workflows to be used by the sample programs. The /RealTimeWebServices directory contains the following files and directories:
Directory /ImportXML Description Contains the web service workflows called by the Realtime web services sample programs. To use the sample programs, import the XML files into a repository and set up the database connections for the SQL and Lookup transformations in the web service workflows. Contains the library files needed to run the sample programs. Contains the SQL scripts for creating the lookup tables used by the web service workflows called by the sample programs. Run the SQL scripts to create tables in an Oracle database. Contains the Java sample programs. The source file for each Realtime web services sample program can be found in a separate directory. Each directory contains the batch and script files to compile and run the sample program and subfolders for the proxy classes used by the sample program.
/lib /LookupSQL
/samples/axis/<SampleProgramDirectory>
To use the Realtime web services examples, you must complete the following steps: 1. 2. 3. 4. 5. Create the database tables that the sample programs will use as lookup tables. Import the mappings and web service workflows into the repository associated with the Web Services Hub. Set up the database connection settings in the sample workflows. Compile the Realtime web services sample programs. Run the Realtime web services sample programs.
106
Note the database connection settings. After you import the sample workflows into a repository, you need to modify the database connection settings of the transformations in the workflows to match your database settings.
For more information about importing metadata objects into a repository, see the PowerCenter Repository Guide.
Set the relational connection to the name of the new connection object. Save the session with the new settings. 3. In the PowerCenter Workflow Manager, edit the s_m_CustomerLookup_MULTIPLEROW session and update the connection information in the sql_Customer transformation. Set the relational connection to the name of your connection object. Save the session with the new settings.
108
Sample.java
This sample program calls a PowerCenter web service workflow that looks up a customer ID in a database and prints out the customer information. The workflow uses an SQL transformation to retrieve multiple rows from the database. Directory: /CustomerLookup_MULTIPLEROW File to compile Java sample: CompileSample.bat or CompileSample.sh File to run Java sample: RunSample.bat or RunSample.sh The following table describes the parameters you use to run the Sample application:
Parameter Customer ID EndPoint URL Description ID for the customer to look up. Pass the customer ID as an integer. URL where the web service can be found. Pass the endpoint URL as a string. The endpoint URL for a realtime web service can be found in the soap:address location element of the service element in the web service WSDL. The default endpoint URL for the sample web service is http://<WSHHostName>:<WSHPort>/wsh/services/ts/CustomerLookup_MULTIPLEROW. If the Web Services Hub is running on HTTPS, the endpoint URL starts with HTTPS.
Sample.java
This sample program calls a PowerCenter web service workflow that looks up a customer ID in a database and prints out the customer information. The mapping uses a Lookup transformation to retrieve one row from the database. Directory: /CustomerLookup_SINGLEROW File to compile Java samples: CompileSample.bat or CompileSample.sh File to run Java sample: RunSample.bat or RunSample.sh
Examples for Realtime Web Services 109
The following table describes the parameters you use to run the Sample application:
Parameter Customer ID EndPoint URL Description ID for the customer to look up. Pass the customer ID as an integer. URL where the web service can be found. Pass the endpoint URL as a string. The endpoint URL for a realtime web service can be found in the soap:address location element of the service element in the Web service WSDL. The default endpoint URL for the sample web service is http://<WSHHostName>:<WSHPort>/wsh/services/ts/CustomerLookup_SINGLEROW. If the Web Services Hub is running on HTTPS, the endpoint URL starts with HTTPS.
110
Appendix B
Overview, 112 Metadata Web Services, 113 Data Integration Web Services, 114
111
Overview
Effective in version 8.1.1, the Web Services Hub supports the web service operations available in version 7.1.4. Most of these operations are also available in version 8.1. Operations in version 8.1.1 take the same required parameters as operations in version 7.1.4. You can run client applications written for version 7.1.4 with no changes in version 8.1.1. In addition, operations in version 8.1.1 can optionally take the same parameters as operations in version 8.1. To run client applications written for version 8.1, add the repository authentication operations (Login and Logout) to the client application.
112
113
resumeTask stopDIServer
114
Index
A
attachments flat file mappings 75 mapping 75 SOAP messages 87 XML mappings 75 authentication Web Services Hub security 20 authorization Web Services Hub security 20
B
Batch web services compiling sample programs 97 Data Integration web service operations 29 description 8, 15, 26 downloading WSDL 15 Metadata web service operations 27 running sample programs 98 viewing published services 15
C
caching configuring for web services 87
clean up Axis client application 43 web service client application 39 client applications clean up in Axis 43 creating request objects for Realtime web services 51 developing 37 error handling 39, 49 error handling in .NET 46 error handling in Axis 43 generating proxy classes 37, 48 generating proxy classes for Realtime web services 51 generating proxy classes in .NET 44 generating proxy classes in Axis 40 initialization 37, 48 initialization in .NET 44 initialization in Axis 40 initializing objects for Realtime web services 51 operation calls 38, 49 operation calls in .NET 45 operation calls in Axis 42 proxy objects 39 Realtime web services 50 resource clean up 39 sending request objects for Realtime web services 52 session maintenance 38 session maintenance in .NET 45 session maintenance in Axis 42
115
writing in .NET using C# 44 writing in Java using Axis 40 client proxy classes See proxy classes commit type configuring 88 configuring cache for web services 87 commit type 88 reader properties 82 writer properties 85 console Web Services Hub 15 Create entity relationships XML view option 61 Create hierarchical relationships XML view option 61
E
encryption Web Services Hub security 20 error handling .NET client application 46 Axis client application 43 client application 39, 49
F
fault body SOAP 23 fault detail SOAP 23 fault handling SOAP 22 fault header SOAP 22 faultcode SOAP 23 faultstring SOAP 23 flat file sessions guidelines 90 flat files mappings 75 flush latency description 90
D
Data Integration web service operations deinitializeDIServerConnection 30 getDIServerProperties 30 getNextLogSegment 30 getSessionLog 31 getSessionPerformanceData 31 getSessionStatistics 31 getTaskDetails 31 getWorkflowDetails 31 getWorkflowLog 32 monitorDIServer 32 pingDIServer 32 recoverWorkflow 33 resumeWorkflow 33 scheduleWorkflow 33 startSessionLogFetch 33 startTask 33 startWorkflow 33 startWorkflowFromTask 33 startWorkflowLogFetch 34 stopTask 34 stopWorkflow 34 unscheduleWorkflow 34 waitTillTaskComplete 34 waitTillWorkflowComplete 34 Data Integration web services description 29 operations available in version 8.1.1 114 operations not available in version 8.1.1 114
G
generating names XML columns 63 getAllDIServers Metadata web service operation 27 getAllFolders Metadata web service operation 27 getAllTaskInstances Metadata web service operation 28 getAllWorkflows Metadata web service operation 28 getDIServerProperties Data Integration web service operation 30
116
Index
getNextLogSegment Data Integration web service operation getSessionLog Data Integration web service operation getSessionPerformanceData Data Integration web service operation getSessionStatistics Data Integration web service operation getTaskDetails Data Integration web service operation getWorkflowDetails Data Integration web service operation getWorkflowLog Data Integration web service operation
30 31 31 31 31 31 32
M
mappings attachment 75 flat file 75 one-way 72 request-response 72 staged 73 XML 75 message IDs propagating 73 messages recovering 87 metadata extensions web service definitions 69 Metadata web service operations getAllDIServers 27 getAllFolders 27 getAllTaskInstances 28 getAllWorkflows 28 Login 28 Logout 28 Metadata web services description 8, 27 operations available in version 8.1.1 113 monitorDIServer Data Integration web service operation 32
I
importing web service source definitions 59 web service target definitions 60 importing source definitions steps 61 importing target definitions steps 61 infinite precision overriding 63 initialization .NET client application 44 Axis client application 40 client application 37, 48 initializing Realtime web services client applications 51 installation web services sample programs 96
O
one-way mappings description 72 operation calls .NET client application 45 Axis client application 42 web service client applications 38, 49 operations Data Integration web services 29 Metadata web services 27
L
load scope configuring 70 log files configuring 21 viewing 21 Login Metadata web service operation 28 Logout Metadata web service operation 28 logs Web Services Hub 21
P
parameter arrays defining in web service application 53 guidelines for web service clients 56 in web service application 53 parameters using a parameter array 53 partitioning web service sessions 88
Index
117
pingDIServer Data Integration web service operation 32 pipeline partitioning web service sessions 88 precision overriding infinite length 63 protected service workflow property 80 proxy classes generating 37, 48 generating for Realtime web services 51 generating in .NET 44 generating in Axis 40 proxy objects client application 39 session ID 39 published services viewing 15, 16
request objects creating in Realtime web services client applications 51 sending from Realtime web services client applications 52 request-response mapping using a SQL transformation 73 request-response mappings description 72 resumeWorkflow Data Integration web service operation 33 deprecated operation 33 runnable service workflow property 81
S
sample programs batch web services examples 99 compiling Batch web services examples 97 compiling Realtime web services examples 108 realtime web services examples 109 running Batch web services examples 98 running Realtime web services examples 108 web services 96 scheduleWorkflow Data Integration web service operation 33 security authentication 20 authorization 20 encryption 20 service configuring 79 service timeout description 90 service workflow configuring 79 creating 79 service workflows troubleshooting 92 session ID Metadata proxy objects 39 session maintenance .NET client application 45 Axis client application 42 client application 38 session properties Reader Time Limit 84 Real-time Flush Latency 84 sessions guidelines for XML and flat file sessions 90
R
reader properties configuring 82 Reader Time Limit description 84 Real-time Flush Latency configuring 84 description 84 real-time session property 84 real-time sessions configuring source-based commit 88 configuring target-based commit 88 Real-time Flush Latency property 84 Recovery Cache Folder property 84 Realtime web services compiling sample programs 108 creating web service 50 description 9, 16 developing client application 50 downloading WSDL 16, 50 running sample programs 108 using the Designer 58 viewing published services 16 recoverWorkflow Data Integration web service operation 33 recovery messages 87 Recovery Cache Folder real-time session property 84
118
Index
Simple Object Access Protocol See SOAP SOAP body 4 description 4 envelope 4 fault body 23 fault detail 23 fault handling 22 fault header 22 fault schema 23 faultcode 23 faultstring 23 guidelines for parameter arrays 56 header 4 message attachments 87 web service component 2 source definitions web services 59 source-based commit configuring 88 SQL transformation request-response mapping 73 staged mapping description 73 startSessionLogFetch Data Integration web service operation startTask Data Integration web service operation startWorkflow Data Integration web service operation startWorkflowFromTask Data Integration web service operation startWorkflowLogFetch Data Integration web service operation stopTask Data Integration web service operation stopWorkflow Data Integration web service operation
U
UDDI web service component 2 Universal Description, Discovery, and Integration See UDDI unscheduleWorkflow Data Integration web service operation 34
V
visible service workflow property 81
W
waitTillTaskComplete Data Integration web service operation 34 waitTillWorkflowComplete Data Integration web service operation 34 web service components SOAP 2 UDDI 2 WSDL 2 Web Service Definition Language See WSDL web service definitions editing 66 viewing 66 viewing in the XML Editor 69 web service operations available in version 8.1.1 112 not available in version 8.1.1 114 web service sessions pipeline partitioning 88 web service targets configuring load scope 70 web services Batch 8 batch client applications in Axis 40 batch client applications in C# 44 batch web services sample programs 99 building blocks 3 compiling Batch web services examples 97 compiling Realtime web services examples 108 configuring service workflows 80 Data Integration 8
Index 119
33 33 33 33 34 34 34
T
target definitions web services 60 target-based commit configuring 88 TaskRequest using a parameter array 54 timeout description 90 service workflow property 80
importing source definitions 61 importing target definitions 61 Metadata 8 overview 2 overview of sample programs 96 Realtime 9 realtime client applications 50 realtime web services sample programs 109 running Batch web services examples 98 running Realtime web services examples 108 source definitions 59 target definitions 60 troubleshooting 92 Web Services Hub Batch web services 15 console 15 description 8, 14 logs 21 Realtime web services 16 Web Services Provider See also Web Services Hub architecture 10 configuring reader 82 configuring writer 85 WorkflowRequest using a parameter array 54 writer properties configuring 85 WSDL Batch web services 15 description 5 Realtime web services 16, 50 web service component 2
X
XML columns generating names 63 XML Editor viewing web service definitions 69 XML sessions guidelines 90 XML views options 61
120
Index