Web Services Provider Guide

Web Services Provider Guide

Informatica PowerCenter® (Version 7.1.1)

Informatica PowerCenter Web Services Provider GuideVersion 7.1.1August 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiNew 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Simple Object Access Protocol (SOAP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Web Services Description Language (WSDL) . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2: Installing and Configuring Web Services Hub . . . . . . . . . . 7Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . 29Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . 35Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . 49Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . 55Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . 67Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . 81Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . 99Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . 113Web Services Hub Level Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

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

Table of Contents vii

viii Table of Contents

List of Figures

Figure 1-1. Building Blocks of a Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Figure 2-1. Web Services Hub Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Figure 2-2. Web Services Hub Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Figure 3-1. Web Services Provider Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Figure 4-1. Web Services Hub Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Figure 4-2. Transformation Services Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Figure 4-3. Transformation Service Description Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Figure 8-1. Web Service Source Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Figure 8-2. Web Service Target Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Figure 8-3. Columns Tab for a Web Service Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Figure 8-4. Attributes Tab for a Web Service Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Figure 8-5. Metadata Extensions Tab for a Web Service Definition . . . . . . . . . . . . . . . . . . . . 92

Figure 8-6. XML Editor Views of Web Service Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Figure 8-7. Request-Response Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Figure 9-1. Creating a Service Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Figure 9-2. Web Service Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Figure 9-3. Web Services Provider Reader Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

List of Figures ix

x List of Figures

List of Tables

Table 2-1. Web Services Hub Installation Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Table 2-2. WSHConfig.xml Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Table 2-3. WSHLog.properties Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Table 2-4. config.xml Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Table 2-5. UpdateConfigFile Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Table 2-6. Web Services Hub Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Table 4-1. Transformation Services Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Table 4-2. Transformation Service Description Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Table 8-1. Web Services Definition Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Table 8-2. Message Header Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Table 8-3. Advanced Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Table 8-4. Required Sources and Targets in a Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Table 8-5. Attachment Group Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Table 9-1. Web Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Table 9-2. Web Services Provider Reader Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Table 9-3. Web Services Provider Writer Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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.1This 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♦ Code page. PowerCenter supports additional Japanese language code pages, such as JIPSE-

kana, 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.

xiv Preface

♦ 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.1This 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.

LicensingInformatica 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 ReporterPowerCenter 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 ControlYou 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♦ 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 request-response 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.

xviii Preface

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 MonitorThe 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 SupportPowerCenter 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.0This section describes new features and enhancements to PowerCenter 7.0.

Data ProfilingIf 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♦ 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

xx Preface

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 ReporterPowerCenter 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♦ 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

xxii Preface

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 ControlThe 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 SupportPowerCenter 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♦ 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.

xxiv Preface

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

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

xxvi Preface

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 ConventionsThis 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 PortalAs 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 WebzineThe 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 SiteYou 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 add-on solutions based on Informatica’s interoperability interfaces.

Obtaining Technical SupportThere 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 Corporation2100 Seaport Blvd.Redwood City, CA 94063Phone: 866.563.6332 or 650.385.5800Fax: 650.213.9489Hours: 6 a.m. - 6 p.m. (PST/PDT)email: [email protected]

Informatica Software Ltd.6 Waltham ParkWaltham Road, White WalthamMaidenhead, BerkshireSL6 3TNPhone: 44 870 606 1525Fax: +44 1628 511 411Hours: 9 a.m. - 5:30 p.m. (GMT)email: [email protected]

BelgiumPhone: +32 15 281 702Hours: 9 a.m. - 5:30 p.m. (local time)

FrancePhone: +33 1 41 38 92 26Hours: 9 a.m. - 5:30 p.m. (local time)

GermanyPhone: +49 1805 702 702Hours: 9 a.m. - 5:30 p.m. (local time)

NetherlandsPhone: +31 306 082 089Hours: 9 a.m. - 5:30 p.m. (local time)

SingaporePhone: +65 322 8589Hours: 9 a.m. - 5 p.m. (local time)

SwitzerlandPhone: +41 800 81 80 70Hours: 8 a.m. - 5 p.m. (local time)

Preface xxix

xxx Preface

C h a p t e r 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.


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


C h a p t e r 2

Installing and Configuring Web Services Hub


♦ 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 RequirementsThe 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 BeginYou need to install the following components before you can run services on the Web Services Hub:

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

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

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

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

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 WindowsUse 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 UNIXUse 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.


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 DirectoriesThe 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

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.

Table 2-1. Web Services Hub Installation Directories

Directory Name Description


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 VariablesYou 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 WindowsAfter 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 UNIXAfter 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:

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 WSH_HOME <Web Services Hub installation path>

Bourne shell export WSH_HOME <Web Services Hub installation path>

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:

Shared Library. Use the following syntax to set the shared library environment variables:

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

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

Operating System UNIX Shell Description

Solaris and Linux

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

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

HP-UX C shell setenv PATH <JAVA_HOME>/bin:${SHLIB_PATH}

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

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

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


Solaris and Linux

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

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

HP-UX C shell setenv SHLIB_PATH <WSH_HOME>/bin:${SHLIB_PATH}

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

AIX C shell setenv LIBPATH <WSH_HOME>/bin:${LIBPATH}

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


HP-UX Itanium C shell setenv JAVA_OPTS "-Xmx512m -Xms256m -d64"

Bourne shell export JAVA_OPTS="-Xmx512m -Xms256m -d64"


Editing WSHConfig.xmlManually 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:

3. Save and close the file.

Editing WSH.wsdlManually 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 <localhost> 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 GuidelinesUse 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 <localhost> 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.

Table 2-2. WSHConfig.xml Parameters

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.


Configuring Logging PropertiesThe 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:


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 HTTPSBy 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.xmlEdit jboss-service.xml to uncomment HTTPS entries and configure WSH_HOME.

Table 2-3. WSHLog.properties Parameters


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.


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\META-INF\

2. Uncomment the following entry in jboss-service.xml, and change WSH_HOME in the "KeyStoreURL" to the Web Services Hub installation directory:



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:



<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"

port="7333" minProcessors="3" maxProcessors="10"

enableLookups="true" acceptCount="10" debug="0"


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 HTTPSChange 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



<URLScheme>http</URLScheme>

Step 3. Replace the Keystore FileReplace 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


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 HubWhen 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.1-Start.

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

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.1-Console.

To verify the Web Services Hub installation on UNIX:

1. Open the following URL in the browser:

http://<host name:port number>/PowerCenter

For example, http://Benz:7333/PowerCenter

Stopping the Web Services HubUse 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.1-Stop.

To stop the Web Services Hub on UNIX:

1. Close the command window.

Figure 2-1. Web Services Hub Console


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:


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:

Table 2-4. config.xml Parameters


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.

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:

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

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

Table 2-5. UpdateConfigFile Options

Option Required/Optional Description

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


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:

5. Click OK.

Table 2-6. Web Services Hub Properties

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.


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



<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"

port="7333" minProcessors="3" maxProcessors="10"

enableLookups="true" acceptCount="10" debug="0"

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

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

<wsdl:port name="DataIntegration" binding="impl:DataIntegrationServiceSoapBinding">

<wsdlsoap:address location="http://localhost:7333/PowerCenter/services/DataIntegration"/>

</wsdl:port>

Editing the Port Number in WSHConfig.xmlIf 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:



<HubPortNumber>7333</HubPortNumber>


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


C h a p t e r 3

Understanding Web Services Provider


♦ 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 HubThe 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 ServicesBatch 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 ServicesUse 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:

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.

Figure 3-1. Web Services Provider Architecture

Web Service Client

Metadata Web Services

Real-time Web Services

Batch Web Services

PowerCenter Server

Web Services Hub

Repository Server

Repository

Service Workflow

WorkflowWeb Service Client

Application Server

Repository Server Communication

Real-time Web Services

Batch Web Services

Secu

rity G

atew

ay

Metadata Web Services


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


C h a p t e r 4

Understanding the Web Services Hub


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

Batch and Metadata Web ServicesYou 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:



<complexType name="LoginRequest">

<sequence>

<element name="RepositoryName" type="xsd:string"/>

<element name="UserName" type="xsd:string"/>

<element name="Password" type="xsd:string"/>

</sequence>

</complexType>

<element name="Login" type="impl:LoginRequest"/>

<element name="LoginReturn" type="xsd:string"/>

Figure 4-1. Web Services Hub Console

Using the Web Services Hub Console 37

Real-time ServicesYou 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


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

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:

Table 4-2 describes the properties on the Transformation Service Description 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.

Figure 4-3. Transformation Service Description Page

Table 4-2. Transformation Service Description Page


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

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.

Table 4-2. Transformation Service Description Page



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 InformationWeb Services Provider encrypts repository information in the configuration file and in responses to web service clients for login requests.

Encrypting the Configuration FileBefore 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 RequestsBefore 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. When the web service client submits a request to run a service, it includes the encrypted credentials in the header element.


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


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 HeaderThe 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

</ErrorCode

<ErrorMessage>

error message

</ErrorMessage>

</ns1:HeaderFault>

SOAP Fault Handling 45

SOAP Fault BodyThe 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>

<faultcode> Client/Server </faultcode>

<faultstring>Brief Description of Error</faultstring>

<detail>

<ns:WSHFaultDetails xmlns:ns=”www.informatica.com/PowerCenter”>

<ErrorCode> Error Code </ ErrorCode >

<ExtendedDetails> Actual Error </ ExtendedDetails >

</ns:WSHFaultDetails>

</detail>

</SOAP-ENV: Fault>


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

</SessionId>

</ns1:Context>

</soap:header>

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


C h a p t e r 5

Using Metadata Web Services Functions


♦ 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

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

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

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

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

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

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


GetAllRepositoriesYou 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


C h a p t e r 6

Using Batch Web Services Functions


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

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

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

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

GetDIServerConnectionStateYou 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

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

GetDIServerPropertiesYou can use this function to get the properties of the PowerCenter Server.

The PowerCenter Server properties include the following information:

♦ 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


Workflow Functions

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

StartWorkflowYou 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).

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

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

UnscheduleWorkflowYou can use this function to unschedule a workflow.

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

Workflow Functions 59

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


Task Functions

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

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

StopTaskYou 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).

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

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

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

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

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

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


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.

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

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

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


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 SizeThe 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


C h a p t e r 7

Writing Client Applications


♦ 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 ClassesTo 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.

InitializationYour 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 MaintenanceThe 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:

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.


Making Function CallsYou 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 ResourcesThe 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 HandlingSOAP 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 ObjectsThe 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.


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 AxisYou 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 AxisYour 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.


Session Maintenance in AxisThe 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 AxisYou 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 AxisCleanup releases the Web Services Hub resources acquired by client applications and performs cleanup operations.


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 AxisYou 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());

}


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 .NetYou 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 .NetYour 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 .NetThe 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.


Making Function Calls in .NetYou 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 .NetClean up releases the Web Services Hub resources acquired by client applications and performs cleanup operations.


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 .NetYou 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);

}


C h a p t e r 8

Working with Service Mappings


♦ 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 DefinitionsWhen 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.

Detail group has foreign key pointing to body group.

Header group has foreign key pointing to root group.

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

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:

For information about importing web service source definitions, see “Steps for Importing Web Service Sources and Targets” on page 85.

Importing Web Service Target DefinitionsWhen 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.

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.

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.


Figure 8-2 shows a sample output message and 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 TargetsWhen 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

Figure 8-2. Web Service Target DefinitionsOutput MessageFault Message


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

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

Choose to import from a local file or a URL.

Choose to display import errors.

Select a URL.

Configure default precision.


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

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.

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.


5. Choose an operation from the Import from WSDL dialog box:

6. Click OK twice.

The web service definition appears in the workspace.


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 DesignerWeb 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 TabThe 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:

Attributes TabThe Attributes tab is a read-only tab that displays the XPath and XMLDataType values for each field in a source or target definition. If the definition has an Attachment group, the Attributes tab displays the MIME type in the data field.

Figure 8-3. Columns Tab for a Web Service Definition


Figure 8-4 shows the Attributes tab for a web service target definition:

Metadata Extensions TabYou 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.

Figure 8-4. Attributes Tab for a Web Service Definition

MIME Type of Attachment


Figure 8-5 shows the Metadata Extensions tab for a web service source definition:

View Definitions in the XML EditorAfter 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.

Figure 8-5. Metadata Extensions Tab for a Web Service Definition

Displays message type as input, output, or fault.


Figure 8-6 shows the XML Editor view of the source definition shown in Figure 8-1 on page 83:

To view a web service definition in the XML Editor:

Right-click a definition and choose WSDL Workspace.

Editing Web Service Targets in a MappingWhen 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.

Figure 8-6. XML Editor Views of Web Service Definition


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


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 one-way 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:

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.

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.

Working with Service Mappings 95

Request-Response MappingsA request-response mapping uses a web service source and target. When you create a request-response 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:

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

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.

Figure 8-7. Request-Response Mapping


Flat File or XML MappingsYou 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 MappingsBased 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:

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.

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.

Working with Service Mappings 97


C h a p t e r 9

Working With Service Workflows


♦ 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 WorkflowWhen 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:

Configuring the ServiceWhen you configure a service, you configure a service name, timeout, and accessibility options.

Figure 9-1. Creating a Service Workflow

Create a service workflow.

Configure service.

Creating and Configuring a Service 101

Figure 9-2 shows the Config Service dialog box:

Table 9-1 describes the properties you can configure for a web service:

Figure 9-2. Web Service Configuration

Table 9-1. Web Service Properties

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.


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

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

Figure 9-3. Web Services Provider Reader Properties

Table 9-2. Web Services Provider Reader Properties

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.


Configuring Real-time Flush LatencyUse 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 WriterWhen you configure session properties for a Web Services Provider writer, you configure cache size and cache directory.

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.

Table 9-2. Web Services Provider Reader Properties

Property Source Type Description


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

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 CachingThe 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 MessagesWhen 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.

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.


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 TypeWhen 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 CommitIf 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 CommitIf you configure a target-based commit, the PowerCenter Server runs the session using source-based 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 PartitioningWhen 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


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.


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 SessionsYou 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 LatencyWhen 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.


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

AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA

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


A p p e n d i x 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

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.

114 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

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.


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 <repository name> 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.


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 <folder name> 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



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: <Description of Error>

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.


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.


WSH_95053 Timeout value is not valid. The timeout value <timeout> 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: <Description of Error>.

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 <repository name>. 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.


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.


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


I n d e x

Aattachments

mapping 97authentication

functions, details 51security 41

BBatch Web Services

functions 56overview 30

Browsingfunctions, details 52

Ccaching

configuring 106Clean Up

in Axis 76using .Net 79

client applicationsdeveloping 69

Client Proxy Classesgenerating 69

generating in .Net 77generating in Axis 73

commit typeconfiguring 107

configuration fileparameters 9updating dynamically 21

configuringcaching 106commit type 107logging levels 16reader properties 103Web Services Hub 21writer properties 105

consoleWeb Services Hub 37

DDeinitializeDIServerConnection

function 57documentation

conventions xxviidescription xxvionline xxvii

123

Eencryption

configuration file 21security 41

environment variablesJAVA_HOME 13JAVA_OPTS 14shared library 14system path 13, 14WSH_HOME 13

Error Codesin SOAP 46Web Services Hub 114

Error Handlingin Axis 76using .Net 79

Ffault handling

SOAP 45fault messages

importing 84fault schema

SOAP 46flat file

mappings 97Functions

DeinitializeDIServerConnection 57GetAllDIServers 52GetAllFolders 52GetAllTaskInstances 52GetAllWorkflows 52GetDIServerConnectionState 57GetDIServerProperties 58GetSessionLog 64GetSessionPerformanceData 63GetSessionStatistics 62GetTaskDetails 62GettingWorkflowLog 64GetWorkflowDetails 62InitializeDIServerConnection 57MonitorDIServer 62PingDIServer 57PowerCenter Server 57ResumeTask 61ResumeWorkflow 60ScheduleWorkflow 59StartTask 61

StartWorkflow 59StopDIServer 57StopTask 61StopWorkflow 59UnscheduleWorkflow 59WaitTillTaskComplete 61WaitTillWorkflowComplete 59

Ggenerating names

setting option 87Get Session Log

function 64GetAllDIServers

function 52GetAllFolders

function 52GetAllTaskInstances

function 52GetAllWorkflows

function 52GetDIServerConnectionState

function 57GetDIServerProperties

function 58GetSessionPerformanceData

function 63GetSessionStatistics

function 62GetTaskDetails

function 62Getting Workflow Log

function 64GetWorkflowDetails

function 62

Iimporting

fault messages 84input messages 83operations 83, 84output messages 84web service definitions 85web service sources 83

infinite precisionoverriding 87

124 Index

Informaticadocumentation xxviWebzine xxviii

Initializationin Axis 73using .Net 77

InitializeDIServerConnectionfunction 57

input messagesimporting 83

installationverifying 19

installation directoriesfrom install process 11

installingWeb Services Hub 10

JJAVA_HOME

configuring on UNIX 13configuring on Windows 13

Lload scope

configuring 93Log

functions, detail 64log file

configuring 43viewing 43

Loginfunction 51

Logoutfunction 51

Mmappings

attachment 97flat file 97one-way 95request-response 95staged 96XML 97

Max Log Buffer SizeWeb Services Hub 65

messageIDpropagating 96

messagesrecovering 106

Metadata and Batch Function Callsin Axis 75using .Net 79

metadata extensionsweb service definitions 91

Metadata Web Servicesdescribed 31

MonitorDIServerfunction 62

Monitoring and Reportingfunctions 62

Nnaming columns

option 87

Oone-way mappings

defined 95operations

importing 83, 84output messages

importing 84

PPingDIServer

function 57pipeline partitioning 107PowerCenter Server

functions, detail 57precision

overriding infinite length 87protected

described 102published services

viewing 38

Rreader properties

configuring 103

Index 125

Reader Time Limitdescription 104

real-time flush latencydescription 105

real-time sessionsconfiguring source-based commit 107defined 105setting the real-time flush latency session property 105

Real-time Web Servicesoverview 31using the Designer 82viewing published services 38

recoveringmessages 106

registeringWeb Services Hub 23

repository passwordencrypting 21

request-response mappingsdefined 95

ResumeTaskfunction 61

ResumeWorkflowfunction 60

runnabledescribed 102

SScheduleWorkflow

function 59security

authentication 41encryption 41

serviceconfiguring 101

service sessionspipeline partitioning 107

service workflowcreating 101

session maintenancein Axis 75using .Net 78Web Services Hub 47

session propertiesReader Time Limit 104real-time flush latency 105

Simple Clienterror handling 71initialization 69session maintenance 70

SOAPBody 4detail 46Envelope 4extended details 46fault handling 45fault structure 46faultcode 46faultstring 46header 4how web services work 2presentation of 4

staged mappingdefined 96

startingWeb Services Hub 19

StartTaskfunction 61

StartWorkflowfunction 59

StopDIServerfunction 57

stoppingWeb Services Hub 20

StopTaskfunction 61

StopWorkflowfunction 59

system pathsetting 13, 14

TTask

functions, detail 61timeout

described 102

UUniversal Description, Discovery and Integration

UDDI, overview 2UnscheduleWorkflow

function 59

126 Index

UpdateConfigFilecommand line program 21guidelines 22

Vvisible

described 102

WWaitTillTaskComplete

function 61WaitTillWorkflowComplete

function 59Web Service

configuring 101web service

source definitions 83target definitions 84

web service definitionsediting 89viewing in the XML Editor 92

web service sessions 107Web Service targets

configuring load scope 93Web Services

Batch, overview 30building blocks 3Metadata Web Services, overview 31

web servicesbatch functions, detail 56Metadata Web Services functions, detail 50overview 2

Web Services Description LanguageWSDL, detail 5WSDL, overview 2

Web Services Hubconfiguration file 21configuring 21console 37defined 30installing on Unix 10logging 16Max Log Buffer Size 65minimum system requirements 8registering 23session maintenance 47starting 19stopping 20

uninstalling 27verifying installation 19writing a client application in .Net using C# 77writing a client application in Java using Axis 73

Web Services Providerarchitecture 32

webzine xxviiiWorkflow

functions, detail 59Workflow Manager

registering the Web Services Hub 23writer properties

configuring 105WSH.wsdl

downloading 37editing 15

WSH_HOMEconfiguring on UNIX 13

WSHConfig.xmlediting 15

XXML Editor

viewing web service definitions 92

Index 127

128 Index

Documents

Web Services Provider Guide