Web Services Provider Guide

Web Services Provider Guide

Informatica PowerCenter® (Version 7.1.1)

Informatica PowerCenter Web Services Provider Guide Version 7.1.1 August 2004 Copyright (c) 1998–2004 Informatica Corporation. All rights reserved. Printed in the USA.

This software and documentation contain proprietary information of Informatica Corporation, they are provided under a license agreement containing restrictions on use and disclosure and is 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 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, PowerMart, PowerCenter, PowerChannel, PowerConnect, MX, and SuperGlue 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 are copyrighted by DataDirect Technologies, 1999-2002. 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-2004 The Apache Software Foundation. All rights reserved. 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 New Features and Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv PowerCenter 7.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv PowerCenter 7.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi PowerCenter 7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx About Informatica Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi About this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii Other Informatica Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii Visiting Informatica Customer Portal . . . . . . . . . . . . . . . . . . . . . . . . xxviii Visiting the Informatica Webzine . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii Visiting the Informatica Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii Visiting the Informatica Developer Network . . . . . . . . . . . . . . . . . . . xxviii Obtaining Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix

Chapter 1: Web Services Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Simple Object Access Protocol (SOAP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Web Services Description Language (WSDL) . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2: Installing and Configuring Web Services Hub . . . . . . . . . . 7 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Minimum System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Understanding the Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Step 1. Install the Web Services Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Installing the Web Services Hub on Windows . . . . . . . . . . . . . . . . . . . . 10 Installing the Web Services Hub on UNIX . . . . . . . . . . . . . . . . . . . . . . 10 Installation Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Step 2. Configure the Web Services Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 iii

Configuring Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Updating Static Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Configuring Logging Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Configuring the Web Services Hub for HTTPS . . . . . . . . . . . . . . . . . . . 16 Step 3. Start the Web Services Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Starting the Web Services Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Verifying the Web Services Hub Installation . . . . . . . . . . . . . . . . . . . . . 19 Stopping the Web Services Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Step 4. Run UpdateConfigFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Rules and Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Step 5. Register the Web Services Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Changing the Web Services Hub Port Number . . . . . . . . . . . . . . . . . . . . . . 25 Editing the Port Number in jboss-service.xml . . . . . . . . . . . . . . . . . . . . 25 Editing the Port Number in WSH.wsdl . . . . . . . . . . . . . . . . . . . . . . . . . 26 Editing the Port Number in WSHConfig.xml . . . . . . . . . . . . . . . . . . . . 26 Uninstalling Web Services Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 3: Understanding Web Services Provider . . . . . . . . . . . . . . 29 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Web Services Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Batch Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Metadata Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Real-time Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Web Services Provider Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 4: Understanding the Web Services Hub . . . . . . . . . . . . . . . 35 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Using the Web Services Hub Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Batch and Metadata Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Real-time Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Web Services Hub Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Encrypting Repository Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Web Services Hub Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Configuring the Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Viewing the Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 SOAP Fault Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 SOAP Fault Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 iv

Table of Contents

SOAP Fault Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Session Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Chapter 5: Using Metadata Web Services Functions . . . . . . . . . . . . 49 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Authentication Request Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Browsing Request Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 GetAllFolders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 GetAllWorkflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 GetAllTaskInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 GetAllDIServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 GetAllRepositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 6: Using Batch Web Services Functions . . . . . . . . . . . . . . . 55 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 PowerCenter Server Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 InitializeDIServerConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 DeinitializeDIServerConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 PingDIServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 GetDIServerConnectionState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 StopDIServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 GetDIServerProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Workflow Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 StartWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 StopWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 ScheduleWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 UnscheduleWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 WaitTillWorkflowComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 ResumeWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Task Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 StartTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 StopTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 WaitTillTaskComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 ResumeTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Monitoring and Reporting Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

v

MonitorDIServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 GetWorkflowDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 GetTaskDetails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 GetSessionStatistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 GetSessionPerformanceData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Log Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 GettingWorkflowLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 GetSessionLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Max Log Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Chapter 7: Writing Client Applications . . . . . . . . . . . . . . . . . . . . . . . . 67 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Writing a Simple Client Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Generating Client Proxy Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Session Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Making Function Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Cleaning up Server Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Invalidating Proxy Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Writing a Client Application in Java Using Axis . . . . . . . . . . . . . . . . . . . . . . 73 Generating Client Proxy Classes in Axis . . . . . . . . . . . . . . . . . . . . . . . . 73 Initialization in Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Session Maintenance in Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Making Function Calls in Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Cleaning Up in Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Error Handling in Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Writing a Client Application in C# Using .Net . . . . . . . . . . . . . . . . . . . . . . 77 Generating Client Proxy Classes in .Net . . . . . . . . . . . . . . . . . . . . . . . . 77 Initialization in .Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Session Maintenance in .Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Making Function Calls in .Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Cleaning Up in .Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Error Handling in .Net . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Chapter 8: Working with Service Mappings . . . . . . . . . . . . . . . . . . . . 81 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 vi

Table of Contents

Importing Web Service Source and Target Definitions . . . . . . . . . . . . . . . . . 83 Importing Web Service Source Definitions . . . . . . . . . . . . . . . . . . . . . . 83 Importing Web Service Target Definitions . . . . . . . . . . . . . . . . . . . . . . 84 Steps for Importing Web Service Sources and Targets . . . . . . . . . . . . . . 85 Viewing and Editing Web Service Definitions . . . . . . . . . . . . . . . . . . . . . . . 89 Viewing and Editing Definitions in the Designer . . . . . . . . . . . . . . . . . 89 View Definitions in the XML Editor . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Editing Web Service Targets in a Mapping . . . . . . . . . . . . . . . . . . . . . . 93 Working with Service Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Request-Response Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Staged Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Flat File or XML Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Attachment Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Chapter 9: Working With Service Workflows . . . . . . . . . . . . . . . . . . . 99 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Creating and Configuring a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Creating a Service Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Configuring the Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Creating and Configuring a Service Session . . . . . . . . . . . . . . . . . . . . . . . 103 Configuring the Web Services Provider Reader . . . . . . . . . . . . . . . . . . 103 Configuring the Web Services Provider Writer . . . . . . . . . . . . . . . . . . 105 Recovering Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Configuring Commit Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Configuring Partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Running Sessions and Service Workflows . . . . . . . . . . . . . . . . . . . . . . . . . 109 Working with XML and Flat File Sessions . . . . . . . . . . . . . . . . . . . . . . 109 Understanding Service Timeout and Flush Latency . . . . . . . . . . . . . . . 109 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Appendix A: Web Services Hub Error Messages . . . . . . . . . . . . . . . 113 Web Services Hub Level Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

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. 2-2. 3-1. 4-1. 4-2. 4-3. 8-1. 8-2. 8-3. 8-4. 8-5. 8-6. 8-7. 9-1. 9-2. 9-3.

Building Blocks of a Web Service . . . . . . . . . . . . . . . . Web Services Hub Console . . . . . . . . . . . . . . . . . . . . . Web Services Hub Editor . . . . . . . . . . . . . . . . . . . . . . Web Services Provider Architecture . . . . . . . . . . . . . . . Web Services Hub Console . . . . . . . . . . . . . . . . . . . . . Transformation Services Page . . . . . . . . . . . . . . . . . . . Transformation 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 Service Workflow . . . . . . . . . . . . . . . . . . . Web Service Configuration . . . . . . . . . . . . . . . . . . . . . Web Services Provider Reader Properties . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . .

.. 3 . 20 . 23 . 32 . 37 . 38 . 39 . 83 . 85 . 90 . 91 . 92 . 93 . 96 101 102 104

List of Figures

ix

x

List of Figures

List of Tables Table Table Table Table Table Table Table Table Table Table Table Table Table Table Table Table

2-1. 2-2. 2-3. 2-4. 2-5. 2-6. 4-1. 4-2. 8-1. 8-2. 8-3. 8-4. 8-5. 9-1. 9-2. 9-3.

Web Services Hub Installation Directories . WSHConfig.xml Parameters . . . . . . . . . . . WSHLog.properties Parameters . . . . . . . . config.xml Parameters . . . . . . . . . . . . . . . UpdateConfigFile Options . . . . . . . . . . . . Web Services Hub Properties . . . . . . . . . . Transformation Services Page . . . . . . . . . . Transformation Service Description Page . Web Services Definition Groups . . . . . . . . Message Header Ports . . . . . . . . . . . . . . . Advanced Options . . . . . . . . . . . . . . . . . . Required Sources and Targets in a Service Attachment Group Ports . . . . . . . . . . . . . Web Service Properties . . . . . . . . . . . . . . . Web Services Provider Reader Properties . . Web Services Provider Writer Properties . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. 11 . 15 . 16 . 21 . 22 . 24 . 39 . 39 . 84 . 84 . 87 . 95 . 97 102 104 106

List of Tables

xi

xii

List of Tables

Preface Welcome to PowerCenter, Informatica’s software product that delivers an open, scalable data integration solution addressing the complete life cycle for all data integration projects including data warehouses and data marts, 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 metadata repository coordinates and drives a variety of core functions, including extracting, transforming, loading, and managing data. The PowerCenter Server 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 moving data warehouses from development to test to production.

xiii

New Features and Enhancements This section describes new features and enhancements to PowerCenter 7.1.1, 7.1, and 7.0.

PowerCenter 7.1.1 This section describes new features and enhancements to PowerCenter 7.1.1.

Data Profiling ♦

Data sampling. You can create a data profile for a sample of source data instead of the entire source. You can view a profile from a random sample of data, a specified percentage of data, or for a specified number of rows starting with the first row.

♦

Verbose data enhancements. You can specify the type of verbose data you want the PowerCenter Server to write to the Data Profiling warehouse. The PowerCenter Server can write all rows, the rows that meet the business rule, or the rows that do not meet the business rule.

♦

Session enhancement. You can save sessions that you create from the Profile Manager to the repository.

♦

Domain Inference function tuning. You can configure the Data Profiling Wizard to filter the Domain Inference function results. You can configure a maximum number of patterns and a minimum pattern frequency. You may want to narrow the scope of patterns returned to view only the primary domains, or you may want to widen the scope of patterns returned to view exception data.

♦

Row Uniqueness function. You can determine unique rows for a source based on a selection of columns for the specified source.

♦

Define mapping, session, and workflow prefixes. You can define default mapping, session, and workflow prefixes for the mappings, sessions, and workflows generated when you create a data profile.

♦

Profile mapping display in the Designer. The Designer displays profile mappings under a profile mappings node in the Navigator.

PowerCenter Server

xiv

Preface

♦

Code page. PowerCenter supports additional Japanese language code pages, such as JIPSEkana, JEF-kana, and MELCOM-kana.

♦

Flat file partitioning. When you create multiple partitions for a flat file source session, you can configure the session to create multiple threads to read the flat file source.

♦

pmcmd. You can use parameter files that reside on a local machine with the Startworkflow command in the pmcmd program. When you use a local parameter file, pmcmd passes variables and values in the file to the PowerCenter Server.

♦

SuSE Linux support. The PowerCenter Server runs on SuSE Linux. On SuSE Linux, you can connect to IBM, DB2, Oracle, and Sybase sources, targets, and repositories using native drivers. Use ODBC drivers to access other sources and targets.

♦

Reserved word support. If any source, target, or lookup table name or column name contains a database reserved word, you can create and maintain a file, reswords.txt, containing reserved words. When the PowerCenter Server initializes a session, it searches for reswords.txt in the PowerCenter Server installation directory. If the file exists, the PowerCenter Server places quotes around matching reserved words when it executes SQL against the database.

♦

Teradata external loader. When you load to Teradata using an external loader, you can now override the control file. Depending on the loader you use, you can also override the error, log, and work table names by specifying different tables on the same or different Teradata database.

Repository ♦

Exchange metadata with other tools. You can exchange source and target metadata with other BI or data modeling tools, such as Business Objects Designer. You can export or import multiple objects at a time. When you export metadata, the PowerCenter Client creates a file format recognized by the target tool.

Repository Server ♦

♦

pmrep. You can use pmrep to perform the following functions: −

Remove repositories from the Repository Server cache entry list.

−

Enable enhanced security when you create a relational source or target connection in the repository.

−

Update a connection attribute value when you update the connection.

SuSE Linux support. The Repository Server runs on SuSE Linux. On SuSE Linux, you can connect to IBM, DB2, Oracle, and Sybase repositories.

Security ♦

Oracle OS Authentication. You can now use Oracle OS Authentication to authenticate database users. Oracle OS Authentication allows you to log on to an Oracle database if you have a logon to the operating system. You do not need to know a database user name and password. PowerCenter uses Oracle OS Authentication when the user name for an Oracle connection is PmNullUser.

Web Services Provider ♦

Attachment support. When you import web service definitions with attachment groups, you can pass attachments through the requests or responses in a service session. The document type you can attach is based on the mime content of the WSDL file. You can attach document types such as XML, JPEG, GIF, or PDF.

Preface

xv

♦

Pipeline partitioning. You can create multiple partitions in a session containing web service source and target definitions. The PowerCenter Server creates a connection to the Web Services Hub based on the number of sources, targets, and partitions in the session.

XML ♦

Multi-level pivoting. You can now pivot more than one multiple-occurring element in an XML view. You can also pivot the view row.

PowerCenter 7.1 This section describes new features and enhancements to PowerCenter 7.1.

Data Profiling ♦

Data Profiling for VSAM sources. You can now create a data profile for VSAM sources.

♦

Support for verbose mode for source-level functions. You can now create data profiles with source-level functions and write data to the Data Profiling warehouse in verbose mode.

♦

Aggregator function in auto profiles. Auto profiles now include the Aggregator function.

♦

Creating auto profile enhancements. You can now select the columns or groups you want to include in an auto profile and enable verbose mode for the Distinct Value Count function.

♦

Purging data from the Data Profiling warehouse. You can now purge data from the Data Profiling warehouse.

♦

Source View in the Profile Manager. You can now view data profiles by source definition in the Profile Manager.

♦

PowerCenter Data Profiling report enhancements. You can now view PowerCenter Data Profiling reports in a separate browser window, resize columns in a report, and view verbose data for Distinct Value Count functions.

♦

Prepackaged domains. Informatica provides a set of prepackaged domains that you can include in a Domain Validation function in a data profile.

Documentation ♦

Web Services Provider Guide. This is a new book that describes the functionality of Real-time Web Services. It also includes information from the version 7.0 Web Services Hub Guide.

♦

XML User Guide. This book consolidates XML information previously documented in the Designer Guide, Workflow Administration Guide, and Transformation Guide.

Licensing Informatica provides licenses for each CPU and each repository rather than for each installation. Informatica provides licenses for product, connectivity, and options. You store xvi

Preface

the repository license keys in a license key file. You can manage the license files using the Repository Server Administration Console, the PowerCenter Server Setup, and the command line program, pmlic.

PowerCenter Server ♦

64-bit support. You can now run 64-bit PowerCenter Servers on AIX and HP-UX (Itanium).

♦

Partitioning enhancements. If you have the Partitioning option, you can define up to 64 partitions at any partition point in a pipeline that supports multiple partitions.

♦

PowerCenter Server processing enhancements. The PowerCenter Server now reads a block of rows at a time. This improves processing performance for most sessions.

♦

CLOB/BLOB datatype support. You can now read and write CLOB/BLOB datatypes.

PowerCenter Metadata Reporter PowerCenter Metadata Reporter modified some report names and uses the PowerCenter 7.1 MX views in its schema.

Repository Server ♦

Updating repository statistics. PowerCenter now identifies and updates statistics for all repository tables and indexes when you copy, upgrade, and restore repositories. This improves performance when PowerCenter accesses the repository.

♦

Increased repository performance. You can increase repository performance by skipping information when you copy, back up, or restore a repository. You can choose to skip MX data, workflow and session log history, and deploy group history.

♦

pmrep. You can use pmrep to back up, disable, or enable a repository, delete a relational connection from a repository, delete repository details, truncate log files, and run multiple pmrep commands sequentially. You can also use pmrep to create, modify, and delete a folder.

Repository ♦

Exchange metadata with business intelligence tools. You can export metadata to and import metadata from other business intelligence tools, such as Cognos Report Net and Business Objects.

♦

Object import and export enhancements. You can compare objects in an XML file to objects in the target repository when you import objects.

♦

MX views. MX views have been added to help you analyze metadata stored in the repository. REP_SERVER_NET and REP_SERVER_NET_REF views allow you to see information about server grids. REP_VERSION_PROPS allows you to see the version history of all objects in a PowerCenter repository.

Preface

xvii

Transformations ♦

Flat file lookup. You can now perform lookups on flat files. When you create a Lookup transformation using a flat file as a lookup source, the Designer invokes the Flat File Wizard. You can also use a lookup file parameter if you want to change the name or location of a lookup between session runs.

♦

Dynamic lookup cache enhancements. When you use a dynamic lookup cache, the PowerCenter Server can ignore some ports when it compares values in lookup and input ports before it updates a row in the cache. Also, you can choose whether the PowerCenter Server outputs old or new values from the lookup/output ports when it updates a row. You might want to output old values from lookup/output ports when you use the Lookup transformation in a mapping that updates slowly changing dimension tables.

♦

Union transformation. You can use the Union transformation to merge multiple sources into a single pipeline. The Union transformation is similar to using the UNION ALL SQL statement to combine the results from two or more SQL statements.

♦

Custom transformation API enhancements. The Custom transformation API includes new array-based functions that allow you to create procedure code that receives and outputs a block of rows at a time. Use these functions to take advantage of the PowerCenter Server processing enhancements.

♦

Midstream XML transformations. You can now create an XML Parser transformation or an XML Generator transformation to parse or generate XML inside a pipeline. The XML transformations enable you to extract XML data stored in relational tables, such as data stored in a CLOB column. You can also extract data from messaging systems, such as TIBCO or IBM MQSeries.

Usability ♦

Viewing active folders. The Designer and the Workflow Manager highlight the active folder in the Navigator.

♦

Enhanced printing. The quality of printed workspace has improved.

Version Control You can run object queries that return shortcut objects. You can also run object queries based on the latest status of an object. The query can return local objects that are checked out, the latest version of checked in objects, or a collection of all older versions of objects.

Web Services Provider

xviii

Preface

♦

Real-time Web Services. Real-time Web Services allows you to create services using the Workflow Manager and make them available to web service clients through the Web Services Hub. The PowerCenter Server can perform parallel processing of both requestresponse and one-way services.

♦

Web Services Hub. The Web Services Hub now hosts Real-time Web Services in addition to Metadata Web Services and Batch Web Services. You can install the Web Services Hub on a JBoss application server.

Note: PowerCenter Connect for Web Services allows you to create sources, targets, and transformations to call web services hosted by other providers. For more information, see PowerCenter Connect for Web Services User and Administrator Guide.

Workflow Monitor The Workflow Monitor includes the following performance and usability enhancements: ♦

When you connect to the PowerCenter Server, you no longer distinguish between online or offline mode.

♦

You can open multiple instances of the Workflow Monitor on one machine.

♦

You can simultaneously monitor multiple PowerCenter Servers registered to the same repository.

♦

The Workflow Monitor includes improved options for filtering tasks by start and end time.

♦

The Workflow Monitor displays workflow runs in Task view chronologically with the most recent run at the top. It displays folders alphabetically.

♦

You can remove the Navigator and Output window.

XML Support PowerCenter XML support now includes the following features: ♦

Enhanced datatype support. You can use XML schemas that contain simple and complex datatypes.

♦

Additional options for XML definitions. When you import XML definitions, you can choose how you want the Designer to represent the metadata associated with the imported files. You can choose to generate XML views using hierarchy or entity relationships. In a view with hierarchy relationships, the Designer expands each element and reference under its parent element. When you create views with entity relationships, the Designer creates separate entities for references and multiple-occurring elements.

♦

Synchronizing XML definitions. You can synchronize one or more XML definition when the underlying schema changes. You can synchronize an XML definition with any repository definition or file used to create the XML definition, including relational sources or targets, XML files, DTD files, or schema files.

♦

XML workspace. You can edit XML views and relationships between views in the workspace. You can create views, add or delete columns from views, and define relationships between views.

♦

Midstream XML transformations. You can now create an XML Parser transformation or an XML Generator transformation to parse or generate XML inside a pipeline. The XML transformations enable you to extract XML data stored in relational tables, such as data stored in a CLOB column. You can also extract data from messaging systems, such as TIBCO or IBM MQSeries.

Preface

xix

♦

Support for circular references. Circular references occur when an element is a direct or indirect child of itself. PowerCenter now supports XML files, DTD files, and XML schemas that use circular definitions.

♦

Increased performance for large XML targets. You can create XML files of several gigabytes in a PowerCenter 7.1 XML session by using the following enhancements: −

Spill to disk. You can specify the size of the cache used to store the XML tree. If the size of the tree exceeds the cache size, the XML data spills to disk in order to free up memory.

−

User-defined commits. You can define commits to trigger flushes for XML target files.

−

Support for multiple XML output files. You can output XML data to multiple XML targets. You can also define the file names for XML output files in the mapping.

PowerCenter 7.0 This section describes new features and enhancements to PowerCenter 7.0.

Data Profiling If you have the Data Profiling option, you can profile source data to evaluate source data and detect patterns and exceptions. For example, you can determine implicit data type, suggest candidate keys, detect data patterns, and evaluate join criteria. After you create a profiling warehouse, you can create profiling mappings and run sessions. Then you can view reports based on the profile data in the profiling warehouse. The PowerCenter Client provides a Profile Manager and a Profile Wizard to complete these tasks.

Data Integration Web Services You can use Data Integration Web Services to write applications to communicate with the PowerCenter Server. Data Integration Web Services is a web-enabled version of the PowerCenter Server functionality available through Load Manager and Metadata Exchange. It is comprised of two services for communication with the PowerCenter Server, Load Manager and Metadata Exchange Web Services running on the Web Services Hub.

Documentation

xx

Preface

♦

Glossary. The Installation and Configuration Guide contains a glossary of new PowerCenter terms.

♦

Installation and Configuration Guide. The connectivity information in the Installation and Configuration Guide is consolidated into two chapters. This book now contains chapters titled “Connecting to Databases from Windows” and “Connecting to Databases from UNIX.”

♦

Upgrading metadata. The Installation and Configuration Guide now contains a chapter titled “Upgrading Repository Metadata.” This chapter describes changes to repository

objects impacted by the upgrade process. The change in functionality for existing objects depends on the version of the existing objects. Consult the upgrade information in this chapter for each upgraded object to determine whether the upgrade applies to your current version of PowerCenter.

Functions ♦

Soundex. The Soundex function encodes a string value into a four-character string. SOUNDEX works for characters in the English alphabet (A-Z). It uses the first character of the input string as the first character in the return value and encodes the remaining three unique consonants as numbers.

♦

Metaphone. The Metaphone function encodes string values. You can specify the length of the string that you want to encode. METAPHONE encodes characters of the English language alphabet (A-Z). It encodes both uppercase and lowercase letters in uppercase.

Installation ♦

Remote PowerCenter Client installation. You can create a control file containing installation information, and distribute it to other users to install the PowerCenter Client. You access the Informatica installation CD from the command line to create the control file and install the product.

PowerCenter Metadata Reporter PowerCenter Metadata Reporter replaces Runtime Metadata Reporter and Informatica Metadata Reporter. PowerCenter Metadata Reporter includes the following features: ♦

Metadata browsing. You can use PowerCenter Metadata Reporter to browse PowerCenter 7.0 metadata, such as workflows, worklets, mappings, source and target tables, and transformations.

♦

Metadata analysis. You can use PowerCenter Metadata Reporter to analyze operational metadata, including session load time, server load, session completion status, session errors, and warehouse growth.

PowerCenter Server ♦

DB2 bulk loading. You can enable bulk loading when you load to IBM DB2 8.1.

♦

Distributed processing. If you purchase the Server Grid option, you can group PowerCenter Servers registered to the same repository into a server grid. In a server grid, PowerCenter Servers balance the workload among all the servers in the grid.

♦

Row error logging. The session configuration object has new properties that allow you to define error logging. You can choose to log row errors in a central location to help understand the cause and source of errors.

♦

External loading enhancements. When using external loaders on Windows, you can now choose to load from a named pipe. When using external loaders on UNIX, you can now choose to load from staged files. Preface

xxi

♦

External loading using Teradata Warehouse Builder. You can use Teradata Warehouse Builder to load to Teradata. You can choose to insert, update, upsert, or delete data. Additionally, Teradata Warehouse Builder can simultaneously read from multiple sources and load data into one or more tables.

♦

Mixed mode processing for Teradata external loaders. You can now use data driven load mode with Teradata external loaders. When you select data driven loading, the PowerCenter Server flags rows for insert, delete, or update. It writes a column in the target file or named pipe to indicate the update strategy. The control file uses these values to determine how to load data to the target.

♦

Concurrent processing. The PowerCenter Server now reads data concurrently from sources within a target load order group. This enables more efficient joins with minimal usage of memory and disk cache.

♦

Real time processing enhancements. You can now use real-time processing in sessions that also process active transformations, such as the Aggregator transformation. You can apply the transformation logic to rows defined by transaction boundaries.

Repository Server ♦

Object export and import enhancements. You can now export and import objects using the Repository Manager and pmrep. You can export and import multiple objects and objects types. You can export and import objects with or without their dependent objects. You can also export objects from a query result or objects history.

♦

pmrep commands. You can use pmrep to perform change management tasks, such as maintaining deployment groups and labels, checking in, deploying, importing, exporting, and listing objects. You can also use pmrep to run queries. The deployment and object import commands require you to use a control file to define options and resolve conflicts.

♦

Trusted connections. You can now use a Microsoft SQL Server trusted connection to connect to the repository.

Security

xxii

Preface

♦

LDAP user authentication. You can now use default repository user authentication or Lightweight Directory Access Protocol (LDAP) to authenticate users. If you use LDAP, the repository maintains an association between your repository user name and your external login name. When you log in to the repository, the security module passes your login name to the external directory for authentication. The repository maintains a status for each user. You can now enable or disable users from accessing the repository by changing the status. You do not have to delete user names from the repository.

♦

Use Repository Manager privilege. The Use Repository Manager privilege allows you to perform tasks in the Repository Manager, such as copy object, maintain labels, and change object status. You can perform the same tasks in the Designer and Workflow Manager if you have the Use Designer and Use Workflow Manager privileges.

♦

Audit trail. You can track changes to repository users, groups, privileges, and permissions through the Repository Administration Console. The Repository Agent logs security changes to a log file stored in the Repository Server installation directory. The audit trail

log contains information, such as changes to folder properties, adding or removing a user or group, and adding or removing privileges.

Transformations ♦

Custom transformation. Custom transformations operate in conjunction with procedures you create outside of the Designer interface to extend PowerCenter functionality. The Custom transformation replaces the Advanced External Procedure transformation. You can create Custom transformations with multiple input and output groups, and you can compile the procedure with any C compiler. You can create templates that customize the appearance and available properties of a Custom transformation you develop. You can specify the icons used for transformation, the colors, and the properties a mapping developer can modify. When you create a Custom transformation template, distribute the template with the DLL or shared library you develop.

♦

Joiner transformation. You can use the Joiner transformation to join two data streams that originate from the same source.

Version Control The PowerCenter Client and repository introduce features that allow you to create and manage multiple versions of objects in the repository. Version control allows you to maintain multiple versions of an object, control development on the object, track changes, and use deployment groups to copy specific groups of objects from one repository to another. Version control in PowerCenter includes the following features: ♦

Object versioning. Individual objects in the repository are now versioned. This allows you to store multiple copies of a given object during the development cycle. Each version is a separate object with unique properties.

♦

Check out and check in versioned objects. You can check out and reserve an object you want to edit, and check in the object when you are ready to create a new version of the object in the repository.

♦

Compare objects. The Repository Manager and Workflow Manager allow you to compare two repository objects of the same type to identify differences between them. You can compare Designer objects and Workflow Manager objects in the Repository Manager. You can compare tasks, sessions, worklets, and workflows in the Workflow Manager. The PowerCenter Client tools allow you to compare objects across open folders and repositories. You can also compare different versions of the same object.

♦

Delete or purge a version. You can delete an object from view and continue to store it in the repository. You can recover or undelete deleted objects. If you want to permanently remove an object version, you can purge it from the repository.

♦

Deployment. Unlike copying a folder, copying a deployment group allows you to copy a select number of objects from multiple folders in the source repository to multiple folders in the target repository. This gives you greater control over the specific objects copied from one repository to another.

Preface

xxiii

♦

Deployment groups. You can create a deployment group that contains references to objects from multiple folders across the repository. You can create a static deployment group that you manually add objects to, or create a dynamic deployment group that uses a query to populate the group.

♦

Labels. A label is an object that you can apply to versioned objects in the repository. This allows you to associate multiple objects in groups defined by the label. You can use labels to track versioned objects during development, improve query results, and organize groups of objects for deployment or export and import.

♦

Queries. You can create a query that specifies conditions to search for objects in the repository. You can save queries for later use. You can make a private query, or you can share it with all users in the repository.

♦

Track changes to an object. You can view a history that includes all versions of an object and compare any version of the object in the history to any other version. This allows you to see the changes made to an object over time.

XML Support PowerCenter contains XML features that allow you to validate an XML file against an XML schema, declare multiple namespaces, use XPath to locate XML nodes, increase performance for large XML files, format your XML file output for increased readability, and parse or generate XML data from various sources. XML support in PowerCenter includes the following features: ♦

XML schema. You can use an XML schema to validate an XML file and to generate source and target definitions. XML schemas allow you to declare multiple namespaces so you can use prefixes for elements and attributes. XML schemas also allow you to define some complex datatypes.

♦

XPath support. The XML wizard allows you to view the structure of XML schema. You can use XPath to locate XML nodes.

♦

Increased performance for large XML files. When you process an XML file or stream, you can set commits and periodically flush XML data to the target instead of writing all the output at the end of the session. You can choose to append the data to the same target file or create a new target file after each flush.

♦

XML target enhancements. You can format the XML target file so that you can easily view the XML file in a text editor. You can also configure the PowerCenter Server to not output empty elements to the XML target.

Usability

xxiv

Preface

♦

Copying objects. You can now copy objects from all the PowerCenter Client tools using the copy wizard to resolve conflicts. You can copy objects within folders, to other folders, and to different repositories. Within the Designer, you can also copy segments of mappings to a workspace in a new folder or repository.

♦

Comparing objects. You can compare workflows and tasks from the Workflow Manager. You can also compare all objects from within the Repository Manager.

♦

Change propagation. When you edit a port in a mapping, you can choose to propagate changed attributes throughout the mapping. The Designer propagates ports, expressions, and conditions based on the direction that you propagate and the attributes you choose to propagate.

♦

Enhanced partitioning interface. The Session Wizard is enhanced to provide a graphical depiction of a mapping when you configure partitioning.

♦

Revert to saved. You can now revert to the last saved version of an object in the Workflow Manager. When you do this, the Workflow Manager accesses the repository to retrieve the last-saved version of the object.

♦

Enhanced validation messages. The PowerCenter Client writes messages in the Output window that describe why it invalidates a mapping or workflow when you modify a dependent object.

♦

Validate multiple objects. You can validate multiple objects in the repository without fetching them into the workspace. You can save and optionally check in objects that change from invalid to valid status as a result of the validation. You can validate sessions, mappings, mapplets, workflows, and worklets.

♦

View dependencies. Before you edit or delete versioned objects, such as sources, targets, mappings, or workflows, you can view dependencies to see the impact on other objects. You can view parent and child dependencies and global shortcuts across repositories. Viewing dependencies help you modify objects and composite objects without breaking dependencies.

♦

Refresh session mappings. In the Workflow Manager, you can refresh a session mapping.

Preface

xxv

About Informatica Documentation The complete set of documentation for PowerCenter includes the following books:

xxvi

Preface

♦

Data Profiling Guide. Provides information about how to profile PowerCenter sources to evaluate source data and detect patterns and exceptions.

♦

Designer Guide. Provides information needed to use the Designer. Includes information to help you create mappings, mapplets, and transformations. Also includes a description of the transformation datatypes used to process and transform source data.

♦

Getting Started. Provides basic tutorials for getting started.

♦

Installation and Configuration Guide. Provides information needed to install and configure the PowerCenter tools, including details on environment variables and database connections.

♦

PowerCenter Connect® for JMS® User and Administrator Guide. Provides information to install PowerCenter Connect for JMS, build mappings, extract data from JMS messages, and load data into JMS messages.

♦

Repository Guide. Provides information needed to administer the repository using the Repository Manager or the pmrep command line program. Includes details on functionality available in the Repository Manager and Administration Console, such as creating and maintaining repositories, folders, users, groups, and permissions and privileges.

♦

Transformation Language Reference. Provides syntax descriptions and examples for each transformation function provided with PowerCenter.

♦

Transformation Guide. Provides information on how to create and configure each type of transformation in the Designer.

♦

Troubleshooting Guide. Lists error messages that you might encounter while using PowerCenter. Each error message includes one or more possible causes and actions that you can take to correct the condition.

♦

Web Services Provider Guide. Provides information you need to install and configure the Web Services Hub. This guide also provides information about how to use the web services that the Web Services Hub hosts. The Web Services Hub hosts Real-time Web Services, Batch Web Services, and Metadata Web Services.

♦

Workflow Administration Guide. Provides information to help you create and run workflows in the Workflow Manager, as well as monitor workflows in the Workflow Monitor. Also contains information on administering the PowerCenter Server and performance tuning.

♦

XML User Guide. Provides information you need to create XML definitions from XML, XSD, or DTD files, and relational or other XML definitions. Includes information on running sessions with XML data. Also includes details on using the midstream XML transformations to parse or generate XML data within a pipeline.

About this Book The Web Services Provider Guide provides information you need to install and configure the Web Services Hub. This guide also provides information about how to use the web services that the Web Services Hub hosts. The Web Services Hub hosts Real-time Web Services, Batch Web Services, and Metadata Web Services. This guide assumes that you have a working knowledge of XML and web service concepts. The material in this book is available for online use.

Document Conventions This guide uses the following formatting conventions: If you see…

It means…

italicized text

The word or set of words are especially emphasized.

boldfaced text

Emphasized subjects.

italicized monospaced text

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.

Note:

The following paragraph provides additional facts.

Tip:

The following paragraph provides suggested uses.

Warning:

The following paragraph notes situations where you can overwrite or corrupt data, unless you follow the specified procedure.

monospaced text

This is a code example.

bold monospaced text

This is an operating system command you enter from a prompt to run a task.

Preface

xxvii

Other Informatica Resources In addition to the product manuals, Informatica provides these other resources: ♦

Informatica Customer Portal

♦

Informatica Webzine

♦

Informatica web site

♦

Informatica Developer Network

♦

Informatica Technical Support

Visiting Informatica Customer Portal As an Informatica customer, you can access the Informatica Customer Portal site at http:// my.informatica.com. The site contains product information, user group information, newsletters, access to the Informatica customer support case management system (ATLAS), the Informatica Knowledgebase, Informatica Webzine, and access to the Informatica user community.

Visiting the Informatica Webzine The Informatica Documentation team delivers an online journal, the Informatica Webzine. This journal provides solutions to common tasks, detailed descriptions of specific features, and tips and tricks to help you develop data warehouses. The Informatica Webzine is a password-protected site that you can access through the Customer Portal. The Customer Portal has an online registration form for login accounts to its webzine and web support. To register for an account, go to http://my.informatica.com. If you have any questions, please email [email protected].

Visiting the Informatica Web Site You can access Informatica’s corporate web site at http://www.informatica.com. The site contains information about Informatica, its background, upcoming events, and locating your closest sales office. You will also find product information, as well as literature and partner information. The services area of the site includes important information on technical support, training and education, and implementation services.

Visiting the Informatica Developer Network The Informatica Developer Network is a web-based forum for third-party software developers. You can access the Informatica Developer Network at the following URL: http://devnet.informatica.com

xxviii

Preface

The site contains information on how to create, market, and support customer-oriented addon solutions based on Informatica’s interoperability interfaces.

Obtaining Technical Support There are many ways to access Informatica technical support. You can call or email your nearest Technical Support Center listed below or you can use our WebSupport Service. WebSupport requires a user name and password. You can request a user name and password at http://my.informatica.com. North America / South America

Africa / Asia / Australia / Europe

Informatica Corporation 2100 Seaport Blvd. Redwood City, CA 94063 Phone: 866.563.6332 or 650.385.5800 Fax: 650.213.9489 Hours: 6 a.m. - 6 p.m. (PST/PDT) email: [email protected]

Informatica Software Ltd. 6 Waltham Park Waltham Road, White Waltham Maidenhead, Berkshire SL6 3TN Phone: 44 870 606 1525 Fax: +44 1628 511 411 Hours: 9 a.m. - 5:30 p.m. (GMT) email: [email protected] Belgium Phone: +32 15 281 702 Hours: 9 a.m. - 5:30 p.m. (local time) France Phone: +33 1 41 38 92 26 Hours: 9 a.m. - 5:30 p.m. (local time) Germany Phone: +49 1805 702 702 Hours: 9 a.m. - 5:30 p.m. (local time) Netherlands Phone: +31 306 082 089 Hours: 9 a.m. - 5:30 p.m. (local time) Singapore Phone: +65 322 8589 Hours: 9 a.m. - 5 p.m. (local time) Switzerland Phone: +41 800 81 80 70 Hours: 8 a.m. - 5 p.m. (local time)

Preface

xxix

xxx

Preface

Chapter 1

Web Services Concepts This chapter includes the following topics: ♦

Overview, 2

♦

Simple Object Access Protocol (SOAP), 4

♦

Web Services Description Language (WSDL), 5

1

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. PowerCenter Web Services Provider allows you to integrate Informatica’s metadata and data integration functionalities. You can write applications that can communicate with PowerCenter Servers 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 services messages.

♦

Web Service Definition Language (WSDL). WSDL is an XML document that describes web services requests and responses. Similar to the IDL file for COM and CORBA, a WSDL file is a contract between client and server.

♦

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. PowerCenter Web Services Provider does not use the UDDI registry.

To build your own web service client, you can start by searching the registry to find published web services. Next, you select web service you want to interface with and retrieve the WSDL file for the designated web service. Using a web services 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 services require, and location of services by examining the self descriptive language of the WSDL files. The Web Services Description Language (WSDL) describes the web services interfaces with enough detail to allow a developer to build a client application to interact with them. Developers write them according to open standards. For more information about writing client applications, see “Writing Client Applications” on page 67.

2

Chapter 1: Web Services Concepts

Figure 1-1 shows the building blocks of a web service: Figure 1-1. Building Blocks of a Web Service

Overview

3

Simple Object Access Protocol (SOAP) SOAP is the communications protocol for web services. It defines the XML format for web services messages. SOAP encodings tell the SOAP runtime environment how to translate from data structures, such as Java into SOAP XML. SOAP and the Web Services Description Language (WSDL) dictate the communication between web services and their clients. A SOAP message contains the following sections: ♦

SOAP envelope. The envelope defines the framework of the message, what is in the message, who or what should deal with it, and whether it is optional or mandatory.

♦

SOAP header. The header is a child element of the SOAP envelope that allows you to 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 person or company that sent the SOAP message body and in what context it will be processed. You can 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. You can 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.

4

Chapter 1: Web Services Concepts

Web Services Description Language (WSDL) WSDL is an XML document that describes web services requests and responses. A WSDL file contains everything required to write a program to work with an XML web service. Similar to the IDL file for COM and CORBA, a WSDL file is a contract between client and server. This includes message content, location of service, and the communications protocol it uses to talk to the service. A WSDL document defines web services as a collection of network endpoints or ports. WSDL is comprised of concrete and abstract definitions. The abstract definitions are comprised of messages, which are descriptions of data being exchanged and port types, which are abstract collections of operations. The concrete protocol and data format specification for a particular port type constitute a reusable binding. This common binding mechanism allows the reuse of abstract definitions. Additionally, WSDLs can be cataloged and searched in a UDDI registry. A UDDI describes the web services in enough detail that you can write an API to interface with the service and your client. The UDDI descriptions include information about service interfaces and implementations.

Web Services Description Language (WSDL)

5

6

Chapter 1: Web Services Concepts

Chapter 2

Installing and Configuring Web Services Hub This chapter includes the following topics: ♦

Overview, 8

♦

Step 1. Install the Web Services Hub, 10

♦

Step 2. Configure the Web Services Hub, 13

♦

Step 3. Start the Web Services Hub, 19

♦

Step 4. Run UpdateConfigFile, 21

♦

Step 5. Register the Web Services Hub, 23

♦

Changing the Web Services Hub Port Number, 25

♦

Uninstalling Web Services Hub, 27

7

Overview The Web Services Hub is a PowerCenter service gateway that you install on an application server. You do not need to install it on the same machine as any PowerCenter component. You configure it with repository connectivity information and other parameters. To install and configure the Web Services Hub, complete the following steps: 1.

Install the Web Services Hub. For more information, see “Step 1. Install the Web Services Hub” on page 10. Web Services Hub supports JBoss 3.2.1. The Web Services Hub installation program installs JBoss.

2.

Configure the Web Services Hub. Configure environment variables, static Web Services Hub parameters, and logging levels. For more information, see “Step 2. Configure the Web Services Hub” on page 13.

3.

Verify the Web Services Hub installation. For more information, see “Step 3. Start the Web Services Hub” on page 19.

4.

Run UpdateConfigFile. Update the configuration file with dynamic parameters. For more information, see “Step 4. Run UpdateConfigFile” on page 21.

5.

Register the Web Services Hub with a repository. If you use Real-time Web Services, you register the Web Services Hub to the repository. For more information, see “Step 5. Register the Web Services Hub” on page 23.

Minimum System Requirements The Web Services Hub requires 90 MB of disk space. You can run the Web Services Hub on any platform that PowerCenter supports. The code page of the Web Services Hub must be compatible with the PowerCenter Server and Repository Server code pages. For more information about code pages, see “Globalization Overview” and “Code Pages” in the Installation and Configuration Guide.

Before You Begin You need to install the following components before you can run services on the Web Services Hub:

8

♦

PowerCenter. Install and configure PowerCenter. For information about PowerCenter installation, see the Installation and Configuration Guide.

♦

Java 2 Platform, Standard Edition (J2SE). Before installing the Web Services Hub, you must install the Java 2 Platform, Standard Edition (SDK version) on the machine where you install the Web Services Hub.

Chapter 2: Installing and Configuring Web Services Hub

To run Web Services Hub with JBoss, you must install one of the following versions of J2SE: Platform

J2SE Version

Windows

1.4.1

Solaris

1.3.1, 1.4.1, or 1.4.2

AIX

1.4.1 or 1.4.2

HP-UX

1.4.1 or 1.4.2

Linux

IBM Java 1.3.1

You can obtain J2SE for some platforms from the following URL: http://java.sun.com/j2se The Web Services Hub conforms to W3C SOAP 1.1 and WSDL 1.1 specifications. Note: Read the release notes for any change to installation or connectivity.

Understanding the Configuration File The installation program installs WSHConfig.xml in the Web Services Hub installation \config directory. You configure WSHConfig.xml before and after you start the Web Services Hub: ♦

Before you start the Web Services Hub. Configure static parameters, such as the Web Services Hub host name and port number, before you start the Web Services Hub. To configure this information, manually edit the configuration file. For more information, see “Step 2. Configure the Web Services Hub” on page 13.

♦

After you start the Web Services Hub. Register repositories and configure dynamic parameters after you start the Web Services Hub. To configure this information, you use the command line program, UpdateConfigFile. For more information, see “Step 4. Run UpdateConfigFile” on page 21.

Overview

9

Step 1. Install the Web Services Hub You can install the Web Services Hub on Windows or UNIX.

Installing the Web Services Hub on Windows Use the following procedure to install the Web Services Hub on Windows. To install the Web Services Hub on Windows: 1.

Log on to the machine as a user who is a member of the local Administrators group.

2.

From Windows, browse the CD and run launch.exe.

3.

Click Web Services Hub.

4.

Click Next.

5.

Click Browse to choose a destination folder for the Web Services Hub installation. Or, click Next to accept the default. Note: Do not use spaces in the install path if you install the Web Services Hub in a

location other than the default location. 6.

Click Install. After the installation completes, the installation program prompts you to set JAVA_HOME and add JAVA_HOME\bin to your system path. For more information, see “Configuring Environment Variables” on page 13.

7.

Click OK.

8.

Click Finish to exit Setup.

Installing the Web Services Hub on UNIX Use the following procedure to install the Web Services Hub on UNIX. To install the Web Services Hub on UNIX: 1.

Log on to the machine.

2.

From the WSHub directory on the installation CD, enter ./install to run the installation program.

3.

Enter 1 to install the Web Services Hub. Or, enter 0 to exit the installation.

4.

Enter the absolute path for the directory where you want to install the Web Services Hub. The installation program prompts you for permission to create the directory if it does not exist.

10

Chapter 2: Installing and Configuring Web Services Hub

The installation program extracts and installs the files. It then prompts you to view the readme file. 5.

Type Y if you want to read the readme file. Otherwise, type N to proceed.

6.

Press Enter and select Exit from the menu.

Installation Directories The Web Services Hub installation creates directories and files in your Web Services Hub installation directory. Table 2-1 describes the contents of the Web Services Hub installation directories: Table 2-1. Web Services Hub Installation Directories Directory Name

Description

bin

Contains dlls, locale files, and other binaries.

config

Contains the following configuration files: - WSHConfig.xml. Configuration file containing repository information and Web Services Hub parameters. - WSHConfig.xsd. XML schema definition file. UpdateConfigFile uses this schema definition file to validate the config.xml. - WSHLog.properties. Properties file used to control the logging in Web Services Hub.

configFileLoader

Contains the command line program used to update WSHConfig.xml file: - UpdateConfigFile. A command line program to update the default WSHConfig.xml file. - config.xml. A sample XML file that the UpdateConfigFile program uses.

docs

Contains the Web Services Provider documentation and API documentation in the following directories: - ClientProxy API. Contains the API documentation for client proxies generated from the WSH.wsdl. The client proxy classes are available in the samples directory. - axis. Contains the java doc for Axis client proxy APIs. - dotnet. Contains a directory csharp, which contains Microsoft Developer Network (MSDN) style documents for C# client proxy APIs. - WebServicesProvider.pdf. Web Services Provider Guide.

javalib

Contains JAR files.

jboss-3.2.1

Contains JBoss installation files. This directory also contains the following files, which contain Web Services Hub and PowerCenter data: - WSHInstall.properties. Located in the server\default\conf folder. - PowerCenter.war. Located in the server\default\deploy folder.

logs

Contains the log files generated by Web Services Hub.

samples

Contains the following sample client applications and readme file: - axis. Contains the Axis client proxy classes and sample client applications developed in Java using these client proxy classes. - dotnet. Contains a csharp directory with the .Net client proxy classes for C# and sample client applications developed in C# using these client proxy classes.

Step 1. Install the Web Services Hub

11

Table 2-1. Web Services Hub Installation Directories Directory Name

Description

ssl

Contains the keystore file required for HTTPS support.

Note: The Web Services Hub installation directory contains a file, WSH.wsdl, which describes the Batch Web Services and the Metadata Web Services.

12

Chapter 2: Installing and Configuring Web Services Hub

Step 2. Configure the Web Services Hub Before you start theWeb Services Hub, you need to configure the following information: ♦

Environment variables

♦

Configuration file

♦

Logging properties

Configuring Environment Variables You configure environment variables on Windows and UNIX. Before you configure environment variables, verify that Java 2 Platform is installed. For more information, see “Before You Begin” on page 8.

Configuring Environment Variables on Windows After you install the Web Services Hub on Windows, you must set the JAVA_HOME and PATH environment variables. ♦

JAVA_HOME. Set JAVA_HOME to your Java home directory, which is the root directory that contains the JDK files.

♦

PATH. Add JAVA_HOME\bin to your system PATH.

Configuring Environment Variables on UNIX After you install the Web Services Hub on UNIX, you set the WSH_HOME, JAVA_HOME, PATH, and shared library environment variables. Set the JAVA_OPTS environment variable if you install the Web Services Hub on HP-UX Itanium. WSH_HOME. Set WSH_HOME to your Web Services Hub installation directory. Use the following syntax to set JAVA_HOME environment variable: UNIX Shell

Description

C shell

setenv WSH_HOME <Web Services Hub installation path>

Bourne shell

export WSH_HOME <Web Services Hub installation path>

JAVA_HOME. Set JAVA_HOME to your Java home directory, which is the root directory that contains the JDK files. Use the following syntax to set JAVA_HOME environment variable: UNIX Shell

Description

C shell

setenv JAVA_HOME <Java installation path>

Bourne shell

export JAVA_HOME=<Java installation path>

Step 2. Configure the Web Services Hub

13

Note: Ensure that you set JAVA_HOME to the Java home directory, not to the JRE directory.

PATH. Add JAVA_HOME\bin to your system PATH. Use the following syntax to add JAVA_HOME to your PATH: Operating System Solaris and Linux

HP-UX

AIX

UNIX Shell

Description

C shell

setenv PATH <JAVA_HOME>/bin:${PATH}

Bourne shell

export PATH=<JAVA_HOME>/bin:${PATH}

C shell

setenv PATH <JAVA_HOME>/bin:${SHLIB_PATH}

Bourne shell

export PATH=<JAVA_HOME>/bin:${SHLIB_PATH}

C shell

setenv PATH <JAVA_HOME>/bin:${LIBPATH}

Bourne shell

export PATH=<JAVA_HOME>/bin:${LIBPATH}

Shared Library. Use the following syntax to set the shared library environment variables: Operating System Solaris and Linux

HP-UX

AIX

UNIX Shell

Description

C shell

setenv LD_LIBRARY_PATH <WSH_HOME>/bin:${LD_LIBRARY_PATH}

Bourne shell

export LD_LIBRARY_PATH=<WSH_HOME>/ bin:${LD_LIBRARY_PATH}

C shell

setenv SHLIB_PATH <WSH_HOME>/bin:${SHLIB_PATH}

Bourne shell

export SHLIB_PATH=<WSH_HOME>/bin:${SHLIB_PATH}

C shell

setenv LIBPATH <WSH_HOME>/bin:${LIBPATH}

Bourne shell

export LIBPATH=<WSH_HOME>/bin:${LIBPATH}

JAVA_OPTS. Use the following syntax to set JAVA_OPTS environment variable when you install the Web Services Hub on HP-UX Itanium: Operating System

UNIX Shell

Description

HP-UX Itanium

C shell

setenv JAVA_OPTS "-Xmx512m -Xms256m -d64"

Bourne shell

export JAVA_OPTS="-Xmx512m -Xms256m -d64"

Updating Static Properties Manually edit Web Services Hub static properties, such as port number and host name, in WSHConfig.xml and WSH.wsdl.

14

Chapter 2: Installing and Configuring Web Services Hub

Editing WSHConfig.xml Manually edit the properties in WSHConfig.xml in the Web Services Hub \config directory. When you start the Web Services Hub, it registers these properties. To edit WSHConfig.xml: 1.

Locate WSHConfig.xml in the Web Services Hub \config directory.

2.

Open it with any text editor and configure the following parameters: Table 2-2. WSHConfig.xml Parameters

3.

Parameter

Description

InternalHostName

The host name at which the Web Services Hub listens for connections from the PowerCenter Server. Default is the Web Services Hub host name.

InternalPortNumber

The port number at which the Web Services Hub listens for connections from the PowerCenter Server. Default is 5555.

URLScheme

Indicates the value that you configure for JBoss: HTTP or HTTPS. Default is http.

HubHostName

The name of the machine hosting the Web Services Hub. Default is the Web Services Hub host name.

HubPortNumber

The port number at which the Web Services Hub runs in JBoss. Default is 7333.

Save and close the file.

Editing WSH.wsdl Manually edit properties in WSH.wsdl in the Web Services Hub \<WSH_HOME>\ directory. To edit WSH.wsdl: 1.

Locate WSH.wsdl in the WSH_HOME directory.

2.

Change to the name of the machine hosting the Web Services Hub.

3.

Verify that the port number matches the hub port number in WSHConfig.xml.

Rules and Guidelines Use the following rules and guidelines when you manually update WSHConfig.xml and WSH.wsdl: ♦

Service requests fail if you use WSH.wsdl to generate proxy classes, and you do not update in WSH.wsdl.

♦

Stop the Web Services Hub to update any static parameter in WSHConfig.xml.

♦

The Web Services Hub may not properly update dynamic parameters if you edit them manually. This can cause unexpected results.

Step 2. Configure the Web Services Hub

15

Configuring Logging Properties The Web Services Hub logs events to a text file, wsh.log, in the Web Services Hub \logs directory. Configure the following logging properties in WSHLog.properties, located in the \config directory. To configure logging properties: 1.

Locate WSHLog.properties in the Web Services Hub \config directory.

2.

Open it with any text editor and update the following parameters: Table 2-3. WSHLog.properties Parameters

3.

Parameter

Description

WSHLogger

Logging levels are fatal, error, warning, info, and debug. Default is info.

MaxFileSize

The maximum size of the log file. Default is 500 KB.

MaxBackupIndex

If the log size exceeds the maximum configured size, the Web Services Hub appends a ‘1’ to the file name and creates a new file. When the log file reaches that size, the Web Services Hub renames the file wsh.log.1 and creates a new file named wsh.log to continue logging messages. Default is 10.

Save and close the file.

Note: When you use debug logging, the Web Services Hub logs verbose messages into the log

file. To avoid overwriting logging messages, increase the maximum file size and the maximum backup index. For more information about the Web Services Hub log file, see “Web Services Hub Log File” on page 43.

Configuring the Web Services Hub for HTTPS By default, JBoss provides support for HTTP. If you want to run client applications using HTTPS, you can configure JBoss for HTTPS. The Web Services Hub uses HTTPS to encrypt messages received from and sent to web service clients. The Web Services Hub also provides server authentication through HTTPS. Complete the following steps to configure the Web Services Hub for HTTPS: 1.

Configure jboss-service.xml to use HTTPS.

2.

Configure WSHConfig.xml to use HTTPS.

3.

Replace the dummy keystore file.

Step 1. Edit jboss-service.xml Edit jboss-service.xml to uncomment HTTPS entries and configure WSH_HOME.

16

Chapter 2: Installing and Configuring Web Services Hub

To edit jboss-service.xml: 1.

Find jboss-service.xml. You might find it in a location similar to the following path: C:\ <WSH_HOME>\jboss-3.2.1\server\default\deploy\jbossweb-tomcat.sar\METAINF\

2.

Uncomment the following entry in jboss-service.xml, and change WSH_HOME in the "KeyStoreURL" to the Web Services Hub installation directory: <arg type="java.lang.String" value="RMI+SSL"/> WSH_HOME\ssl\wsh.keystore changeit -->

3.

Uncomment the following entry, and update the port number. The port number should match the hub port number in WSHConfig.xml. -->

4.

Comment the following entry in jboss-service.xml:
Step 2. Configure the Web Services Hub

17

connectionTimeout="20000" useURIValidationHack="false" />

Note: You can use one type of protocol. If you use HTTP, comment the HTTPS connector

element. If you use HTTPS, comment the HTTP connector element.

Step 2. Configure the Web Services Hub to Use HTTPS Change the URL scheme in WSHConfig.xml to HTTPS. If you use the default installation, you can find WSHConfig.xml in the following location: C:\<WSH_HOME>\config\WSHConfig.xml

http

Step 3. Replace the Keystore File Replace the dummy keystore file, wsh.keystore, with a keystore file containing actual certificates. If you use the default installation, you can find wsh.keystore in the following location: C:\<WSH_HOME>\ssl

18

Chapter 2: Installing and Configuring Web Services Hub

Step 3. Start the Web Services Hub To start the Web Services Hub, you start JBoss Application Server. After you start JBoss, you can verify that the Web Services Hub installation is successful.

Starting the Web Services Hub When you start the JBoss Application Server, the command window shows the commands to start JBoss and the Web Services Hub. The following message in the command window indicates that the Web Services Hub successfully started: INFO [STDOUT] log prop path is /InformaticaWebServiceHub7.1.1/config/WSHLog.properties

Note: You can disregard the error message that follows startup: ERROR invalid console appender config detected, console stream is looping To start the Web Services Hub on Windows: 1.

From the Windows Start menu, choose Programs-Informatica Web Services Hub 7.1.1Start. The command window opens and displays the startup commands.

To start the Web Services Hub on UNIX: 1.

Navigate to the drive and directory where you installed JBoss Application Server and go to the \bin directory. For example, if you accepted the default installation when you installed the Web Services Hub, go to the following directory: /InformaticaWebServiceHub7.1.1/jboss-3.2.1/bin

2.

From the command prompt, type run.sh.

Verifying the Web Services Hub Installation After you start the JBoss Application Server, you can verify the Web Services Hub installation. You can verify the installation by opening the Web Services Hub console.

Step 3. Start the Web Services Hub

19

Figure 2-1 shows the Web Services Hub console: Figure 2-1. Web Services Hub Console

The home page displays the following services: ♦

Realtime Web Services

♦

Batch Web Services

♦

Metadata Web Services

If the Web Services Hub does not start, you can check the wsh.log file in the \logs directory for troubleshooting information. Note: You must run UpdateConfigFile to register repositories with the Web Services Hub

before you can see the services in the Realtime Web Services link. To verify the Web Services Hub installation on Windows: 1.

From the Windows Start menu, choose Programs-Informatica Web Services Hub 7.1.1Console.

To verify the Web Services Hub installation on UNIX: 1.

Open the following URL in the browser: http:///PowerCenter For example, http://Benz:7333/PowerCenter

Stopping the Web Services Hub Use the following procedures to stop the Web Services Hub. To stop the Web Services Hub on Windows: 1.

From the Windows Start menu, choose Programs-Informatica Web Services Hub 7.1.1Stop.

To stop the Web Services Hub on UNIX: 1. 20

Close the command window.

Chapter 2: Installing and Configuring Web Services Hub

Step 4. Run UpdateConfigFile Complete the following steps after you verify that Web Services Hub starts: 1.

Update config.xml. Enter repository information for each repository that you want to register with the Web Services Hub. You can add multiple repositories to config.xml. Also enter Web Services Hub parameters for the session expiry and maximum log buffer size.

2.

Run UpdateConfigFile. When you run UpdateConfigFile, it reads config.xml and updates WSHConfig.xml with the values. If you add or update a repository, it encrypts the repository password.

UpdateConfigFile and config.xml are in the Web Services Hub \configFileLoader directory. To update config.xml: 1.

Locate config.xml in the Web Services Hub \configFileLoader directory.

2.

Open it with any text editor and update the following parameters: Table 2-4. config.xml Parameters

3.

Parameter

Description

Name

Repository name that you want to register with the Web Services Hub.

ServerHostName

Name of the machine hosting the Repository Server.

ServerPortNumber

Repository Server port number.

Username

Repository user name.

Password

Repository password. UpdateConfigFile encrypts this when you load WSHConfig.xml.

SessionExpiryPeriod

The maximum time in seconds that Web Services Hub resources can remain idle while logging in. Default is 3600.

MaxLogBufferSize

The maximum buffer limit in Kilobytes (KB) for workflow and session log segments. Default is 1024.

Save and close the file.

After you add repository entries into config.xml, you can run UpdateConfigFile. To run UpdateConfigFile: 1.

Verify that the Web Services Hub is running.

2.

From a command line, go to the \configFileLoader directory.

3.

Run UpdateConfigFile to update WSHConfig.xml. On Windows, use the following syntax to update WSHConfig.xml: UpdateConfigFile [-s | -ns] <WSH Hostname> <WSH Port number> [-update | -delete] [config.xml | Repository Name]

On UNIX, use the following syntax to update WSHConfig.xml: Step 4. Run UpdateConfigFile

21

UpdateConfigFile.sh [-s | -ns] <WSH Hostname> <WSH Port number> [-update | -delete] [config.xml | Repository Name]

Note: Values in the format [x | y] represent the options you can use for the command

parameter. Table 2-5 lists UpdateConfigFile options: Table 2-5. UpdateConfigFile Options

4.

Option

Required/ Optional

-s | -ns

Required

Indicates secure or nonsecure mode of communication. Secure mode uses HTTPS, and nonsecure mode uses HTTP. Enter -ns for nonsecure mode. Enter -s for secure mode.

WSH Hostname

Required

The name of the machine hosting the Web Services Hub.

WSH Port number

Required

Web Services Hub port number. The default port number for HTTP is 7333.

-update | -delete

Required

Enter -update to update the WSHConfig.xml file. Enter -delete to delete a repository from the WSHConfig.xml file.

config.xml | Repository Name

Required

If you update parameters in WSHConfig.xml, enter config.xml to specify that file, which contains the parameter values that you want to update. If you want to delete a repository from WSHConfig.xml, enter a repository.

Description

Press Enter. If UpdateConfigFile updates WSHConfig.xml, the command prompt displays the following message: Config file successfully updated

Rules and Guidelines Use the following rules and guidelines when you run UpdateConfigFile:

22

♦

If you configure the Web Services Hub to use HTTPS, use the secure option, -s, when you run UpdateConfigFile.

♦

Always use UpdateConfigFile to update dynamic parameters in the WSHConfig.xml. The Web Services Hub may not properly update dynamic parameters if you edit them manually. This can cause unexpected results.

Chapter 2: Installing and Configuring Web Services Hub

Step 5. Register the Web Services Hub If you use Real-time Web Services, you register a Web Services Hub with the repository. When you register Web Services Hub, you identify the host name and port number of the machine hosting Web Services Hub. Note: You can register one Web Services Hub with a repository. To register the Web Services Hub: 1.

In the Workflow Manager, connect to the repository.

2.

Choose Server-WebServices Hub Config. The WebServices Hub Browser appears.

3.

Click New to register a new hub. The Web Services Hub Editor dialog box appears. Figure 2-2. Web Services Hub Editor

Step 5. Register the Web Services Hub

23

4.

Configure the properties as described in Table 2-6: Table 2-6. Web Services Hub Properties

5.

24

Property

Description

Server Name

Web Services Hub name.

Host Name / IP Address

The host name or IP address of the Web Services Hub.

Resolved IP Address

The resolved IP address.

Port Number

Internal port number of the Web Services Hub. Default is 5555.

Protocol

The transport protocol. The Web Services Hub supports TCP/IP.

Timeout (seconds)

The timeout value for the connection between the PowerCenter Server and the Web Services Hub. Default is 60.

Resolve Server

If you do not know the IP address, enter the host name and click Resolve Server to resolve the IP address. You can also enter the IP address in the Host Name/IP Address field and use Resolve Server to resolve the host name.

Click OK.

Chapter 2: Installing and Configuring Web Services Hub

Changing the Web Services Hub Port Number The Web Services Hub starts when you start JBoss. By default the Web Services Hub starts on port 7333. If you want to change the port number of the Web Services Hub, you must stop the Web Services Hub and edit the port number to match in the following files: ♦

jboss-service.xml

♦

WSH.wsdl

♦

WSHConfig.xml

Editing the Port Number in jboss-service.xml Find jboss-service.xml. You might find it in a location similar to the following path: C:\<WSH_HOME>\jboss-3.2.1\server\default\deploy\jbossweb-tomcat.sar\META-INF\ If you use HTTP, edit the following entry in jboss-service.xml to configure the port number:

If you use HTTPS, edit the following entry in jboss-service.xml to configure the port number: -->

Note: You can use one type of protocol. If you use HTTP, comment the HTTPS connector

element. If you use HTTPS, comment the HTTP connector element.

Changing the Web Services Hub Port Number

25

Editing the Port Number in WSH.wsdl If you use the default installation, find WSH.wsdl in the following location: C:\<WSH_HOME>\ Edit the port number for the Metadata port and the DataIntegration port. The following excerpt is from a default WSH.wsdl file: <wsdl:service name="WebServicesHub"> <wsdl:port name="Metadata" binding="impl:MetadataServiceSoapBinding"> <wsdlsoap:address location="http://localhost:7333/ PowerCenter/services/Metadata"/> <wsdl:port name="DataIntegration" binding="impl:DataIntegrationServiceSoapBinding"> <wsdlsoap:address location="http://localhost:7333/ PowerCenter/services/DataIntegration"/>

Editing the Port Number in WSHConfig.xml If you use the default installation, find WSHConfig.xml in the following location: C:\<WSH_HOME>\config\ Edit the entry for the HubPortNumber. The following excerpt is from a default WSHConfig.xml file:

7333

26

Chapter 2: Installing and Configuring Web Services Hub

Uninstalling Web Services Hub You can use one of the following methods to uninstall the Web Services Hub: ♦

Run setup.exe on the PowerCenter installation CD. The Informatica Web Services Hub Setup detects existing installed components and prompts you to remove them.

♦

Use the Add/Remove Programs dialog box. In the Windows Control Panel, choose Add/ Remove Programs, and then choose Informatica Web Services Hub 7.1.1. The Informatica Web Services Hub Setup detects existing installed components and prompts you to remove them. You can access the Add/Remove Programs dialog box only if you have system administrative privileges.

Note: The uninstall program does not remove path and environment settings that you configured for the Web Services Hub.

Uninstalling Web Services Hub

27

28

Chapter 2: Installing and Configuring Web Services Hub

Chapter 3

Understanding Web Services Provider This chapter includes the following topics: ♦

Overview, 30

♦

Web Services Provider Architecture, 32

29

Overview Web Services Provider provides some of the PowerCenter Server functionality through a service-oriented architecture. It is comprised of a Web Services Hub and web services hosted by the Web Services Hub.

Web Services Hub The Web Services Hub is a PowerCenter Service gateway for external clients. It processes SOAP requests from web service clients that want to access PowerCenter web services. It receives requests from web service clients and passes them to the PowerCenter Server or the Repository Server. The PowerCenter Server or the Repository Server process the requests and send a response to the web service client through the Web Services Hub. The content of the response depends on the type of service. The Web Services Hub hosts the following web services: ♦

Batch Web Services. Run and monitor workflows and administer the PowerCenter Server.

♦

Metadata Web Services. Log in to the repository and browse metadata.

♦

Real-time Web Services. Create service workflows that allow you to read and write messages to a web service client through the Web Services Hub.

For more information about the Web Services Hub, see “Understanding the Web Services Hub” on page 35.

Batch Web Services Batch Web Services is a web-enabled version of the PowerCenter Server and the Workflow Monitor. Use Batch Web Services to perform some Load Manager capabilities, such as running and monitoring PowerCenter workflows and administering the PowerCenter Server. Write web service client applications using the functions available with Batch Web Services. Batch Web Services provides the following types of functions: ♦

PowerCenter Server functions. Perform PowerCenter Server functions, such as connecting to the PowerCenter Server or getting server properties.

♦

Workflow functions. Perform workflow functions, such as starting, stopping, or scheduling workflows.

♦

Task functions. Perform task functions, such as starting or stopping a task.

♦

Monitoring and reporting functions. Perform monitoring and reporting functions, such as monitoring workflows and session performance.

♦

Log functions. Perform log functions, such as getting workflow or session logs.

For more information about Batch Web Services functions, see “Using Batch Web Services Functions” on page 55.

30

Chapter 3: Understanding Web Services Provider

Metadata Web Services Metadata Web Services provides the functions that retrieve metadata from PowerCenter repositories. Write web service client applications using the functions available with Metadata Web Services. Metadata Web Services provides the following types of functions: ♦

Authentication functions. Perform authentication functions to log in and log out of the repository.

♦

Browsing functions. Perform browsing functions to get information necessary to run workflows, such as retrieving repositories, folders, and workflows.

For more information about Metadata Web Services functions, see “Using Metadata Web Services Functions” on page 49.

Real-time Web Services Use Real-time Web Services to expose transformation logic as a service. Write client applications to run Real-time Web Services. You can create a service mapping to receive a message from a web service client, transform it, and write it to any target PowerCenter supports. You can also create a service mapping with both a web service source and target definition to receive a message request from a web service client, transform the data, and send the response back to the web service client. The source and target definitions represent service operations, where the source defines the user request, and the target defines the response. After you create a mapping, you can create a service workflow. A service workflow is a workflow enabled for web services. Configure service information, and add sessions to the workflow. When you save the workflow, the Web Services Hub publishes the service. The PowerCenter Server can perform parallel processing of both request-response and one-way services. For more information about creating service mappings, see “Working with Service Mappings” on page 81. For more information about creating services, see “Working With Service Workflows” on page 99.

Overview

31

Web Services Provider Architecture Web Services Provider is comprised of a Web Services Hub and web services hosted by the Web Services Hub. These web services communicate with the PowerCenter Server and the Repository Server. Figure 3-1 shows Web Services Provider architecture: Figure 3-1. Web Services Provider Architecture Web Service Client Security Gateway

Web Service Client

Web Services Hub Service Workflow Real-time Web Services

PowerCenter Server Workflow

Batch Web Services Metadata Web Services Application Server

Repository Server Repository Real-time Web Services Batch Web Services Metadata Web Services Repository Server Communication

The Web Services Hub processes service requests in similar ways for the Real-time Web Services, Batch Web Services, and Metadata Web Services. The following process describes the architecture of Web Services Provider: 1.

A web service client sends a SOAP message to the Web Services Hub to run a service.

2.

The Web Services Hub authenticates the web service client based on repository user name and password.

3.

If the service request is for a real-time service, the Web Services Hub generates a message ID and sends the SOAP request to the PowerCenter Server. If the service request is for a batch service, the Web Services Hub sends the request to the PowerCenter Server to process. The request may be to run or monitor a workflow, start or stop the server, or get log information. If the service request is for a metadata service, the Web Services Hub sends the request to the Repository Server to process. The request may be to log in or log out of the repository.

32

Chapter 3: Understanding Web Services Provider

4.

The PowerCenter Server processes the request. If the request is for a real-time service, the PowerCenter Server sends the processed data to the Web Services Hub and uses the message ID to correlate the request with the response. The Web Services Hub sends a SOAP response to the web service client. If the service request is for a batch or metadata service, the Web Services Hub sends a response based on the request. For example, if you request the PowerCenter Server connection state, the Web Services Hub returns a connection state, such as aborted, connected, or disconnected.

The PowerCenter Server and Web Services Hub communicate with the Repository Server throughout the process.

Web Services Provider Architecture

33

34

Chapter 3: Understanding Web Services Provider

Chapter 4

Understanding the Web Services Hub This chapter includes the following topics: ♦

Overview, 36

♦

Using the Web Services Hub Console, 37

♦

Web Services Hub Security, 41

♦

Web Services Hub Log File, 43

♦

SOAP Fault Handling, 45

♦

Session Maintenance, 47

35

Overview The Web Services Hub is a PowerCenter Service gateway for external clients. It exposes PowerCenter functionality through a service-oriented architecture. It receives requests from web service clients and passes them to the PowerCenter Server or the Repository Server. The PowerCenter Server or the Repository Server process the requests and send a response to the web service client through the Web Services Hub. The Web Services Hub hosts Batch Web Services, Metadata Web Services, and Real-time Web Services. For more information, see “Understanding Web Services Provider” on page 29. You install the Web Services Hub on an application server and configure information such repository login, session expiry, and log buffer size. The Web Services Hub connects to the Repository Server and the PowerCenter Server through TCP/IP. Web service clients log in to the Web Services Hub through HTTP(s). The Web Services Hub authenticates the client based on repository user name and password. You can use the Web Services Hub console to view service information and download WSDL files necessary for running services and workflows.

36

Chapter 4: Understanding the Web Services Hub

Using the Web Services Hub Console You can use the Web Services Hub console to view service information and download WSDL required to run services. You can connect to the Web Services Hub from any browser. Use the following endpoint URL to connect to the Web Services Hub console: http://<Web Services Hub Host Name:Port Number>/PowerCenter/services Figure 4-1 shows the Web Services Hub console: Figure 4-1. Web Services Hub Console

Batch and Metadata Web Services You can click the Batch Web Services or Metadata Web Services links to view a list of functions available with each service. The function signatures are defined as XML in WSH.wsdl. Download WSH.wsdl from the Web Services Hub to generate code for applications that access the batch and metadata services. The following sample shows the signature for the Login function:

<sequence> <element name="RepositoryName" type="xsd:string"/> <element name="UserName" type="xsd:string"/> <element name="Password" type="xsd:string"/> <element name="Login" type="impl:LoginRequest"/> <element name="LoginReturn" type="xsd:string"/>

Using the Web Services Hub Console

37

Real-time Services You can view service information published by the Web Services Hub. You view information such as service and workflow name, service type, and protected status. Before you can build a client application to run a service, you need the following information from the Web Services Hub: ♦

Service name. Identify the service you want to run.

♦

WSDL and referenced schemas. Download the WSDL and referenced schemas associated with the service. You can view the generated WSDL, but you cannot view the referenced schema.

♦

Protected status. If the service is protected, you must send a login request to the Web Services Hub.

Click the Realtime Web Services link to view service information. You can view valid and invalid services. Figure 4-2 shows the Transformation Services page: Figure 4-2. Transformation Services Page

38

Chapter 4: Understanding the Web Services Hub

Table 4-1 describes the columns displayed on the Transformation Services page: Table 4-1. Transformation Services Page Column

Description

Service Name

Service name defined in the service workflow.

Repository Name

Repository containing the service.

Folder Name

Folder containing the service.

Workflow Name

Service workflow associated with the service.

WSDL

WSDL published by the Web Services Hub to run the service.

To view additional service information, such as the runnable and protected values, you can click on a service name. Figure 4-3 show the Transformation Service Description page: Figure 4-3. Transformation Service Description Page

Table 4-2 describes the properties on the Transformation Service Description page: Table 4-2. Transformation Service Description Page Property

Description

Service Name

Service name defined in the service workflow.

Repository Name

Repository containing the service.

Folder Name

Folder containing the service.

Workflow Name

Service workflow associated with the service.

Is Runnable

Indicates the runnable value. For more information about runnable services, see “Creating and Configuring a Service” on page 101.

Using the Web Services Hub Console

39

Table 4-2. Transformation Service Description Page

40

Property

Description

Is Protected

Indicates whether the service is protected or public. For more information about protected services, see “Creating and Configuring a Service” on page 101.

Is One Way

Indicates whether the service is one-way or request-response.

Service WSDL

WSDL published by the Web Services Hub to run the service.

Chapter 4: Understanding the Web Services Hub

Web Services Hub Security The Web Services Hub has the following levels of security: ♦

Encryption. The Web Services Hub encrypts the repository login information in the configuration file used to connect to the repository. It also encrypts the repository password for web service clients to use to request services.

♦

Authentication. The Web Services Hub authenticates requests from web service clients based on the user name and password. A web service client logs in to the repository through a SOAP request sent to the Web Services Hub. This request must contain a repository name, repository user name, and password. The Web Services Hub authenticates the 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 real-time 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 service workflow is running. For more information about access to services, see “Configuring the Service” on page 101.

Note: If a real-time service is not protected, the Web Services Hub does not perform

authentication or authorization for service requests.

Encrypting Repository Information Web Services Provider encrypts repository information in the configuration file and in responses to web service clients for login requests.

Encrypting the Configuration File Before the Web Services Hub can connect to a repository, you must load repository information into the configuration file, WSHConfig.xml. Use the command line program, UpdateConfigFile, to load repository information into the configuration file. UpdateConfigFile encrypts the password before storing it in the file. For more information about UpdateConfigFile, see “Step 4. Run UpdateConfigFile” on page 21.

Encrypting Log in Requests Before a web service client can request to run a web service it must log in to the Web Services Hub. The Web Services Hub uses the following process to provide a web service client with encrypted credentials to run services. 1.

A web service client sends a login request to the Web Services Hub. This request contains a repository name, user name, and password.

2.

The Web Services Hub authenticates the user and sends a login response containing credentials that the web service client can use for subsequent requests.

Web Services Hub Security

41

3.

42

When the web service client submits a request to run a service, it includes the encrypted credentials in the header element.

Chapter 4: Understanding the Web Services Hub

Web Services Hub Log File The Web Services Hub creates a log for status and error messages related to tasks, such as service initialization, task execution, and connection status. You can troubleshoot problems by examining error messages in this log. The Web Services Hub generates a log file, wsh.log, in the Web Services Hub installation logs directory.

Configuring the Log File You configure log information in the file, WSHLog.properties. You can configure the size of the log and the level of logging. By default, the size of wsh.log is 100 KB. If the log size exceeds the maximum configured size, the Web Services Hub appends a ‘1’ to the file name and creates a new file. When the log file reaches that size, the Web Services Hub renames the file wsh.log.1 and creates a new file named wsh.log to continue logging messages. By default, the Web Services Hub can create up to 10 files. You can configure logging levels for the Web Services Hub: ♦

Fatal. Indicates the Web Services Hub installation is missing some files. Fatal messages have the highest severity level.

♦

Error. Indicates the Web Services Hub failed to perform an operation or respond to a request.

♦

Warning. Indicates the Web Services Hub is performing an operation that may cause an error. This can cause repository inconsistencies.

♦

Information. Indicates the Web Services Hub is performing an operation that does not indicate errors or problems.

♦

Debug. Indicates Web Services Hub operations at the thread level. Debug messages generally record the success or failure of individual internal operations.

Note: When you use debug logging, the Web Services Hub logs verbose messages into the log

file. To avoid overwriting logging messages, increase the maximum file size and the maximum backup index. For more information about logging levels, see “Configuring Logging Properties” on page 16.

Viewing the Log File You can view the log files in the Web Services Hub \logs directory. Based on the log size you configure and the logging levels you configure, this directory may contain multiple files. The following messages are from a sample log file: 2004-03-17 13:58:05,308 [main] INFO - RepositoryDataManager::fetchRepositoryData FetchRepositoryData called for repository [WSProvider71] 2004-03-17 13:58:08,449 [main] ERROR - RepositoryDataManager::fetchRepositoryData Failed to fetch details of the workflow [ProcessOrderNew111], in folder [TestFolder] while fetching data for the repository [WSProvider71] :

Web Services Hub Log File

43

Note: The Web Services Hub also writes messages in the fault element of a SOAP response

when it cannot process the request. For more information about fault handling, see “SOAP Fault Handling” on page 45.

44

Chapter 4: Understanding the Web Services Hub

SOAP Fault Handling If the Web Services Hub cannot process a request, it sends a response to the web service client that contains error information indicating the cause of the error. The message target is based on the task the Web Services Hub was performing when it encountered the error: ♦

If the Web Services Hub cannot process a message in a service workflow, it writes messages to fault targets.

♦

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 contain error information.

Messages contain a message code, comprised of a prefix and code number, and the message text. For example, the message code “WSH_95005” has the associated message text “Invalid request parameter. Shutdown mode 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 “Web Services Hub Level Errors” on page 114.

SOAP Fault Header The Web Services Hub reports header related errors in the header fault element of a SOAP response header. The schema of this element is listed below: <ns1:HeaderFault xmlns:ns1=”http://www.informatica.com/PowerCenter”> <ErrorCode> error code error message

SOAP Fault Handling

45

SOAP Fault Body The SOAP fault body contains the following sub-elements: ♦

Faultcode. The faultcode determines if the error originates at the web service client or the PowerCenter Server. 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 PowerCenter Server, Web Services Hub, or repository.

♦

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> Client/Server Brief Description of Error <detail> <ns:WSHFaultDetails xmlns:ns=”www.informatica.com/PowerCenter”> <ErrorCode> Error Code <ExtendedDetails> Actual Error

46

Chapter 4: Understanding the Web Services Hub

Session Maintenance When you run Batch Web Services and Metadata Web Services, the Web Services Hub requires session maintenance to cache resources. The SOAP header in the SOAP message carries the session information facilitating session maintenance. The Web Services Hub uses the following SOAP header schema: <soap:header> <ns1:Context xmlns:ns1=”http://www.informatica.com/PowerCenter”> <SessionId> XYZ

The Session ID element contains the session information, which is a 128-bit UUID string. The client application does not send session information in the SOAP header of the Login function call for Metadata Web Services. The Web Services Hub response to the client login request contains a SOAP header with the Session ID. The client sends this Session ID in the SOAP header for all subsequent Metadata Web Services requests to the Web Services Hub. Similarly, the client application does not send session information in the SOAP header of the InitializeDIServerConnection function call of Batch Web Services. The Web Services Hub response to the client InitializeDIServerConnection request contains a SOAP header with the Session ID. The client then sends this Session ID in the SOAP header for all subsequent Batch Web Services requests to the Web Services Hub. Note: You can call the GetAllRepositories function of Metadata Web Services without setting

the SOAP header. The GetAllRepositories function of Metadata Web Services is the only function that does not require the Login function.

Session Maintenance

47

48

Chapter 4: Understanding the Web Services Hub

Chapter 5

Using Metadata Web Services Functions This chapter includes the following topics: ♦

Overview, 50

♦

Authentication Request Functions, 51

♦

Browsing Request Functions, 52

49

Overview When you log in to the Web Services Hub, it resolves the Repository Server host name and port number from the given repository name using this configuration file. You can use Metadata Web Services to retrieve metadata from the PowerCenter repositories. As part of the Web Services Hub, Metadata Web Services offers metadata functionality required for Batch Web Services. This includes accessing and browsing the PowerCenter repositories. Metadata Web Services provides authentication requests to authenticate users for accessing a repository. These requests allow you to log in and log out of the PowerCenter repositories. The log in process validates your user name and password to verify you have access to the repository and to what extent. For example, you might have administrator or user access to a repository. These access privileges determine your ability to access folders and the operations you can perform within the folders in the repository. The Logout function logs you out of the repository and deinitializes the connections to all PowerCenter Servers associated with this repository. If you do not log out of the repository, resources acquired by this user login will be released by session expiry employed by Web Services Hub. The Web Services Hub releases the connections to the PowerCenter Servers and repositories used by a client application experiencing a period of inactivity exceeding the Session Expiry period. You can also use Metadata Web Services to browse the PowerCenter repositories. Browsing requests allow you to get metadata such as folders, workflows, and tasks from the repositories. This chapter explains the functions that Metadata Web Services offers. The Web Services Hub services are doc/literal services. Functions in doc/literal services take an XML document and return an XML document. If you want to know more about the request and response XML documents for these functions, refer to WSH.wsdl. If you want to know more about client proxy functions generated from the WSH.wsdl with Axis and .Net web services toolkits, refer to the API documentation available in the docs directory. Note: DI Server refers to the PowerCenter Server.

50

Chapter 5: Using Metadata Web Services Functions

Authentication Request Functions Authentication requests validate user names and passwords to access the PowerCenter repository. For more information on PowerCenter repository security, see the PowerCenter Repository Guide. You can use the following authentication requests to access the PowerCenter repositories: ♦

Login

♦

Logout

Login The Login function authenticates user name and password for a specified repository. This is the first function a client application should call before calling any other functions. The GetAllRepositories function is an exception that you can call without calling the Login function. For more information on the GetAllRepositories function, see “GetAllRepositories” on page 53. The Login function returns the LoginHandle that the InitializeDIServerConnection function uses to connect to the PowerCenter Server and repository. The Login function requires repository name, user name, and password. After calling the Login function, the web service client application can work with both Metadata Web Services and Batch Web Services providing a single sign-on experience.

Logout The Logout function disconnects you from the repository and its PowerCenter Server connections. You can call this function once you are done calling Metadata and Batch Web Services functions to release resources at the Web Services Hub.

Authentication Request Functions

51

Browsing Request Functions Browsing requests allow you to browse the repository for information in folders, workflows, worklets. You can also get a list of repositories that are configured at the Web Services Hub. You can use browsing requests to perform the following tasks: ♦

Get all folders in a repository.

♦

Get all workflows in a folder.

♦

Get all worklets and session tasks.

♦

Get all servers configured for a repository.

♦

Get all repositories in the Web Services Hub configuration file.

GetAllFolders You can use the GetAllFolder function to retrieve all folders in a repository that your client application is logged into.

GetAllWorkflows Use the GetAllWorkflows function to get information about all workflows in a folder. A workflow is a set of instructions that tells the PowerCenter Server how to execute tasks, such as sessions, email notifications, and shell commands. Workflow information includes the name of the workflow, name of the folder in which the workflow resides, and whether the workflow is valid.

GetAllTaskInstances Use the GetAllTaskInstances function to get information about all worklets and session task instances in a workflow for a specified depth.

GetAllDIServers You can register one or more PowerCenter Servers with a repository to run workflows and sessions. In a multiple server environment, it is important to enter descriptive server names for each registered server to help users differentiate between servers. When you register multiple servers, you must have a unique server name, and a unique combination of host name and port number for each server in the repository. This function returns the PowerCenter Server names registered to a given repository.

52

Chapter 5: Using Metadata Web Services Functions

GetAllRepositories You can use the GetAllRepositories function to view all repositories configured at the Web Services Hub. Before a Web Services Hub client application can use a repository, configure the repository at the Web Services Hub by changing the Web Services Hub configuration file. For more information on configuring repositories at the Web Services Hub, see “Step 4. Run UpdateConfigFile” on page 21. Note: You can call the GetAllRepositories function with Metadata Web Services before logging into a repository.

Browsing Request Functions

53

54

Chapter 5: Using Metadata Web Services Functions

Chapter 6

Using Batch Web Services Functions This chapter includes the following topics: ♦

Overview, 56

♦

PowerCenter Server Functions, 57

♦

Workflow Functions, 59

♦

Task Functions, 61

♦

Monitoring and Reporting Functions, 62

♦

Log Functions, 64

55

Overview Batch Web Services functions allows you to start and stop existing workflows and tasks. You can schedule or unschedule existing workflows and tasks. You can get session statistics and performance data. You can retrieve workflow and session logs. And you can perform administrative operations, such as stopping the PowerCenter Servers. The complete set of Batch Web Services request functions consists of the following categories: ♦

PowerCenter Server functions

♦

Workflow functions

♦

Task functions

♦

Monitoring and Reporting functions

♦

Log functions

Note: Log segments obtained by Batch Web Services function calls are either in PowerCenter Server code page or in UTF-8.

56

Chapter 6: Using Batch Web Services Functions

PowerCenter Server Functions The PowerCenter Server functions let you get details about the PowerCenter Server.

InitializeDIServerConnection Use this function to initialize a connection to a PowerCenter Server. This function passes the login information (repository name, user name, and password) to the Web Services Hub in the form of a login handle and PowerCenter Server name. You obtain the login handle by using the Login function of the Metadata Web Service. After calling the Login function, the web service client application can work with both Metadata Web Services and Batch Web Services to provide a single sign-on.

DeinitializeDIServerConnection Use this function in conjunction with InitializeDIServerConnection to disconnect the client application from the PowerCenter Server. This is the last function you call to Batch Web Services. After calling this function, the client cannot call any other functions of Batch Web Services unless it again calls the InitializeDIServerConnection function. You can call this function when you finish using Batch Web Services in order to free resources at the Web Services Hub.

PingDIServer You can use this function to determine whether the PowerCenter Server is running. The return values are ALIVE or FAIL.

GetDIServerConnectionState You can use this function to get the state of connection to the PowerCenter Server. This function returns the following values of the connection state: ♦

ABORTED

♦

CONNECTED

♦

CONNECTING

♦

DISCONNECTED

♦

DISCONNECTING

♦

LOST

StopDIServer You can use this function to shut down the PowerCenter Server.

PowerCenter Server Functions

57

You can stop the PowerCenter Server in one of the following modes: ♦

COMPLETE. The server waits for all the running workflows to complete before shutting down

♦

STOP. The server stops all the running workflows, and then it shuts down.

♦

ABORT. The server aborts all running workflows before shutting down.

Note: You can optionally specify the reason for the shutdown.

GetDIServerProperties You can use this function to get the properties of the PowerCenter Server. The PowerCenter Server properties include the following information:

58

♦

PowerCenter Server name

♦

PowerCenter Server version

♦

PowerCenter Server product name

♦

Timestamp on the PowerCenter Server

♦

PowerCenter Server startup time

♦

Repository name

♦

Data movement mode (ASCII or Unicode)

♦

Whether the PowerCenter Server can debug mappings

Chapter 6: Using Batch Web Services Functions

Workflow Functions The Workflow functions let you perform tasks such as starting, stopping, and scheduling workflows.

StartWorkflow You can use this function to start the entire workflow, or you can start a workflow from a task. When you start a workflow from a task, the PowerCenter Server runs the workflow from the selected task to the end of the workflow. When you want to start a workflow from a task, you need to specify the task instance path. 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 the form, WorkletName.TaskName. For instance, if worklet ‘A’ is a worklet in a workflow. Worklet ‘A’ contains another worklet, ‘B,’ and task ‘C’ is a task within worklet ‘B,’ then the task instance path for task ‘C’ is (A.B.C).

StopWorkflow You can use this function to stop a running workflow. When you stop a workflow, the PowerCenter Server tries to stop all the tasks that are currently running in the workflow. If the workflow contains a worklet, the PowerCenter Server 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 specifying an “isAbort boolean as true.” Normally, you abort workflows only if the PowerCenter Server fails to stop the workflow.

ScheduleWorkflow You can use this function to schedule a workflow. You can schedule any workflow that does not run on demand.

UnscheduleWorkflow You can use this function to unschedule a workflow.

WaitTillWorkflowComplete You can use this function to wait for a running workflow to complete on the PowerCenter Server.

Workflow Functions

59

ResumeWorkflow You can use this function to resume a suspending or suspended workflow on the PowerCenter Server. You can choose to suspend a workflow or worklet if a task fails. After you fix the failed task, you can resume the workflow. When you resume a workflow, the PowerCenter Server finds the failed task, runs the task again, and continues running the rest of the tasks in the workflow path.

60

Chapter 6: Using Batch Web Services Functions

Task Functions Task functions let you perform tasks such as starting and stopping individual tasks in a workflow.

StartTask You can use this function to start and run a specific task within a workflow.

StopTask You can use this function to stop a task running on a PowerCenter Server. You can stop or abort a task, workflow, or worklet at any time. You can also abort a running task by specifying an “isAbort boolean as true.” Normally, you abort tasks only if the PowerCenter Server fails to stop the task. 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 the form, WorkletName.TaskName. For instance, if worklet ‘A’ is a worklet in a workflow. Worklet ‘A’ contains another worklet, ‘B,’ and task ‘C’ is a task within worklet ‘B,’ then the task instance path for task ‘C’ is (A.B.C).

WaitTillTaskComplete You can use this function to wait for a running task to complete on a PowerCenter Server.

ResumeTask You can use this function to resume a suspending or suspended task (of worklet type only) on the PowerCenter Server.

Task Functions

61

Monitoring and Reporting Functions The Monitoring and Reporting functions let you monitor session statistics, session performance data, and get details of workflows, tasks, and sessions. For example, you can use these functions to monitor load statistics for each target in a mapping.

MonitorDIServer You can use this function to retrieve the status of the PowerCenter Server, details of active and/or scheduled workflows, details of the tasks within the workflows, details of links within the workflows, and the timestamp for this information. You can call this function in three 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.

GetWorkflowDetails You can use this function to get the details of a given workflow. If the workflow is running, you get the detail of the running workflow. If the workflow is not running, you get the detail of the last run of this workflow. Workflow details include the name of the folder, workflow, workflow log file, and user that runs the workflow. It includes workflow run type, log file code page, start time, end time, run status, run error code, and run error message.

GetTaskDetails You can use this function to retrieve the details of a task instance from the PowerCenter Server. If the enclosing workflow is running and the task instance has already run, you get the detail of the current task instance in the running workflow. If the enclosing workflow is not running, you get the task detail of the last workflow run. The task detail information includes folder name, workflow name, task instance name, task type, start time, run status, run error code, and run error message, GetTaskDetails gives you both task type and a boolean specifying whether task is of type session.

GetSessionStatistics You can use this function to get the statistics of a session running on the PowerCenter Server. When the session is not running, this function provides the statistics of the most recently run session.

62

Chapter 6: Using Batch Web Services Functions

Session statistics includes folder name, workflow name, task instance, mapping, session status, task run status, first error code and message, the number of transformation errors, the number of successful and failed rows for source and target, transformation instance name, the number of applied, affected, and rejected rows, throughput, last error, and start and end time for the session. Note: You call this function only for Session tasks.

GetSessionPerformanceData You can use this function to retrieve the performance data of a session running on the PowerCenter Server. The performance details provide counters that help you understand the session and mapping efficiency. Note: You call this function only for Session tasks.

Monitoring and Reporting Functions

63

Log Functions The PowerCenter Server creates a log for all status and error messages while running workflows and sessions. You can troubleshoot sessions and workflows by examining error messages sent to this log. Batch Web Services provides functions to fetch the workflow and session logs from the PowerCenter Server.

GettingWorkflowLog The PowerCenter Server creates a workflow log file for each workflow it runs. It writes information in the workflow log, such as initialization of processes, workflow task run information, errors encountered, and workflow run summary. Use the following functions to get workflow logs using the web services: ♦

StartWorkflowLogFetch

♦

GetNextLogSegment

To get workflow logs using the web services: 1.

Call StartWorkflowLogFetch once. This returns a LogHandle.

2.

Call GetNextLogSegment with this LogHandle. This returns a LogSegment object.

3.

If EndOfLog field of LogSegment object (obtained in step 2) is false, go to step 2, else exit.

The StartWorkflowLogFetch function requires folder name and workflow name. It returns a LogHandle. The GetNextLogSegment function requires a LogHandle (obtained in the StartWorkflowLogFetch) and a timeout value. This timeout value specifies the maximum time for which the client application can be blocked if no log segments for the workflow are available at the Web Services Hub. The Web Services Hub receives the log segments from the PowerCenter Server. After the timeout value expires, control is returned to the client application. LogSegment object returned by GetNextLogSegment provides a function getCodePage, which returns the code page ID as an integer.

GetSessionLog The PowerCenter Server creates a session log file for each session it runs. It writes information in 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.

64

Chapter 6: Using Batch Web Services Functions

Use the following functions to get session logs through the web services: ♦

StartSessionLogFetch

♦

GetNextLogSegment

To get session logs through the web services: 1.

Call StartSessionLogFetch once. This returns a LogHandle.

2.

Call GetNextLogSegment with this LogHandle. This returns a LogSegment object.

3.

If EndOfLog field of LogSegment object (obtained in step 2) is false, go to step 2, else exit.

StartSessionLogFetch function requires folder name, workflow name, and task instance path. It returns a LogHandle. The GetNextLogSegment function requires a LogHandle (obtained in the StartSessionLogFetch) and a timeout value. This timeout value specifies the maximum time for which the client application can be blocked if no log segments for the session are available at the Web Services Hub. The Web Services Hub receives the log segments from the PowerCenter Server. After the timeout value expires, control is returned to the client application.

Max Log Buffer Size The Web Services Hub buffers the log segments in memory until the MaxLogBufferSize limit is reached. The Web Services Hub drops the subsequent log segments it receives from the PowerCenter Server when the MaxLogBufferSize limit is reached. You can configure the MaxLogBufferSize by running UpdateConfigFile. The default value is 1024 KB. When calling Batch Web Services functions, call the GetNextLogSegment function immediately after calling the StartWorkflowLogFetch and StartSessionLogFetch functions to prevent loss of log segments. For more information about UpdateConfigFile, see “Step 4. Run UpdateConfigFile” on page 21.

Log Functions

65

66

Chapter 6: Using Batch Web Services Functions

Chapter 7

Writing Client Applications This chapter includes the following topics: ♦

Overview, 68

♦

Writing a Simple Client Application, 69

♦

Writing a Client Application in Java Using Axis, 73

♦

Writing a Client Application in C# Using .Net, 77

67

Overview This chapter provides an overview of how you can write client applications for the Web Services Hub. Following the generic sample client discussion is a section on developing your client applications in both Java and .Net. You need the Web Services Hub WSDL files (WSH.wsdl) and a web services toolkit depending on the language and platform you wish to use to develop your client application. Web services toolkits make it easy to create client applications by generating client-side proxy classes from the desired web service WSDL files. There are many web services toolkits available for almost all the languages and platforms on the market today.

68

Chapter 7: Writing Client Applications

Writing a Simple Client Application This section discusses the steps to write a Web Services Hub client application using any web services toolkit. Later sections of this chapter discuss the steps to develop client applications using the Axis and .Net Web Services Toolkits. Developing a client application for web services involves the following processes: ♦

Generate client proxy classes

♦

Initialization

♦

Session maintenance

♦

Metadata and Batch function calls

♦

Clean up

Note: These steps may vary according to the web services toolkit you use. Some toolkits, such as .Net, handle the session maintenance step automatically by generating the appropriate information from the WSDL files. As a result, the .Net client applications do not need to perform session maintenance.

Generating Client Proxy Classes To use the services offered by Web Services Hub, you need to generate a client proxy with the WSDL file provided and a web services toolkit. Use the following steps to generate client proxies: 1.

Select the web services toolkit for the platform and language you want to develop in.

2.

Change the Web Services Hub host name and port number in the endpoint URL for Metadata Web Services and Batch Web Services in the WSH.wsdl. You can change these by editing the address element, which is available in the definitions\service\port hierarchy in the WSDL file.

3.

Generate the client-side proxy classes from the WSH.wsdl using the web service toolkit. Refer to the web services toolkit documentation for details on the proxy classes generation. Different toolkits generate the client-side proxy classes in different manners.

4.

WSH.wsdl contains two port type definitions, one each for Metadata and Batch Web Services APIs. The generated client-side proxy classes should have two classes, one each for Metadata and Batch Web Services APIs apart from other classes.

Initialization Your client application performs an initialization step that enables it to make calls to Metadata Web Services and Batch Web Services.

Writing a Simple Client Application

69

To perform Initialization: 1.

Instantiate the proxy class for the Metadata APIs and name this object, for example, MWSProxy. Use this object to call Metadata Web Services functions.

2.

Instantiate the proxy class for the Data Integration APIs and name this object, for example, DIWSProxy. Use this object to call Batch Web Services functions.

3.

Call the Login function of Metadata Web Services using the MWSProxy object. This function requires three input parameters, repository name, user name, and password and the return parameter is a LoginHandle string. This function call associates the MWSProxy object with the repository name and user name pair. All subsequent requests made to Metadata Web Services using the MWSProxy object use this repository name and user name.

4.

Call the InitializeDIServerConnection function using the DIWSProxy object. This function requires two input parameters, LoginHandle and the PowerCenter Server name. This function call associates the DIWSProxy object with the repository name, user name, and PowerCenter Server name. All subsequent requests made to Batch Web Services using the DIWSProxy object use this repository name, user name, and PowerCenter Server name.

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:

70

1.

Extract the header with the root element name “Context” and namespace http://www.informatica.com/PowerCenter from the response of the Login function call. This SOAP header contains the Session ID sent by the Web Services Hub.

2.

Send this Session ID in a SOAP header for all subsequent requests using the MWSProxy object. You accomplish this by setting the SOAP header once in the MWSProxy object after the Login function call.

3.

Extract the header with the root element name “Context” and namespace http://www.informatica.com/PowerCenter from the response of the InitializeDIServerConnection function call. This header contains the Session ID sent by the Web Services Hub.

4.

Send this Session ID in a SOAP header for all subsequent requests made using the DIWSProxy object. You can accomplish this by setting the SOAP header once in the DIWSProxy object after the InitializeDIServerConnection function call.

Chapter 7: Writing Client Applications

Making Function Calls You are now ready to call Metadata Web Services and Batch Web Services functions using the MWSProxy and DIWSProxy objects respectively. For more information on Metadata Web Services function calls, see “Using Metadata Web Services Functions” on page 49. For more information on Batch Web Services function calls, see “Using Batch Web Services Functions” on page 55.

Cleaning up Server Resources The Web Services Hub implements session expiry for performance and resource clean up. The Logout and DeinitializeDIServerConnection functions clean up the server resources. However, if you log in to a repository but do not call the DeinitializeDIServerConnection and Logout functions, the Web Services Hub performs resource clean up after the session expiration period. Session expiry is defined for a Login function call and identified by the LoginHandle returned by the Login function call. A LoginHandle can connect to multiple Informatica Servers. Use the LoginHandle in the InitializeDIServerConnection function to initialize connections to multiple Informatica Servers. Note: The Web Services Hub defers resource clean up if there are active calls at the time of

session expiry. Clean up releases the Web Services Hub resources acquired by client applications and performs cleanup operations. To perform clean up: 1.

Call the Batch Web Services DeinitializeDIServerConnection function using the DIWSProxy object.

2.

Call the Metadata Web Services Logout function using the MWSProxy object.

Error Handling SOAP fault elements in the SOAP response report errors that occur while using Web Services Provider. While calling any of the Metadata Web Services or Batch Web Services functions, 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 error, exception handling scheme to obtain 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.

Writing a Simple Client Application

71

For more information on error handling schemes used in the Axis Web Services Toolkit, see “Error Handling in Axis” on page 76. For more information on error handling schemes used in the .Net Web Services Toolkit, see “Error Handling in .Net” on page 79.

Invalidating Proxy Objects The Login function call creates a session for the repository name and user name you provide. The LoginHandle (which corresponds to the Metadata proxy object) that you obtain from the Login function call identifies this session. This session (and Metadata proxy object) is valid as long as the LoginHandle is valid. Once you Logout, the LoginHandle becomes invalid along with the corresponding Metadata and Batch proxy objects.

72

Chapter 7: Writing Client Applications

Writing a Client Application in Java Using Axis This section highlights the steps to write a client application in Java using the Axis Web Services Toolkit.

Generating Client Proxy Classes in Axis You can generate Client Proxy Classes in Java using the Axis Web Services Toolkit. Generate client proxy classes in Java in the following manner: ♦

Change the Web Services Hub host name and port number in the endpoint URL for Metadata Web Services and Batch Web Services in the WSH.wsdl file. You can change these by editing the address element, which is available in the definitions\service\port hierarchy in the WSDL file.

♦

Generate the Client Proxy Classes from the WSH.wsdl using the following command: java org.apache.axis.wsdl.WSDL2Java --NStoPkg http://www.informatica.com/PowerCenter=ProxyClasses -W WSH.wsdl.

This generates the client proxy classes in the folder “ProxyClasses” in the “ProxyClasses” package. Use the -W options to turn off support for “wrapped” document/literal. This generates two proxy classes, MetadataInterface.java and DataIntegrationInterface.java. The proxy classes contain Metadata Web Services and Batch Web Services functions. Note: You can use the Axis client proxy classes shipped with the Web Services Hub samples

directory.

Initialization in Axis Your client application performs an initialization step that enables it to make calls to Metadata Web Services and Batch Web Services. To perform initialization: 1.

Get an object (Web Services Hub) of the Web Services Hub by instantiating the WebServicesHubLocator class, as follows: WebServicesHub WSH = new WebServicesHubLocator();

2.

Get an object (MWSProxy) of MetadataInterface from the Web Services Hub (obtained in previous step). Use the MWSProxy object to call Metadata Web Services functions. If you are changing the Metadata service endpoint URL in the WSH.wsdl before creating the client proxy classes, get the MWSProxy object as follows: MWSProxy=WSH.getMetadata();

Otherwise, get the MWSProxy object as follows: MWSProxy=WSH.getMetadata(new java.net.URL(MWS_URL));

Writing a Client Application in Java Using Axis

73

Where the MWS_URL is a string containing the Metadata Service endpoint URL. 3.

Get a Data Integration Interface object (DIWSProxy) from the Web Services Hub (obtained in step one). Use the DIWSProxy object to call the Batch Web Services functions. If you are changing the Metadata service endpoint URL in the WSH.wsdl before creating the client side proxy classes, get the DIWSProxy object as follows: DIWSProxy=WSH. getDataIntegration ();

Otherwise, get the DIWSProxy object as follows: DIWSProxy=WSH. getDataIntegration (new java.net.URL(DIWS_URL));

Where DIWS_URL is a string containing Batch Web Services endpoint URL. 4.

Call the Login function of Metadata Web Services using the MWSProxy object. This function takes three input parameters, repository name, user name, and password, that are wrapped in an object LoginRequest and return a LoginHandle string. This function call associates the MWSProxy object with the repository name and user name. All subsequent requests made to Metadata Web Services using this MWSProxy object use this same repository name and user name. Use the MWSProxy object as follows: LoginRequest loginReq = new LoginRequest(); loginReq.setRepositoryName(REPO_NAME); loginReq.setUserName(USER_NAME); loginReq.setPassword(PASSWORD); String loginHandle = MWSProxy.login(loginReq);

where REPO_NAME is a string containing a repository name, USER_NAME is a string containing a user name, and PASSWORD is a string containing a password. 5.

Call the Batch Web Services InitializeDIServerConnection function using the DIWSProxy object. This function takes two input parameters, LoginHandle (obtained in step 4) and the PowerCenter Server name. This function call associates the DIWSProxy object with the repository name, user name (used in Login), and PowerCenter Server name. All subsequent requests made to the Batch Web Services using the DIWSProxy object use this same repository name, user name, and PowerCenter Server name. Use the DIWSProxy object as follows: InitializeDIServerConnectionRequest initializeReq = new InitializeDIServerConnectionRequest(); initializeReq.setDIServerName(DI_SERVER_NAME); initializeReq.setLoginHandle(loginHandle); DIWSProxy.initializeDIServerConnection(initializeReq);

Where DI_SERVER_NAME is a string containing the PowerCenter Server name.

74

Chapter 7: Writing Client Applications

Session Maintenance in Axis 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 perform session maintenance: 1.

Extract the SOAP header (MWSHeader) with the root element name “Context” and the namespace http://www.informatica.com/PowerCenter from the response of the Login function call using the MWSProxy object. This SOAP header contains the Session ID sent by the Web Services Hub. Send this Session ID in a SOAP header for all subsequent requests using the MWSProxy object. You set the SOAP header once in the MWSProxy object after the Login function call, as follows: SOAPHeaderElement MWSHeader =((org.apache.axis.client.Stub)MWSProxy).getResponseHeader(“http:// www.informatica.com/PowerCenter”,“Context”); ((org.apache.axis.client.Stub)MWSProxy).setHeader(MWSHeader);

2.

Extract the SOAP header (DIWSHeader) with the root element name “Context” and the namespace http://www.informatica.com/PowerCenter from the response of the Login function call using the DIWSProxy object. This SOAP header contains the Session ID sent by the Web Services Hub. Send this Session ID in a SOAP header for all subsequent requests using the DIWSProxy object. You set the SOAP header once in the DIWSProxy object after the Login function call as follows: SOAPHeaderElement DIWSHeader =((org.apache.axis.client.Stub)DIWSProxy).getResponseHeader(“http:// www.informatica.com/PowerCenter”,“Context”); ((org.apache.axis.client.Stub)DIWSProxy).setHeader(MWSHeader);

Making Function Calls in Axis You are now ready to call Metadata Web Services and Batch Web Services functions using the MWSProxy and DIWSProxy objects respectively. For example, you can call the GetAllDIServers function to get a PowerCenter Server: DIServerInfoArray servers = MWSProxy.getAllDIServers(new VoidRequest()); System.out.println(“WSH Supports following DI Servers “); for(int i=0; i < servers.getDIServerInfo().length ; i++) { System.out.println(servers.getDIServerInfo(i).getName()); }

You can call the PingDIServer function to ping a PowerCenter Server: PingDIServerRequest pingReq = new PingDIServerRequest(); pingReq.setDIServerName(DI_SERVER_NAME); pingReq.setTimeOut(30);

Writing a Client Application in Java Using Axis

75

EPingState pingResult = DIWSProxy.pingDIServer(pingReq); System.out.println(“Ping result is : “+ pingResult.toString());

Where the DI_SERVER_NAME is a string containing the PowerCenter Server name.

Cleaning Up in Axis Cleanup releases the Web Services Hub resources acquired by client applications and performs cleanup operations. To perform clean up: 1.

Call the DeinitializeDIServerConnection function of the Batch Web Services using the DIWSProxy object. DIWSProxy.deinitializeDIServerConnection(new VoidRequest());

2.

Call the Logout function of Metadata Web Services using the MWSProxy object. MWSProxy.logout(new VoidRequest());

Error Handling in Axis You can implement client application error handling in Axis by placing the code in a try block and catching the FaultDetails object. The FaultDetails class is generated as part of the client proxies. Code in a try block for catching the FaultDetails object as follows: try { // Code for steps explained above. } catch(FaultDetails fault) { // Display fault code System.out.println(“fault code : “ + fault.getFaultCode()); // Display fault string System.out.println(“fault string : “ + fault.getFaultString()); // Display error code System.out.println(“error code is : “ + fault.getErrorCode()); // Display extended details System.out.println(“extended detail is : “ + fault.getExtendedDetails()); }

76

Chapter 7: Writing Client Applications

Writing a Client Application in C# Using .Net This section highlights the various steps for writing a client application in C# using the .Net Web Services Toolkit.

Generating Client Proxy Classes in .Net You can create client proxy classes for the Web Services Hub in C# using Microsoft’s .Net Web Services Toolkit. You generate client proxy classes in C# in the following manner: ♦

Change the Web Services Hub host name and port number in the endpoint URL for Metadata Web Services and Batch Web Services in the WSH.wsdl file. You can change these by editing the address element, which is available in the definitions\service\port hierarchy in the WSDL file.

♦

Generate the Client Proxy Classes from the WSH.wsdl using the following command: wsdl WSH.wsdl

This generates a WebServicesHub.cs file that contains two proxy classes, MetadataServiceSoapBinding and DataIntegrationServiceSoapBinding along with data container classes. The two proxy classes contain Metadata Web Services and Batch Web Services functions. Note: You can use the .Net client proxy classes shipped with Web Services Hub distribution

in samples directory.

Initialization in .Net Your client application performs an initialization step that enables it to make useful calls to Metadata Web Services and Batch Web Services. To perform initialization: 1.

Instantiate a MetadataServiceSoapBinding class object (MWSProxy). Use the MWSProxy object to call Metadata Web Services functions as follows: MWSProxy= new MetadataServiceSoapBinding();

If you did not change the Metadata service endpoint URL in the WSH.wsdl before creating the client proxy classes, you can set the new URL as follows: MWSProxy.Url = MWS_URL;

Where MWS_URL is a string containing Metadata Service endpoint URL. 2.

Instantiate a DataIntegrationServiceSoapBinding class object (DIWSProxy). Use the DIWSProxy object to call the Batch Web Services functions as follows: DIWSProxy= new DataIntegrationServiceSoapBinding ();

Writing a Client Application in C# Using .Net

77

If you did not change the Batch Web Services endpoint URL in WSH.wsdl before creating client side proxy classes, you can set the new URL as follows: DIWSProxy.Url = DIWS_URL;

Where DIWS_URL is a string containing the Batch Web Services endpoint URL. 3.

Call the Login function of Metadata Web Services using the MWSProxy object. This function takes three input parameters, repository name, user name, and password, wrapped in an object LoginRequest and returns a LoginHandle string. This function call associates the MWSProxy object with this repository name and user name pair. All subsequent requests made to Metadata Web Services using the MWSProxy object use this repository name and user name. Use the MWSProxy object to call the Login function as follows: LoginRequest loginReq = new LoginRequest(); loginReq.RepositoryName = REPO_NAME; loginReq.UserName = USER_NAME; loginReq.Password = PASSWORD; String loginHandle = MWSProxy.Login(loginReq);

where REPO_NAME is a string containing the repository name, USER_NAME is a string containing the user name, and PASSWORD is a string containing the password. 4.

Call the InitializeDIServerConnection function of the Batch Web Services using the DIWSProxy object. This function uses two input parameters, LoginHandle (obtained in step 3) and the PowerCenter Server name. This function call associates the DIWSProxy object with the repository name, user name (used for Login), and the PowerCenter Server name. All subsequent requests made to the Batch Web Services using the DIWSProxy object use this same repository name, user name, and PowerCenter Server name. Use the DIWSProxy object to call the Login function as follows: InitializeDIServerConnectionRequest initializeReq = new InitializeDIServerConnectionRequest(); initializeReq.DIServerName=DI_SERVER_NAME; initializeReq.LoginHandle= loginHandle; DIWSProxy.InitializeDIServerConnection(initializeReq);

where DI_SERVER_NAME is a string containing the PowerCenter Server name.

Session Maintenance in .Net The Web Services Hub requires session maintenance to cache resources. The SOAP header in the SOAP Message carries the session information facilitating session maintenance. You do not need to take additional steps. The .Net client proxy classes handle session maintenance for you.

78

Chapter 7: Writing Client Applications

Making Function Calls in .Net You are now ready to call Metadata Web Services and Batch Web Services functions using the MWSProxy and DIWSProxy objects respectively. For example, you can call the GetAllDIServers function for Metadata Web Services as follows: DIServerInfo[] servers = MWSProxy.GetAllDIServers(new VoidRequest()); Console.WriteLine(“WSH Supports following DI Servers”); for(int i=0;i< servers.Length;i++) { Console.WriteLine(server[i].Name); }

Similarly, you can call the PingDIServer function of the Batch Web Services as follows: PingDIServerRequest pingReq = new PingDIServerRequest(); pingReq.DIServerName=DI_SERVER_NAME; pingReq.TimeOut= 30; EPingState pingState= DIWSProxy.PingDIServer(pingReq); Console.WriteLine(“ping result using state” + pingState);

Where DI_SERVER_NAME is a string containing the PowerCenter Server name.

Cleaning Up in .Net Clean up releases the Web Services Hub resources acquired by client applications and performs cleanup operations. To perform clean up: 1.

Call the DeinitializeDIServerConnection function of the Batch Web Services using the DIWSProxy object as follows: DIWSProxy.DeinitializeDIServerConnection(new VoidRequest());

2.

Call the Logout function of Metadata Web Services using the MWSProxy object as follows: MWSProxy.logout(new VoidRequest());

Error Handling in .Net You can implement client application error handling in .Net by placing the code in a try block and catching the SOAP Exception object. The SOAP Exception class is part of the .Net framework SDK. Code in a try block for catching the SOAP Exception object as follows: try { //Code for steps explained above. }

Writing a Client Application in C# Using .Net

79

catch(SoapException fault) { // Display fault code Console.WriteLine(“fault code is : “ + fault.Code); // Display fault string Console.WriteLine(“fault string is : “ + fault.Message); // Parsing detail element XmlNode detail = fault.Detail; XmlElement WSHFaultDetails = detail[“WSHFaultDetails”, “http:// www.informatica.com/PowerCenter”]; 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); }

80

Chapter 7: Writing Client Applications

Chapter 8

Working with Service Mappings This chapter includes the following topics: ♦

Overview, 82

♦

Importing Web Service Source and Target Definitions, 83

♦

Viewing and Editing Web Service Definitions, 89

♦

Working with Service Mappings, 95

81

Overview Before you can define a service in the Workflow Manager, you use the Designer to perform 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 service 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 source and target and use it in a service. This allows you receive message data through a SOAP call instead of reading it from a file.

82

Chapter 8: Working with Service Mappings

Importing Web Service Source and Target Definitions Web service source and target definitions represent metadata for SOAP request and response messages. You create web service source and target definitions by importing a WSDL file. The WSDL file contains information about a web service operation. The Designer creates a source or target definition based on the operation you choose in the WSDL file you import: ♦

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 Warehouse Designer, the Designer imports metadata for a web service soap response. This represents the metadata for a web service SOAP response.

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.

Importing Web Service Source Definitions When you use the Source Analyzer to import an operation from a WSDL file, the Import Wizard imports the input message associated with the operation. Each definition has multiple groups. Figure 8-1 shows a source definition imported from a WSDL file: Figure 8-1. Web Service Source Definition

Root group contains message ID.

Body group has foreign key pointing to root group.

Detail group has foreign key pointing to body group.

Header group has foreign key pointing to root group.

Importing Web Service Source and Target Definitions

83

Table 8-1 describes the groups in a web service definition: Table 8-1. Web Services Definition Groups Group Name

Description

Message

The root group contains the message ID and client information. For information about the message header ports, see Table 8-2.

Header_name

The header group contains a foreign key to the root group. The header group has 1:1 relationship with the root group.

Body_name

The body group contains a foreign key pointing to the root group. The body group has a 1:1 relationship with the root group.

X_ name

The detail group contains a foreign key pointing to the body group. This detail group has an n:1 relationship with the body group.

Att_name

The attachment group contains a foreign key pointing to the root group. The attachment group has an n:1 relationship with the root group.

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 service workflow, the Web Services Hub uses this information to identify the web service client and generate a message ID. Table 8-2 describes the message header ports in a web service definition: Table 8-2. Message Header Ports Port Name

Description

PK_Message

Generated primary key for the root group.

MessageID

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

ClientID

User ID of the web service client.

ClientIP

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

Importing Web Service Target Definitions When you use the Warehouse Designer to import an operation from a WSDL file, the Import Wizard imports the output message and any fault message associated with the operation. Because a function within an operation can result in different faults, the Import Wizard may create multiple fault definitions. A fault message represents an error processing the request. Each message contains a group for the message root and the message body. The message root group for a web service target definition contains a message ID port.

84

Chapter 8: Working with Service Mappings

Figure 8-2 shows a sample output message and fault message: Figure 8-2. Web Service Target Definitions Output Message Fault Message

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

Steps for Importing Web Service Sources and Targets When you import a WSDL file, you can import it from a local file, or you can import it from a URL. You can import definitions from a WSDL file with document/literal encoding. The Import Wizard imports the input message of operation as a source definition. It imports the output message and fault message of an operation as target definitions. If a service does not have an associated operation, you cannot import the definition. To import a web service definition: 1.

From the Source Analyzer, choose Sources - Import from WSDL (Provider). or

Importing Web Service Source and Target Definitions

85

From the Warehouse Designer, choose Targets - Import from WSDL (Provider).

Select a URL.

Configure default precision.

Choose to display import errors.

Choose to import from a local file or a URL.

2.

86

Click Advanced Options to configure the default precision for String datatype fields.

Chapter 8: Working with Service Mappings

Table 8-3 describes the options you can configure when you choose Advanced Options. Table 8-3. Advanced Options Option

Description

Override all infinite lengths

You can specify a default length for fields with undefined lengths, such as strings.

Generate names for XML columns

You can choose to name XML columns by a sequence number or from the element or attribute name in the schema. If you use names, you can add the XML view as a prefix to each column, and you can add the element name as a prefix to all the attributes.

3.

Choose to import from a local file or a URL.

4.

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.

Importing Web Service Source and Target Definitions

87

5.

Choose an operation from the Import from WSDL dialog box:

6.

Click OK twice. The web service definition appears in the workspace.

88

Chapter 8: Working with Service Mappings

Viewing and Editing Web Service Definitions After you import a web service source or target, you can view the definition in the Designer workspace or the XML Editor. You can also edit some properties in the Designer workspace.

Viewing and Editing Definitions in the Designer Web service source definitions and target definitions contain the following tabs: ♦

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. By default, the Designer imports web service definition String datatypes with a precision of 1,000. You can change the default precision for String datatypes when you import the source or target. When you change the default precision, the Designer uses the updated 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

definition 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 85.

Viewing and Editing Web Service Definitions

89

Figure 8-3 shows the Columns tab for a web service source definition: Figure 8-3. Columns Tab for a Web Service Definition

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.

90

Chapter 8: Working with Service Mappings

Figure 8-4 shows the Attributes tab for a web service target definition: Figure 8-4. Attributes Tab for a Web Service Definition

MIME Type of Attachment

Metadata Extensions Tab You can create metadata extensions on the Metadata Extensions tab. You can also view the vendor-defined extensions in the Web Services Provider Domain. These metadata extensions identify the message type, which can be input, output, or fault.

Viewing and Editing Web Service Definitions

91

Figure 8-5 shows the Metadata Extensions tab for a web service source definition: Figure 8-5. Metadata Extensions Tab for a Web Service Definition

Displays message type as input, output, or fault.

View Definitions in the XML Editor After you import a web service source or target definition, you can view the groups and relationships in the XML Editor. The XML Editor is read-only for web service source and target definitions. You can perform functions such as validation and searching. For more information about the XML Editor, see the XML User Guide.

92

Chapter 8: Working with Service Mappings

Figure 8-6 shows the XML Editor view of the source definition shown in Figure 8-1 on page 83: Figure 8-6. XML Editor Views of Web Service Definition

To view a web service definition in the XML Editor:

Right-click a definition and choose WSDL Workspace.

Editing Web Service Targets in a Mapping When you work with web service targets in a mapping, you can configure the load scope on the Properties tab. Load scope in a web service target definition is similar to the transformation scope in a transformation. You can configure the following load scope values: ♦

All input. When you configure the load scope to all input, the PowerCenter Server generates a response after it receives all incoming data. Different groups in the target can receive data from different transaction generators. The PowerCenter Server ignores commits when the load scope is all input.

Viewing and Editing Web Service Definitions

93

♦

Transaction. When you configure the load scope to transaction, the PowerCenter Server generates a response when it receives all data in the transaction. All groups in the target must receive data from the same transaction generator.

For more information about transformation scope, see "Understanding Commit Points" in the Workflow Administration Guide.

94

Chapter 8: Working with Service Mappings

Working with Service Mappings You can create service mappings to process web service requests. A service mapping can contain source or target definitions imported from a Web Services Description Language (WSDL) file containing a web service operation. It can also contain flat file or XML source or target definitions. The mapping you create depends on the type of service that you want to run: ♦

♦

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. This allows you to 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 PowerCenter Server loads data to a target, often triggered by a real-time event through a web service request. When you create a oneway mapping, you do not need to propagate the message ID to the target.

The web service source and target definitions you put in the mapping depend on the type of mapping you create. Table 8-4 describes the web service source and targets definitions you use based on the mapping type: Table 8-4. Required Sources and Targets in a Service Service Type

Web Service Source

Web Service Target

Request-Response

Must have one instance of one web service source definition.

Can have multiple instances of one target output definition. Can have multiple target fault definitions.

One-way

Must have one instance of one web service source definition.

Contains no web service target definition.

Note: You can also create mappings with flat file or XML source or targets and run them in

service workflows. For more information, see “Running Sessions and Service Workflows” on page 109.

Working with Service Mappings

95

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, your company 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 8-7 shows a sample request-response mapping: Figure 8-7. Request-Response Mapping

Note: When you create request-response mappings, Informatica recommends that you 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.

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 request and response. 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:

96

1.

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.

2.

An external application receives messages from the MQSeries target, processes them, and sends messages to another MQSeries queue.

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.

Chapter 8: Working with Service Mappings

Flat File or XML Mappings You can read from or write to web service clients using flat file or XML mappings. For example, you periodically use FTP to access a flat file containing messages from a web service application. Instead of using FTP, you can set up a SOAP call to receive messages through a service. This eliminates disk input and output and allows you to receive the message as a SOAP request rather than waiting to receive a file. When you configure the session, change the reader from Flat File Reader to Web Services Provider Reader for Flat Files.

Attachment Mappings Based on the source and target definitions, you can receive and send attachments as part of the SOAP request. The document type you can attach is based on the MIME content of the WSDL file. You can attach document types such as XML, JPEG, GIF, or PDF. 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 8-5 describes the attachment group ports in a web service definition: Table 8-5. Attachment Group Ports Port Name

Description

FK_Att_Name

Generated foreign key pointing to PK_Message in the root group.

Att_Data_Name

Contains the attachment. You can view the MIME type for the attachment on the Attributes tab.

Att_Index_Name

Unique identifier for each attachment in the message.

Att_Type_Name

The 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 your 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, you can use a Sequence Generator transformation to generate a unique index for each attachment you send in a response.

Working with Service Mappings

97

98

Chapter 8: Working with Service Mappings

Chapter 9

Working With Service Workflows This chapter includes the following topics: ♦

Overview, 100

♦

Creating and Configuring a Service, 101

♦

Creating and Configuring a Service Session, 103

♦

Running Sessions and Service Workflows, 109

♦

Troubleshooting, 111

99

Overview You configure services and service workflows in the Workflow Manager. When you create a service workflow, you enable it for web services. You configure the service within the workflow properties. For more information about creating services and service workflows, see “Creating and Configuring a Service” on page 101. When you create a session to add to the workflow, you can 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 103. For more information about running sessions, see “Running Sessions and Service Workflows” on page 109. Note: Before you can run a service workflow, you must register the Web Services Hub. For

more information, see “Step 5. Register the Web Services Hub” on page 23.

100

Chapter 9: Working With Service Workflows

Creating and Configuring a Service You must create a service workflow and configure a service to process a service mapping. When you enable web services in the workflow properties, you can configure service information that allows web service clients to run the service workflow. Perform the following tasks when you create and configure a service: ♦

Create a service workflow.

♦

Configure the service.

Creating a Service Workflow When you enable web services in the workflow properties, you create a service workflow. You can configure service information and add service sessions to the workflow. A service session is based on a service mapping. Each service workflow must contain exactly one web service input message source and at most one type of web service output message target. The workflow can write to multiple fault message targets. Figure 9-1 shows how to enable the workflow for web services: Figure 9-1. Creating a Service Workflow

Create a service workflow. Configure service.

Configuring the Service When you configure a service, you configure a service name, timeout, and accessibility options. Creating and Configuring a Service

101

Figure 9-2 shows the Config Service dialog box: Figure 9-2. Web Service Configuration

Table 9-1 describes the properties you can configure for a web service: Table 9-1. Web Service Properties

102

Option

Description

Service Name

Name of service that web service clients can run. 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.

Timeout

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

Protected

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

Visible

Makes the service visible in the Web Services Hub to web service clients. When you make the service visible, the Web Services Hub publishes the service in a list of services available to web service clients. If the service is not visible, the Web Services Hub does not publish the service WSDL. However, web service clients can still run a service by submitting a request with the service name and WSDL.

Runnable

Allows a web service client to run the service. If enabled, a web service client can start the workflow or invoke the service while the workflow is running. If you want a web service client to start the workflow, schedule the workflow to run on demand. If disabled, a web service client can invoke the service while the workflow is running, but cannot start the workflow. If disabled, you can start the workflow through the Workflow Manager, LMAPI, or pmcmd.

Chapter 9: Working With Service Workflows

Creating and Configuring a Service Session When you create a service session, you can use a service mapping or any flat file or XML mapping. Configure the following properties when you configure a service session: ♦

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

♦

Web Services Provider writer. When you configure the writer for a service session, you configure caching information that the PowerCenter Server uses to cache target data. For more information about configuring the writer, see “Configuring the Web Services Provider Writer” on page 105.

♦

Recovery. When you enable recovery, the PowerCenter Server stores messages in the cache directory. For more information about message recovery, see “Recovering Messages” on page 106.

♦

Commit type. Configure real-time sessions for a source-based commit. For more information about commit behavior, see “Configuring Commit Type” on page 107.

♦

Partitioning. You can configure partitioning properties based on the source and target type in the mapping. For more information about partitioning, see “Configuring Partitioning” on page 107.

Configuring the Web Services Provider Reader The properties you configure for a Web Services Provider reader depend on the source type in the mapping.

Creating and Configuring a Service Session

103

Figure 9-3 shows the properties you configure for the Web Services Provider reader: Figure 9-3. Web Services Provider Reader Properties

Configure reader properties based on the reader type. Table 9-2 describes the properties you configure for the different web services provider readers: Table 9-2. Web Services Provider Reader Properties

104

Property

Source Type

Description

Idle Time*

Web Service Flat File XML

The amount of time in seconds the PowerCenter Server waits to receive messages before it stops reading from the source and ends the session. Default value is -1 and indicates an infinite period of time.

Message Count*

Web Service Flat File XML

The number of messages the PowerCenter Server reads before it ends the session. If the session uses flat file or XML sources, configure the message count to 1. For more information, see “Running Sessions and Service Workflows” on page 109. Default value is -1 and indicates an infinite number of messages.

Reader Time Limit*

Web Service Flat File XML

The amount of time in seconds that the PowerCenter Server reads source messages from the Web Services Hub. For example, if you specify 10 for a time limit, the PowerCenter Server stops reading from the Web Services Hub after 10 seconds. Default value is 0 and indicates an infinite period of time.

Chapter 9: Working With Service Workflows

Table 9-2. Web Services Provider Reader Properties Property

Source Type

Description

Real-time Flush Latency

Web Service

Send response messages to the Web Services Hub after a specified number of seconds. Default value is 0 and indicates that the flush latency is disabled. Set this to a value less than the service timeout in the service properties.

Recovery Cache Folder

Web Service Flat File XML

If you enable recovery, the PowerCenter Server stores messages in this location before processing them. Default value is $PMCacheDir/. For information about message caching, see “Recovering Messages” on page 106.

Treat Empty Content as Null

XML

Treats empty strings as null values. By default, empty content is not null.

*The session stops when it meets any of these conditions.

Configuring Real-time Flush Latency Use flush latency to send response messages to the Web Services Hub after a specified number of seconds. The PowerCenter Server flushes messages to the Web Services Hub when it reaches the flush latency period or when the reader buffer is full, whichever comes first. The PowerCenter Server does not buffer messages longer than the flush latency period. The Web Services Hub might not send responses to the web service client if you configure flush latency greater than the service timeout. For more information, see “Running Sessions and Service Workflows” on page 109. Consider the following guidelines when you configure flush latency: ♦

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 PowerCenter Server 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.

Configuring the Web Services Provider Writer When you configure session properties for a Web Services Provider writer, you configure cache size and cache directory.

Creating and Configuring a Service Session

105

Table 9-3 describes the properties you configure for a Web Services Provider writer: Table 9-3. Web Services Provider Writer Properties Property

Target Type

Description

Orphan Row Handling

XML

Determines orphan row handling. Select Ignore to continue the session and ignore the orphan rows. Select Error to abort the session when an orphan row occur.

Cache Size

Web Service XML

The total size in bytes for the memory cache used by writer. Default is 10,000,000 bytes.

Cache Directory

Web Service XML

The directory for the target cache files. Default is the $PMCacheDir server variable.

Use the following 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 PowerCenter Server does not cache the target messages.

♦

When you change the writer type for a flat file or an XML target, you can 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 XML User Guide.

Configuring Caching The PowerCenter Server caches row data while it generates a message. The cache size is the sum of all the groups in the target instance. It includes a primary key and a foreign key index cache for each group and one data cache for all groups. If the memory requirements exceed the cache size, the PowerCenter Server pages to disk. When the session completes, the PowerCenter Server releases cache memory and deletes the cache files. The total cache requirement is the sum of the data cache and index cache requirements for each target group.

Recovering Messages When you enable recovery, you can recover read messages from a failed session. The PowerCenter Server stores all read messages in a cache before processing the messages for the target. If the session fails, run it in recovery mode to recover the messages the PowerCenter Server could not process. The PowerCenter Server reads and processes the messages from the cache. It does not continue to receive messages from the Web Services Hub. The PowerCenter Server removes messages from the message cache files after the flush latency period expires. It empties the cache files at the end of the session.

106

Chapter 9: Working With Service Workflows

Note: The PowerCenter Server ignores the reader time limit, idle time, and message count

when it reads messages from the cache. For more information about recovery, see the Workflow Administration Guide.

Configuring Commit Type When you configure a real-time session, the PowerCenter Server uses a source-based commit. If you configure a flush latency interval, the interval begins when the PowerCenter Server receives the first message from the Web Services Hub. The PowerCenter Server sends messages to the Web Services Hub based on the commit type that you choose.

Configuring Source-Based Commit If you configure a source-based commit, the PowerCenter Server sends messages to the Web Services Hub based on the commit interval and the flush latency interval. For example, you use five seconds as the flush latency interval and you set the source-based commit interval to 1,000 messages. The PowerCenter Server sends messages to the Web Services Hub after receiving 1,000 messages from the source and after each five second flush latency interval. If the session uses an XML target, and you configure the on commit property to ignore, the PowerCenter Server sends messages to the Web Services Hub when it reads 1,000 messages. It does not issue a commit when it reaches the flush latency interval. Note: The PowerCenter Server ignores source-based commits for XML sources.

Configuring Target-Based Commit If you configure a target-based commit, the PowerCenter Server runs the session using sourcebased commit. It sends messages to the Web Services Hub based on the flush latency interval. It does not send messages based on the commit interval. For more information about commit types and intervals, see the Workflow Administration Guide. Note: The PowerCenter Server ignores target-based commits for XML targets.

Configuring Partitioning When you configure multiple partitions in a session that contains web service source and target definitions, the PowerCenter Server 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 PowerCenter Server 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 PowerCenter Server. The PowerCenter Server uses a target connection to

Creating and Configuring a Service Session

107

send a response to the Web Services Hub. The Web Services Hub and the PowerCenter Server use the source and target connections in a round-robin fashion. When you configure partitioning 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 “Pipeline Partitioning” in the Workflow Administration Guide.

108

Chapter 9: Working With Service Workflows

Running Sessions and Service Workflows When the Web Services Hub receives a SOAP message request to run a service based on a mapping containing web service sources or targets, it generates a message ID and passes the request to the PowerCenter Server. After the PowerCenter Server runs the service request, it passes the response to the Web Services Hub. The Web Services Hub generates a SOAP message response and passes it back to the web service client.

Working with XML and Flat File Sessions You can also create a service session based on a mapping that contains XML or flat file sources and targets. When you configure the session, you change the reader or writer in the session properties to receive or send messages to the web service client. When you change the reader or writer type, the Web Services Hub sends request payload to the PowerCenter Server as an attachment to the SOAP message. When the Web Services Hub receives a SOAP message request to run a service based on a session with updated reader or writer properties for web service access, it sends the request payload to the PowerCenter Server as an attachment to the SOAP message. It cannot generate a message ID or correlate the incoming request with the outgoing response. If the service is request-reply, the PowerCenter Server starts a session instance for each request. When it passes the response to the Web Services Hub, the Web Services Hub attaches the response to a SOAP message and sends it back to the web service client. For information about running services with flat file or XML mappings, see “Working with Service Mappings” on page 95. Use the following rules and guidelines when you configure a request-response session with flat file or XML source or targets: ♦

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.

Understanding Service Timeout and Flush Latency When you run a service session, the Web Services Hub must generate the response message in the timeout period configured in the service properties. When the Web Services Hub reaches the timeout period, it sends a fault message to the web service client and drops the connection. If the PowerCenter Server 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 scenarios describe some session configurations that can result in dropped response messages: ♦

You configure flush latency greater than the service timeout period. Running Sessions and Service Workflows

109

For example, you configure the 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 PowerCenter Server 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 PowerCenter Server 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 configure the terminating conditions to infinite values, the session runs continuously and never ends. The PowerCenter Server 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 PowerCenter Server.

♦

You disable flush latency and use message count as the terminating condition. For example, you want the session to end after the PowerCenter Server processes 10 messages. You configure message count to 10, and you disable flush latency to flush all the messages at the end of the session. If the PowerCenter Server 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 PowerCenter Server.

To help ensure that the Web Services Hub does not reach the timeout period, configure flush latency value less than the service timeout.

110

Chapter 9: Working With Service Workflows

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 service workflow. You cannot run the Debugger against a service mapping or a reusable session without the workflow. When a client application invokes a service, I see a debug message in the Web Services Hub log similar to the following message: 2004-06-28 14:46:47,400 [Thread-6] DEBUG - WshServlet::logRequestHeaders vsdebuggercausalitydata : AwAAAHW5hDm6UwNDh9Cb134tdNUAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA AA

You cannot debug this message. The Web Services Hub did not generate it. The client application sends this message in the HTTP header. 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.

Troubleshooting

111

112

Chapter 9: Working With Service Workflows

Appendix A

Web Services Hub Error Messages This appendix includes the following topics: ♦

Web Services Hub Level Errors, 114

113

Web Services Hub Level Errors This section discuses the Web Services Hub errors. It lists error codes and error messages specific to the Web Service Hub. The error code is the Error Code element in the detail element of a SOAP fault. The error message is the faultstring element of the SOAP fault. For more information on SOAP fault schema, see “SOAP Fault Handling” on page 45. WSH_95000

Web Services Hub ERROR.

Cause:

Internal error at the Web Services Hub.

Action:

See the Extended Details in the SOAP fault message to determine the exact problem. or

114

Action:

Contact Informatica Technical Support.

WSH_95001

Invalid request parameter. Folder name cannot be null.

Cause:

This occurs when you pass a null folder name in a function call that requires folder name.

Action:

Specify a valid folder name.

WSH_95002

Invalid request parameter. Workflow name cannot be null.

Cause:

This occurs when you pass a null workflow name in a function call that requires a workflow name.

Action:

Specify a valid workflow name.

WSH_95003

Invalid request parameter. Task instance path cannot be null.

Cause:

This occurs when you pass a null task instance path in a function call that requires task instance path.

Action:

Specify a valid task instance path.

WSH_95004

Shutdown mode <shutdown mode> is not valid. Valid modes are ABORT, STOP, or COMPLETE.

Cause:

This occurs when you pass an invalid shutdown mode in the StopDIServer function call.

Action:

Specify a valid shutdown mode. Valid modes are ABORT, STOP, or COMPLETE.

WSH_95005

Invalid request parameter. Shutdown mode cannot be null.

Cause:

This occurs when you pass a null value shutdown mode in the StopDIServer function call.

Action:

Specify a valid shutdown mode. Valid modes are ABORT, STOP, or COMPLETE.

Appendix A: Web Services Hub Error Messages

WSH_95006

Request mode <request mode> is not valid. Valid request modes are NORMAL or RECOVERY.

Cause:

This occurs when you pass an invalid request mode in a function call that takes request mode as a parameter.

Action:

Specify a valid request mode. Valid request modes are NORMAL or RECOVERY.

WSH_95007

Invalid request parameter. Request mode cannot be null.

Cause:

This occurs when you pass a null request mode in a function call that takes request mode as a parameter.

Action:

Specify a valid request mode. Valid request modes are NORMAL or RECOVERY.

WSH_95008

Monitor server mode <monitor server mode> is not valid. Valid selections are ALL, RUNNING, or SCHEDULED.

Cause:

This occurs when you pass an invalid monitor server mode in the MonitorDIServer function call.

Action:

Specify a valid monitor server mode. Valid selections are ALL, RUNNING, or SCHEDULED.

WSH_95009

Invalid request parameter. Monitor server mode cannot be null.

Cause:

This occurs when you pass a null monitor server mode in the MonitorDIServer function call.

Action:

Specify a valid monitor server mode. Valid selections are ALL, RUNNING, or SCHEDULED.

WSH_95010

Invalid request parameter. Repository name cannot be null.

Cause:

This occurs when you pass a null repository name in the Login function call.

Action:

Specify a valid repository name.

WSH_95011

Invalid request parameter. Username cannot be null.

Cause:

This occurs when you pass a null user name in the Login function call.

Action:

Specify a valid user name.

WSH_95012

Invalid request parameter. Password cannot be null.

Cause:

This occurs when you pass a null password in the Login function call.

Action:

Specify a valid password.

WSH_95013

Invalid request parameter. Login handle cannot be null.

Cause:

This occurs when you pass a null login handle in the InitializeDIServerConnection function call.

Action:

Specify a valid login handle. Web Services Hub Level Errors

115

WSH_95014

Invalid request parameter. PowerCenter Server name cannot be null.

Cause:

This occurs when you pass a null PowerCenter Server name in either the InitializeDIServerConnection or PingDIServer function calls.

Action:

Specify a valid PowerCenter Server name.

WSH_95015

Invalid request parameter. WorkflowRequest object cannot be null.

Cause:

This occurs when you pass a null WorkflowRequest object in a workflow request function call.

Action:

Specify a valid WorkflowRequest object.

WSH_95016

PowerCenter Server <powercenter server name> is not registered with repository.

Cause:

This occurs when you pass a PowerCenter Server name in the InitializeDIServerConnection function call that is not registered with the repository used in Login function call.

Action:

Specify a PowerCenter Server name, which is registered with the repository used in the Login function call.

WSH_95017

Invalid login handle.

Cause:

This occurs when you pass an invalid login handle.

Action:

Specify a valid login handle, which is obtained from the Login function call.

WSH_95018

Invalid request parameter. TaskRequest object cannot be null.

Cause:

This occurs when you pass a null TaskRequest object in a task request function call.

Action:

Specify a valid TaskRequest object.

WSH_95020

Connection to PowerCenter Server is not initialized.

Cause:

This occurs when you call any function of the Batch Web Services functions without calling the InitializeDIServerConnection function first.

Action:

Call the InitializeDIServerConnection function before calling any other functions of Batch Web Services. or

116

Cause:

This occurs when you have called the InitializeDIServerConnection function and call other functions of Batch Web Services without setting the header.

Action:

Set the header obtained in the InitializeDIServerConnection response in subsequent requests to Batch Web Services.

WSH_95021

Unable to process request. InitializeDIServerConnection request should not contain a SOAP header.

Cause:

This occurs when you send a header in the InitializeDIServerConnection request.

Appendix A: Web Services Hub Error Messages

Action:

Clear the header before calling the InitializeDIServerConnection function.

WSH_95022

Invalid log handle.

Cause:

This occurs when you pass an invalid log handle in the GetNextLogSegment function.

Action:

Specify a valid log handle obtained from the StartWorkflowLogFetch or the StartSessionLogFetch function calls.

WSH_95023

Unable to process request. Login request should not contain a SOAP header.

Cause:

This occurs when you pass a SOAP header in the Login function call.

Action:

Clear the headers before calling Login function.

WSH_95024

User logged out.

Cause:

This occurs when you make any function call after logging out.

Action:

Call the Login function again before making any other function calls.

WSH_95025

User session expired.

Cause:

This occurs when you make any function calls after your session expires.

Action:

Call the Login function again before making any other function calls.

WSH_95026

Unable to deinitialize the connection to PowerCenter Server. Some calls are in progress.

Cause:

This occurs when you try to call the DeinitializeDIServerConnection function when active calls are in progress.

Action:

Wait for active calls to finish and then call the DeinitializeDIServerConnection function.

WSH_95027

Repository is not configured at the Web Services Hub.

Cause:

This occurs when you try to use a repository, which is not configured at the Web Services Hub.

Action:

Either configure the Web Services Hub for this repository or use a repository, which is configured at the Web Services Hub.

WSH_95028

User not logged in.

Cause:

This occurs when you try to call a web service function without calling the Login function first.

Action:

Call the Login function before calling any other web services functions. or

Cause:

This occurs when you have called the Login, and then call some Metadata Web Service function without setting the header.

Web Services Hub Level Errors

117

Action:

Set the SOAP header obtained in the Login function call response before making any subsequent calls to the Metadata Web Service.

WSH_95029

Folder does not exist.

Cause:

This occurs when you specify an invalid folder name in a function call of the Metadata Web Service.

Action:

Specify a valid folder name.

WSH_95030

Workflow <workflow name> does not exist.

Cause:

This occurs when you specify an invalid workflow name in a function call of the Metadata Web Service.

Action:

Specify a valid workflow name.

WSH_95031

Session is being logged out or timed out.

Cause:

This occurs when you make any function call and the Web Services Hub is performing clean up because of a session time out (expiry) or logout.

Action:

Wait for cleanup completion and log in again before making any function calls.

WSH_95032

Invalid SOAP header in request.

Cause:

This occurs when you send a header element which does not conform to the header element schema.

Action:

Use a valid SOAP header element as defined in the schema.

WSH_95033

Invalid Session ID in header. Either you have logged out, timed out, or your Session ID is invalid.

Cause:

This occurs when you send a Session ID in the SOAP header that has expired, or timed out.

Action:

Call the Login function again and use the Session ID obtained in the response header of the Login function call. or

Cause:

This occurs when you send an invalid Session ID in the SOAP header.

Action:

Use the Session ID obtained in the response header of the Login function call.

WSH_95034

Repository error.

Cause:

This occurs while you are querying repositories using the Metadata Web Service APIs and an internal repository error occurs.

Action:

Look at the extended details to find out the exact problem. or

Action:

118

Contact Informatica Technical Support.

Appendix A: Web Services Hub Error Messages

WSH_95035

Invalid SOAP request.

Cause:

This occurs when you pass a null SOAP message in the request.

Action:

Send the SOAP request as the Web Services Hub WSDL file dictates.

WSH_95036

User logged out or session expired.

Cause:

This occurs when you try to make a call after logout or the session expires.

Action:

Call the Login function again before making any further calls.

WSH_95040

Unable to log out. Some calls are in progress.

Cause:

This occurs when you try to call logout while active calls are in progress.

Action:

Wait for the active calls to finish, and then call Logout.

WSH_95041

Depth <depth> is not valid. Depth should be a positive integer value.

Cause:

This occurs when you give an invalid depth in the GetAllTaskInstances function call.

Action:

Specify a depth value greater than zero.

WSH_95042

Invalid request parameter. LoginRequest object cannot be null.

Cause:

This occurs when you pass a null LoginRequest object in the Login function call.

Action:

Specify a valid LoginRequest object.

WSH_95043

Invalid request parameter. FolderInfo object cannot be null.

Cause:

This occurs when you pass a null value for the FolderInfo object in the GetAllWorkflows function call.

Action:

Specify a valid FolderInfo object.

WSH_95044

Invalid request parameter. GetAllTaskInstancesRequest object cannot be null.

Cause:

This occurs when you pass a null GetAllTaskInstancesRequest object in the function call.

Action:

Specify a valid GetAllTaskInstancesRequest object.

WSH_95045

Unable to load config file:

Cause:

This occurs when the config file loader service fails to load the config file. The reason could be that the config file is not well-formed, the config file is invalid (does not conform to schema), or the config file is not present at the desired location.

Action:

Make sure that the config file is well-formed, conforms to the schema specified in the WSHConfig.xsd and is present in the designated location.

Web Services Hub Level Errors

119

120

WSH_95046

Invalid request parameter. The InitializeDIServerConnectionRequest object cannot be null.

Cause:

This occurs when you pass a null InitializeDIServerConnectionRequest object in the InitializeDIServerConnection function call.

Action:

Specify a valid InitializeDIServerConnectionRequest object.

WSH_95047

Invalid request parameter. PingDIServerRequest object cannot be null.

Cause:

This occurs when you pass a null PingDIServerRequest object in PingDIServer function call.

Action:

Specify a valid PingDIServerRequest object.

WSH_95048

Invalid request parameter. The StopDIServerRequest object cannot be null.

Cause:

This occurs when you pass a null StopDIServerRequest object in the StopDIServer function call.

Action:

Specify a valid StopDIServerRequest object.

WSH_95049

Invalid request parameter. The GetSessionStatisticsRequest object cannot be null.

Cause:

This occurs when you pass a null GetSessionStatisticsRequest object in the GetSessionStatistics function call.

Action:

Specify a valid GetSessionStatisticsRequest object.

WSH_95050

Invalid request parameter. The GetSessionPerformanceDataRequest object cannot be null.

Cause:

This occurs when you pass a null GetSessionPerformanceDataRequest object in the function call.

Action:

Specify a valid GetSessionPerformanceDataRequest object in the GetSessionPerformanceData function call.

WSH_95051

Invalid request parameter. The StartSessionLogFetchRequest object cannot be null.

Cause:

This occurs when you pass a null StartSessionLogFetchRequest object in the StartSessionLogFetch function call.

Action:

Specify a valid StartSessionLogFetchRequest object.

WSH_95052

Invalid request parameter. The StartWorkflowLogFetchRequest object cannot be null.

Cause:

This occurs when you pass a null StartWorkflowLogFetchRequest object in the StartWorkflowLogFetch function call.

Action:

Specify a valid StartWorkflowLogFetchRequest object.

Appendix A: Web Services Hub Error Messages

WSH_95053

Timeout value is not valid. The timeout value should be a positive integer value.

Cause:

This occurs when you specify an invalid timeout value.

Action:

Specify a time out value greater than zero.

WSH_95054

Invalid request parameter. The GetNextLogSegmentRequest object cannot be null.

Cause:

This occurs when you pass a null GetNextLogSegmentRequest object in the GetNextLogSegment function call.

Action:

Specify a valid GetNextLogSegmentRequest object.

WSH_95055

Unable to parse the config.xml file: .

Cause:

You used UpdateConfigFile with a config.xml file that does not conform to the specified schema.

Action:

Use a valid config.xml that conforms to XML schema described in WSHConfigUpdate.xsd file in config folder.

or Cause:

The Web Services Hub could not find the schema file for config.xml.

Action:

Verify that the config folder contains the schema file, WSHConfig.xsd.

WSH_95056

Unable to delete the Repository . This repository is not configured at WSH

Cause:

You tried to delete a repository that is not configured the Web Services Hub.

Action:

Use a repository name configured in the WSHConfig.xml.

WSH_95100

Unable to connect to PowerCenter Server.

Cause:

This may occur if the PowerCenter Server is down or there is a network problem.

Action:

Make sure the PowerCenter Server is running and the network is up.

WSH_95101

Connection to PowerCenter Server is aborted.

Cause:

The connection to the PowerCenter Server is lost due to some internal problem.

Action:

Contact Informatica Technical Support.

WSH_95102

Connection to the PowerCenter Server is lost.

Cause:

This error may occur when you call a Batch Web Services function after calling the InitializeDIServerConnection function. This may happen if the PowerCenter Server goes down or there is a network problem.

Web Services Hub Level Errors

121

Action:

122

Make sure the PowerCenter Server is running and the network is up. Once the PowerCenter Server is running and the network is up, call the ‘InitializeDIServerConnection’ function.

Appendix A: Web Services Hub Error Messages

Index

A

Batch Web Services functions 56 overview 30 Browsing functions, details 52

generating in .Net 77 generating in Axis 73 commit type configuring 107 configuration file parameters 9 updating dynamically 21 configuring caching 106 commit type 107 logging levels 16 reader properties 103 Web Services Hub 21 writer properties 105 console Web Services Hub 37

C

D

caching configuring 106 Clean Up in Axis 76 using .Net 79 client applications developing 69 Client Proxy Classes generating 69

DeinitializeDIServerConnection function 57 documentation conventions xxvii description xxvi online xxvii

attachments mapping 97 authentication functions, details 51 security 41

B

123

E encryption configuration file 21 security 41 environment variables JAVA_HOME 13 JAVA_OPTS 14 shared library 14 system path 13, 14 WSH_HOME 13 Error Codes in SOAP 46 Web Services Hub 114 Error Handling in Axis 76 using .Net 79

F fault handling SOAP 45 fault messages importing 84 fault schema SOAP 46 flat file mappings 97 Functions DeinitializeDIServerConnection 57 GetAllDIServers 52 GetAllFolders 52 GetAllTaskInstances 52 GetAllWorkflows 52 GetDIServerConnectionState 57 GetDIServerProperties 58 GetSessionLog 64 GetSessionPerformanceData 63 GetSessionStatistics 62 GetTaskDetails 62 GettingWorkflowLog 64 GetWorkflowDetails 62 InitializeDIServerConnection 57 MonitorDIServer 62 PingDIServer 57 PowerCenter Server 57 ResumeTask 61 ResumeWorkflow 60 ScheduleWorkflow 59 StartTask 61

124

Index

StartWorkflow 59 StopDIServer 57 StopTask 61 StopWorkflow 59 UnscheduleWorkflow 59 WaitTillTaskComplete 61 WaitTillWorkflowComplete 59

G generating names setting option 87 Get Session Log function 64 GetAllDIServers function 52 GetAllFolders function 52 GetAllTaskInstances function 52 GetAllWorkflows function 52 GetDIServerConnectionState function 57 GetDIServerProperties function 58 GetSessionPerformanceData function 63 GetSessionStatistics function 62 GetTaskDetails function 62 Getting Workflow Log function 64 GetWorkflowDetails function 62

I importing fault messages 84 input messages 83 operations 83, 84 output messages 84 web service definitions 85 web service sources 83 infinite precision overriding 87

Informatica documentation xxvi Webzine xxviii Initialization in Axis 73 using .Net 77 InitializeDIServerConnection function 57 input messages importing 83 installation verifying 19 installation directories from install process 11 installing Web Services Hub 10

J JAVA_HOME configuring on UNIX 13 configuring on Windows 13

L load scope configuring 93 Log functions, detail 64 log file configuring 43 viewing 43 Login function 51 Logout function 51

M mappings attachment 97 flat file 97 one-way 95 request-response 95 staged 96 XML 97 Max Log Buffer Size Web Services Hub 65

messageID propagating 96 messages recovering 106 Metadata and Batch Function Calls in Axis 75 using .Net 79 metadata extensions web service definitions 91 Metadata Web Services described 31 MonitorDIServer function 62 Monitoring and Reporting functions 62

N naming columns option 87

O one-way mappings defined 95 operations importing 83, 84 output messages importing 84

P PingDIServer function 57 pipeline partitioning 107 PowerCenter Server functions, detail 57 precision overriding infinite length 87 protected described 102 published services viewing 38

R reader properties configuring 103 Index

125

Reader Time Limit description 104 real-time flush latency description 105 real-time sessions configuring source-based commit 107 defined 105 setting the real-time flush latency session property 105 Real-time Web Services overview 31 using the Designer 82 viewing published services 38 recovering messages 106 registering Web Services Hub 23 repository password encrypting 21 request-response mappings defined 95 ResumeTask function 61 ResumeWorkflow function 60 runnable described 102

S ScheduleWorkflow function 59 security authentication 41 encryption 41 service configuring 101 service sessions pipeline partitioning 107 service workflow creating 101 session maintenance in Axis 75 using .Net 78 Web Services Hub 47 session properties Reader Time Limit 104 real-time flush latency 105

126

Index

Simple Client error handling 71 initialization 69 session maintenance 70 SOAP Body 4 detail 46 Envelope 4 extended details 46 fault handling 45 fault structure 46 faultcode 46 faultstring 46 header 4 how web services work 2 presentation of 4 staged mapping defined 96 starting Web Services Hub 19 StartTask function 61 StartWorkflow function 59 StopDIServer function 57 stopping Web Services Hub 20 StopTask function 61 StopWorkflow function 59 system path setting 13, 14

T Task functions, detail 61 timeout described 102

U Universal Description, Discovery and Integration UDDI, overview 2 UnscheduleWorkflow function 59

UpdateConfigFile command line program 21 guidelines 22

V visible described 102

W WaitTillTaskComplete function 61 WaitTillWorkflowComplete function 59 Web Service configuring 101 web service source definitions 83 target definitions 84 web service definitions editing 89 viewing in the XML Editor 92 web service sessions 107 Web Service targets configuring load scope 93 Web Services Batch, overview 30 building blocks 3 Metadata Web Services, overview 31 web services batch functions, detail 56 Metadata Web Services functions, detail 50 overview 2 Web Services Description Language WSDL, detail 5 WSDL, overview 2 Web Services Hub configuration file 21 configuring 21 console 37 defined 30 installing on Unix 10 logging 16 Max Log Buffer Size 65 minimum system requirements 8 registering 23 session maintenance 47 starting 19 stopping 20

uninstalling 27 verifying installation 19 writing a client application in .Net using C# 77 writing a client application in Java using Axis 73 Web Services Provider architecture 32 webzine xxviii Workflow functions, detail 59 Workflow Manager registering the Web Services Hub 23 writer properties configuring 105 WSH.wsdl downloading 37 editing 15 WSH_HOME configuring on UNIX 13 WSHConfig.xml editing 15

X XML Editor viewing web service definitions 92

Index

127

128

Index