Web Services Provider Guide

Informatica PowerCenter®
(Version 7.1.1)
Informatica PowerCenter Web Services Provider Guide
Version 7.1.1
August 2004

Copyright (c) 1998–2004 Informatica Corporation.

All rights reserved. Printed in the USA.

This software and documentation contain proprietary information of Informatica Corporation, they are provided under a license agreement
containing restrictions on use and disclosure and is also protected by copyright law. Reverse engineering of the software is prohibited. No
part of this document may be reproduced or transmitted in any form, by any means (electronic, photocopying, recording or otherwise)
without prior consent of Informatica Corporation.

Use, duplication, or disclosure of the Software by the U.S. Government is subject to the restrictions set forth in the applicable software
license agreement as provided in DFARS 227.7202-1(a) and 227.7702-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR
12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14 (ALT III), as applicable.

The information in this document is subject to change without notice. If you find any problems in the documentation, please report them to
us in writing. Informatica Corporation does not warrant that this documentation is error free.
Informatica, PowerMart, PowerCenter, PowerChannel, PowerConnect, MX, and SuperGlue are trademarks or registered trademarks of
Informatica Corporation in the United States and in jurisdictions throughout the world. All other company and product names may be trade
names or trademarks of their respective owners.

Portions of this software are copyrighted by DataDirect Technologies, 1999-2002.

Informatica PowerCenter products contain ACE (TM) software copyrighted by Douglas C. Schmidt and his research group at Washington
University and University of California, Irvine, Copyright (c) 1993-2002, all rights reserved.

Portions of this software contain copyrighted material from The JBoss Group, LLC. Your right to use such materials is set forth in the GNU
Lesser General Public License Agreement, which may be found at http://www.opensource.org/licenses/lgpl-license.php. The JBoss materials
are provided free of charge by Informatica, “as-is”, without warranty of any kind, either express or implied, including but not limited to the
implied warranties of merchantability and fitness for a particular purpose.

Portions of this software contain copyrighted material from Meta Integration Technology, Inc. Meta Integration® is a registered trademark
of Meta Integration Technology, Inc.

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
The Apache Software is Copyright (c) 1999-2004 The Apache Software Foundation. All rights reserved.

DISCLAIMER: Informatica Corporation provides this documentation “as is” without warranty of any kind, either express or implied,
including, but not limited to, the implied warranties of non-infringement, merchantability, or use for a particular purpose. The information
provided in this documentation may include technical inaccuracies or typographical errors. Informatica could make improvements and/or
changes in the products described in this documentation at any time without notice.
Table of Contents
List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
New Features and Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
PowerCenter 7.1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xiv
PowerCenter 7.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi
PowerCenter 7.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx
About Informatica Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
About this Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Other Informatica Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Visiting Informatica Customer Portal . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Visiting the Informatica Webzine . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Visiting the Informatica Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Visiting the Informatica Developer Network . . . . . . . . . . . . . . . . . . . xxviii
Obtaining Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix

Chapter 1: Web Services Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

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

Chapter 2: Installing and Configuring Web Services Hub . . . . . . . . . . 7

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

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

Chapter 3: Understanding Web Services Provider . . . . . . . . . . . . . . 29

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Web Services Hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Batch Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Metadata Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Real-time Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Web Services Provider Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 4: Understanding the Web Services Hub . . . . . . . . . . . . . . . 35

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

iv Table of Contents
 SOAP Fault Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Session Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Chapter 5: Using Metadata Web Services Functions . . . . . . . . . . . . 49

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Authentication Request Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Browsing Request Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
GetAllFolders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
GetAllWorkflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
GetAllTaskInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
GetAllDIServers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
GetAllRepositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 6: Using Batch Web Services Functions . . . . . . . . . . . . . . . 55

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

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

Chapter 7: Writing Client Applications . . . . . . . . . . . . . . . . . . . . . . . . 67

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

Chapter 8: Working with Service Mappings . . . . . . . . . . . . . . . . . . . . 81

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

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

Chapter 9: Working With Service Workflows . . . . . . . . . . . . . . . . . . . 99

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

Appendix A: Web Services Hub Error Messages . . . . . . . . . . . . . . . 113

Web Services Hub Level Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

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

Table of Contents vii

viii Table of Contents
List of Figures
Figure 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.1
This section describes new features and enhancements to PowerCenter 7.1.1.

Data Profiling
♦ Data sampling. You can create a data profile for a sample of source data instead of the
entire source. You can view a profile from a random sample of data, a specified percentage
of data, or for a specified number of rows starting with the first row.
♦ Verbose data enhancements. You can specify the type of verbose data you want the
PowerCenter Server to write to the Data Profiling warehouse. The PowerCenter Server can
write all rows, the rows that meet the business rule, or the rows that do not meet the
business rule.
♦ Session enhancement. You can save sessions that you create from the Profile Manager to
the repository.
♦ Domain Inference function tuning. You can configure the Data Profiling Wizard to filter
the Domain Inference function results. You can configure a maximum number of patterns
and a minimum pattern frequency. You may want to narrow the scope of patterns returned
to view only the primary domains, or you may want to widen the scope of patterns
returned to view exception data.
♦ Row Uniqueness function. You can determine unique rows for a source based on a
selection of columns for the specified source.
♦ Define mapping, session, and workflow prefixes. You can define default mapping,
session, and workflow prefixes for the mappings, sessions, and workflows generated when
you create a data profile.
♦ Profile mapping display in the Designer. The Designer displays profile mappings under a
profile mappings node in the Navigator.

PowerCenter Server
♦ 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.1
This section describes new features and enhancements to PowerCenter 7.1.

Data Profiling
♦ Data Profiling for VSAM sources. You can now create a data profile for VSAM sources.
♦ Support for verbose mode for source-level functions. You can now create data profiles
with source-level functions and write data to the Data Profiling warehouse in verbose
mode.
♦ Aggregator function in auto profiles. Auto profiles now include the Aggregator function.
♦ Creating auto profile enhancements. You can now select the columns or groups you want
to include in an auto profile and enable verbose mode for the Distinct Value Count
function.
♦ Purging data from the Data Profiling warehouse. You can now purge data from the Data
Profiling warehouse.
♦ Source View in the Profile Manager. You can now view data profiles by source definition
in the Profile Manager.
♦ PowerCenter Data Profiling report enhancements. You can now view PowerCenter Data
Profiling reports in a separate browser window, resize columns in a report, and view
verbose data for Distinct Value Count functions.
♦ Prepackaged domains. Informatica provides a set of prepackaged domains that you can
include in a Domain Validation function in a data profile.

Documentation
♦ Web Services Provider Guide. This is a new book that describes the functionality of Real-time
Web Services. It also includes information from the version 7.0 Web Services Hub Guide.
♦ XML User Guide. This book consolidates XML information previously documented in the
Designer Guide, Workflow Administration Guide, and Transformation Guide.

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

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

PowerCenter Server
♦ 64-bit support. You can now run 64-bit PowerCenter Servers on AIX and HP-UX
(Itanium).
♦ Partitioning enhancements. If you have the Partitioning option, you can define up to 64
partitions at any partition point in a pipeline that supports multiple partitions.
♦ PowerCenter Server processing enhancements. The PowerCenter Server now reads a
block of rows at a time. This improves processing performance for most sessions.
♦ CLOB/BLOB datatype support. You can now read and write CLOB/BLOB datatypes.

PowerCenter Metadata Reporter

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

Repository Server
♦ Updating repository statistics. PowerCenter now identifies and updates statistics for all
repository tables and indexes when you copy, upgrade, and restore repositories. This
improves performance when PowerCenter accesses the repository.
♦ Increased repository performance. You can increase repository performance by skipping
information when you copy, back up, or restore a repository. You can choose to skip MX
data, workflow and session log history, and deploy group history.
♦ pmrep. You can use pmrep to back up, disable, or enable a repository, delete a relational
connection from a repository, delete repository details, truncate log files, and run multiple
pmrep commands sequentially. You can also use pmrep to create, modify, and delete a
folder.

Repository
♦ Exchange metadata with business intelligence tools. You can export metadata to and
import metadata from other business intelligence tools, such as Cognos Report Net and
Business Objects.
♦ Object import and export enhancements. You can compare objects in an XML file to
objects in the target repository when you import objects.
♦ MX views. MX views have been added to help you analyze metadata stored in the
repository. REP_SERVER_NET and REP_SERVER_NET_REF views allow you to see
information about server grids. REP_VERSION_PROPS allows you to see the version
history of all objects in a PowerCenter repository.

Preface xvii
 Transformations
♦ Flat file lookup. You can now perform lookups on flat files. When you create a Lookup
transformation using a flat file as a lookup source, the Designer invokes the Flat File
Wizard. You can also use a lookup file parameter if you want to change the name or
location of a lookup between session runs.
♦ Dynamic lookup cache enhancements. When you use a dynamic lookup cache, the
PowerCenter Server can ignore some ports when it compares values in lookup and input
ports before it updates a row in the cache. Also, you can choose whether the PowerCenter
Server outputs old or new values from the lookup/output ports when it updates a row. You
might want to output old values from lookup/output ports when you use the Lookup
transformation in a mapping that updates slowly changing dimension tables.
♦ Union transformation. You can use the Union transformation to merge multiple sources
into a single pipeline. The Union transformation is similar to using the UNION ALL SQL
statement to combine the results from two or more SQL statements.
♦ Custom transformation API enhancements. The Custom transformation API includes
new array-based functions that allow you to create procedure code that receives and
outputs a block of rows at a time. Use these functions to take advantage of the
PowerCenter Server processing enhancements.
♦ Midstream XML transformations. You can now create an XML Parser transformation or
an XML Generator transformation to parse or generate XML inside a pipeline. The XML
transformations enable you to extract XML data stored in relational tables, such as data
stored in a CLOB column. You can also extract data from messaging systems, such as
TIBCO or IBM MQSeries.

Usability
♦ Viewing active folders. The Designer and the Workflow Manager highlight the active
folder in the Navigator.
♦ Enhanced printing. The quality of printed workspace has improved.

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

Web Services Provider

♦ 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 Monitor
The Workflow Monitor includes the following performance and usability enhancements:
♦ When you connect to the PowerCenter Server, you no longer distinguish between online
or offline mode.
♦ You can open multiple instances of the Workflow Monitor on one machine.
♦ You can simultaneously monitor multiple PowerCenter Servers registered to the same
repository.
♦ The Workflow Monitor includes improved options for filtering tasks by start and end
time.
♦ The Workflow Monitor displays workflow runs in Task view chronologically with the most
recent run at the top. It displays folders alphabetically.
♦ You can remove the Navigator and Output window.

XML Support
PowerCenter XML support now includes the following features:
♦ Enhanced datatype support. You can use XML schemas that contain simple and complex
datatypes.
♦ Additional options for XML definitions. When you import XML definitions, you can
choose how you want the Designer to represent the metadata associated with the imported
files. You can choose to generate XML views using hierarchy or entity relationships. In a
view with hierarchy relationships, the Designer expands each element and reference under
its parent element. When you create views with entity relationships, the Designer creates
separate entities for references and multiple-occurring elements.
♦ Synchronizing XML definitions. You can synchronize one or more XML definition when
the underlying schema changes. You can synchronize an XML definition with any
repository definition or file used to create the XML definition, including relational sources
or targets, XML files, DTD files, or schema files.
♦ XML workspace. You can edit XML views and relationships between views in the
workspace. You can create views, add or delete columns from views, and define
relationships between views.
♦ Midstream XML transformations. You can now create an XML Parser transformation or
an XML Generator transformation to parse or generate XML inside a pipeline. The XML
transformations enable you to extract XML data stored in relational tables, such as data
stored in a CLOB column. You can also extract data from messaging systems, such as
TIBCO or IBM MQSeries.

Preface xix
 ♦ Support for circular references. Circular references occur when an element is a direct or
indirect child of itself. PowerCenter now supports XML files, DTD files, and XML
schemas that use circular definitions.
♦ Increased performance for large XML targets. You can create XML files of several
gigabytes in a PowerCenter 7.1 XML session by using the following enhancements:
− Spill to disk. You can specify the size of the cache used to store the XML tree. If the size
of the tree exceeds the cache size, the XML data spills to disk in order to free up
memory.
− User-defined commits. You can define commits to trigger flushes for XML target files.
− Support for multiple XML output files. You can output XML data to multiple XML
targets. You can also define the file names for XML output files in the mapping.

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

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

Data Integration Web Services

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

Documentation
♦ 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 Reporter

PowerCenter Metadata Reporter replaces Runtime Metadata Reporter and Informatica
Metadata Reporter. PowerCenter Metadata Reporter includes the following features:
♦ Metadata browsing. You can use PowerCenter Metadata Reporter to browse PowerCenter
7.0 metadata, such as workflows, worklets, mappings, source and target tables, and
transformations.
♦ Metadata analysis. You can use PowerCenter Metadata Reporter to analyze operational
metadata, including session load time, server load, session completion status, session
errors, and warehouse growth.

PowerCenter Server
♦ DB2 bulk loading. You can enable bulk loading when you load to IBM DB2 8.1.
♦ Distributed processing. If you purchase the Server Grid option, you can group
PowerCenter Servers registered to the same repository into a server grid. In a server grid,
PowerCenter Servers balance the workload among all the servers in the grid.
♦ Row error logging. The session configuration object has new properties that allow you to
define error logging. You can choose to log row errors in a central location to help
understand the cause and source of errors.
♦ External loading enhancements. When using external loaders on Windows, you can now
choose to load from a named pipe. When using external loaders on UNIX, you can now
choose to load from staged files.

Preface xxi
 ♦ External loading using Teradata Warehouse Builder. You can use Teradata Warehouse
Builder to load to Teradata. You can choose to insert, update, upsert, or delete data.
Additionally, Teradata Warehouse Builder can simultaneously read from multiple sources
and load data into one or more tables.
♦ Mixed mode processing for Teradata external loaders. You can now use data driven load
mode with Teradata external loaders. When you select data driven loading, the
PowerCenter Server flags rows for insert, delete, or update. It writes a column in the target
file or named pipe to indicate the update strategy. The control file uses these values to
determine how to load data to the target.
♦ Concurrent processing. The PowerCenter Server now reads data concurrently from
sources within a target load order group. This enables more efficient joins with minimal
usage of memory and disk cache.
♦ Real time processing enhancements. You can now use real-time processing in sessions that
also process active transformations, such as the Aggregator transformation. You can apply
the transformation logic to rows defined by transaction boundaries.

Repository Server
♦ Object export and import enhancements. You can now export and import objects using
the Repository Manager and pmrep. You can export and import multiple objects and
objects types. You can export and import objects with or without their dependent objects.
You can also export objects from a query result or objects history.
♦ pmrep commands. You can use pmrep to perform change management tasks, such as
maintaining deployment groups and labels, checking in, deploying, importing, exporting,
and listing objects. You can also use pmrep to run queries. The deployment and object
import commands require you to use a control file to define options and resolve conflicts.
♦ Trusted connections. You can now use a Microsoft SQL Server trusted connection to
connect to the repository.

Security
♦ 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 Control
The PowerCenter Client and repository introduce features that allow you to create and
manage multiple versions of objects in the repository. Version control allows you to maintain
multiple versions of an object, control development on the object, track changes, and use
deployment groups to copy specific groups of objects from one repository to another. Version
control in PowerCenter includes the following features:
♦ Object versioning. Individual objects in the repository are now versioned. This allows you
to store multiple copies of a given object during the development cycle. Each version is a
separate object with unique properties.
♦ Check out and check in versioned objects. You can check out and reserve an object you
want to edit, and check in the object when you are ready to create a new version of the
object in the repository.
♦ Compare objects. The Repository Manager and Workflow Manager allow you to compare
two repository objects of the same type to identify differences between them. You can
compare Designer objects and Workflow Manager objects in the Repository Manager. You
can compare tasks, sessions, worklets, and workflows in the Workflow Manager. The
PowerCenter Client tools allow you to compare objects across open folders and
repositories. You can also compare different versions of the same object.
♦ Delete or purge a version. You can delete an object from view and continue to store it in
the repository. You can recover or undelete deleted objects. If you want to permanently
remove an object version, you can purge it from the repository.
♦ Deployment. Unlike copying a folder, copying a deployment group allows you to copy a
select number of objects from multiple folders in the source repository to multiple folders
in the target repository. This gives you greater control over the specific objects copied from
one repository to another.

Preface xxiii
 ♦ Deployment groups. You can create a deployment group that contains references to
objects from multiple folders across the repository. You can create a static deployment
group that you manually add objects to, or create a dynamic deployment group that uses a
query to populate the group.
♦ Labels. A label is an object that you can apply to versioned objects in the repository. This
allows you to associate multiple objects in groups defined by the label. You can use labels
to track versioned objects during development, improve query results, and organize groups
of objects for deployment or export and import.
♦ Queries. You can create a query that specifies conditions to search for objects in the
repository. You can save queries for later use. You can make a private query, or you can
share it with all users in the repository.
♦ Track changes to an object. You can view a history that includes all versions of an object
and compare any version of the object in the history to any other version. This allows you
to see the changes made to an object over time.

XML Support
PowerCenter contains XML features that allow you to validate an XML file against an XML
schema, declare multiple namespaces, use XPath to locate XML nodes, increase performance
for large XML files, format your XML file output for increased readability, and parse or
generate XML data from various sources. XML support in PowerCenter includes the
following features:
♦ XML schema. You can use an XML schema to validate an XML file and to generate source
and target definitions. XML schemas allow you to declare multiple namespaces so you can
use prefixes for elements and attributes. XML schemas also allow you to define some
complex datatypes.
♦ XPath support. The XML wizard allows you to view the structure of XML schema. You
can use XPath to locate XML nodes.
♦ Increased performance for large XML files. When you process an XML file or stream, you
can set commits and periodically flush XML data to the target instead of writing all the
output at the end of the session. You can choose to append the data to the same target file
or create a new target file after each flush.
♦ XML target enhancements. You can format the XML target file so that you can easily view
the XML file in a text editor. You can also configure the PowerCenter Server to not output
empty elements to the XML target.

Usability
♦ 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 Conventions
This guide uses the following formatting conventions:

If you see… It means…

italicized text The word or set of words are especially emphasized.

boldfaced text Emphasized subjects.

italicized monospaced text This is the variable name for a value you enter as part of an
operating system command. This is generic text that should be
replaced with user-supplied values.

Note: The following paragraph provides additional facts.

Tip: The following paragraph provides suggested uses.

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

monospaced text This is a code example.

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

Preface xxvii
Other Informatica Resources
In addition to the product manuals, Informatica provides these other resources:
♦ Informatica Customer Portal
♦ Informatica Webzine
♦ Informatica web site
♦ Informatica Developer Network
♦ Informatica Technical Support

Visiting Informatica Customer Portal

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

Visiting the Informatica Webzine

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

Visiting the Informatica Web Site

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

Visiting the Informatica Developer Network

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

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

Obtaining Technical Support

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

North America / South America Africa / Asia / Australia / Europe

Informatica Corporation Informatica Software Ltd.

2100 Seaport Blvd. 6 Waltham Park
Redwood City, CA 94063 Waltham Road, White Waltham
Phone: 866.563.6332 or 650.385.5800 Maidenhead, Berkshire
Fax: 650.213.9489 SL6 3TN
Hours: 6 a.m. - 6 p.m. (PST/PDT) Phone: 44 870 606 1525
email: [email protected] Fax: +44 1628 511 411
Hours: 9 a.m. - 5:30 p.m. (GMT)
email: [email protected]

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

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

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

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

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

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

Preface xxix
xxx Preface
 Chapter 1

Web Services Concepts

This chapter includes the following topics:

♦ Overview, 2
♦ Simple Object Access Protocol (SOAP), 4
♦ Web Services Description Language (WSDL), 5

1
Overview
Web services are business functions that operate over the Web. They describe a collection of
operations that are network accessible through standardized XML messaging. PowerCenter
Web Services Provider allows you to integrate Informatica’s metadata and data integration
functionalities. You can write applications that can communicate with PowerCenter Servers
using any language and platform. You can embed these applications easily in existing
components and products.
Web services are based on open standards, such as XML, SOAP, and WSDL, which offer
greater interoperability than traditional proprietary applications.
Examples of web services include business services, such as stock quotes, airline schedules, and
credit checks.
The components that enable web services include:
♦ Simple Object Access Protocol (SOAP). SOAP is the communications protocol for web
services. It is the specification that defines the XML format for web services messages.
♦ Web Service Definition Language (WSDL). WSDL is an XML document that describes
web services requests and responses. Similar to the IDL file for COM and CORBA, a
WSDL file is a contract between client and server.
♦ Registry. Directory of published web services. Some web service providers publish services
in Universal Description, Discovery, and Integration (UDDI). Registering a web service in
the UDDI is optional. PowerCenter Web Services Provider does not use the UDDI
registry.
To build your own web service client, you can start by searching the registry to find published
web services. Next, you select web service you want to interface with and retrieve the WSDL
file for the designated web service. Using a web services tool kit such as Axis, generate the
client proxies. The client proxies contain all of the function calls required to interact with a
web service.
You can determine what functions a web service offers, the data the web services require, and
location of services by examining the self descriptive language of the WSDL files. The Web
Services Description Language (WSDL) describes the web services interfaces with enough
detail to allow a developer to build a client application to interact with them. Developers
write them according to open standards. For more information about writing client
applications, see “Writing Client Applications” on page 67.

2 Chapter 1: Web Services Concepts

Figure 1-1 shows the building blocks of a web service:

Figure 1-1. Building Blocks of a Web Service

Overview 3
Simple Object Access Protocol (SOAP)
SOAP is the communications protocol for web services. It defines the XML format for web
services messages. SOAP encodings tell the SOAP runtime environment how to translate from
data structures, such as Java into SOAP XML. SOAP and the Web Services Description
Language (WSDL) dictate the communication between web services and their clients.
A SOAP message contains the following sections:
♦ SOAP envelope. The envelope defines the framework of the message, what is in the
message, who or what should deal with it, and whether it is optional or mandatory.
♦ SOAP header. The header is a child element of the SOAP envelope that allows you to add
features to a SOAP message in a decentralized manner.
♦ SOAP body. The body is the container for mandatory information that provides a
mechanism for exchanging information with the intended recipient.
Authentication and transaction management are typical examples of extensions that can be
implemented as header entries. The SOAP header helps to process the data in the body of the
SOAP Message. Information related to authentication or transactions is usually contained in
the header because this information identifies the person or company that sent the SOAP
message body and in what context it will be processed.
You can use a SOAP toolkit to create and parse SOAP messages. A SOAP toolkit translates
function calls from another language to a SOAP message. For example, the Apache Axis
toolkit translates Java function calls to SOAP.
You can use SOAP to implement web services on different platforms both inside and outside
an organization. Each SOAP implementation supports different function calls and
parameters. Therefore, a function that works with one toolkit may not work with another.

4 Chapter 1: Web Services Concepts

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

Web Services Description Language (WSDL) 5

6 Chapter 1: Web Services Concepts
 Chapter 2

Installing and Configuring

Web Services Hub
This chapter includes the following topics:
♦ Overview, 8
♦ Step 1. Install the Web Services Hub, 10
♦ Step 2. Configure the Web Services Hub, 13
♦ Step 3. Start the Web Services Hub, 19
♦ Step 4. Run UpdateConfigFile, 21
♦ Step 5. Register the Web Services Hub, 23
♦ Changing the Web Services Hub Port Number, 25
♦ Uninstalling Web Services Hub, 27

7
Overview
The Web Services Hub is a PowerCenter service gateway that you install on an application
server. You do not need to install it on the same machine as any PowerCenter component. You
configure it with repository connectivity information and other parameters.
To install and configure the Web Services Hub, complete the following steps:
1. Install the Web Services Hub. For more information, see “Step 1. Install the Web
Services Hub” on page 10. Web Services Hub supports JBoss 3.2.1. The Web Services
Hub installation program installs JBoss.
2. Configure the Web Services Hub. Configure environment variables, static Web Services
Hub parameters, and logging levels. For more information, see “Step 2. Configure the
Web Services Hub” on page 13.
3. Verify the Web Services Hub installation. For more information, see “Step 3. Start the
Web Services Hub” on page 19.
4. Run UpdateConfigFile. Update the configuration file with dynamic parameters. For
more information, see “Step 4. Run UpdateConfigFile” on page 21.
5. Register the Web Services Hub with a repository. If you use Real-time Web Services, you
register the Web Services Hub to the repository. For more information, see “Step 5.
Register the Web Services Hub” on page 23.

Minimum System Requirements

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

Before You Begin

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

Platform J2SE Version

Windows 1.4.1

Solaris 1.3.1, 1.4.1, or 1.4.2

AIX 1.4.1 or 1.4.2

HP-UX 1.4.1 or 1.4.2

Linux IBM Java 1.3.1

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

Understanding the Configuration File

The installation program installs WSHConfig.xml in the Web Services Hub installation
\config directory. You configure WSHConfig.xml before and after you start the Web Services
Hub:
♦ Before you start the Web Services Hub. Configure static parameters, such as the Web
Services Hub host name and port number, before you start the Web Services Hub. To
configure this information, manually edit the configuration file. For more information, see
“Step 2. Configure the Web Services Hub” on page 13.
♦ After you start the Web Services Hub. Register repositories and configure dynamic
parameters after you start the Web Services Hub. To configure this information, you use
the command line program, UpdateConfigFile. For more information, see “Step 4. Run
UpdateConfigFile” on page 21.

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

Installing the Web Services Hub on Windows

Use the following procedure to install the Web Services Hub on Windows.

To install the Web Services Hub on Windows:

1. Log on to the machine as a user who is a member of the local Administrators group.
2. From Windows, browse the CD and run launch.exe.
3. Click Web Services Hub.
4. Click Next.
5. Click Browse to choose a destination folder for the Web Services Hub installation. Or,
click Next to accept the default.
Note: Do not use spaces in the install path if you install the Web Services Hub in a
location other than the default location.
6. Click Install.
After the installation completes, the installation program prompts you to set
JAVA_HOME and add JAVA_HOME\bin to your system path. For more information,
see “Configuring Environment Variables” on page 13.
7. Click OK.
8. Click Finish to exit Setup.

Installing the Web Services Hub on UNIX

Use the following procedure to install the Web Services Hub on UNIX.

To install the Web Services Hub on UNIX:

1. Log on to the machine.

2. From the WSHub directory on the installation CD, enter ./install to run the installation
program.
3. Enter 1 to install the Web Services Hub. Or, enter 0 to exit the installation.
4. Enter the absolute path for the directory where you want to install the Web Services Hub.
The installation program prompts you for permission to create the directory if it does not
exist.

10 Chapter 2: Installing and Configuring Web Services Hub

 The installation program extracts and installs the files. It then prompts you to view the
readme file.
5. Type Y if you want to read the readme file. Otherwise, type N to proceed.
6. Press Enter and select Exit from the menu.

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

Table 2-1. Web Services Hub Installation Directories

Directory
Description
Name

bin Contains dlls, locale files, and other binaries.

config Contains the following configuration files:

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

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

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

javalib Contains JAR files.

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

logs Contains the log files generated by Web Services Hub.

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

Step 1. Install the Web Services Hub 11

 Table 2-1. Web Services Hub Installation Directories

Directory
Description
Name

ssl Contains the keystore file required for HTTPS support.

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

12 Chapter 2: Installing and Configuring Web Services Hub

Step 2. Configure the Web Services Hub
Before you start theWeb Services Hub, you need to configure the following information:
♦ Environment variables
♦ Configuration file
♦ Logging properties

Configuring Environment Variables

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

Configuring Environment Variables on Windows

After you install the Web Services Hub on Windows, you must set the JAVA_HOME and
PATH environment variables.
♦ JAVA_HOME. Set JAVA_HOME to your Java home directory, which is the root directory
that contains the JDK files.
♦ PATH. Add JAVA_HOME\bin to your system PATH.

Configuring Environment Variables on UNIX

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

UNIX Shell Description

C shell setenv WSH_HOME <Web Services Hub installation path>

Bourne shell export WSH_HOME <Web Services Hub installation path>

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

UNIX Shell Description

C shell setenv JAVA_HOME <Java installation path>

Bourne shell export JAVA_HOME=<Java installation path>

Step 2. Configure the Web Services Hub 13

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

PATH. Add JAVA_HOME\bin to your system PATH. Use the following syntax to add
JAVA_HOME to your PATH:

Operating
UNIX Shell Description
System

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

Linux

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}

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

Operating
UNIX Shell Description
System

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

Linux

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}

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

Operating
UNIX Shell Description
System

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

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

Updating Static Properties

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

14 Chapter 2: Installing and Configuring Web Services Hub

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

To edit WSHConfig.xml:

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

2. Open it with any text editor and configure the following parameters:

Table 2-2. WSHConfig.xml Parameters

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.

3. Save and close the file.

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

To edit WSH.wsdl:

1. Locate WSH.wsdl in the WSH_HOME directory.

2. Change <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 Guidelines

Use the following rules and guidelines when you manually update WSHConfig.xml and
WSH.wsdl:
♦ Service requests fail if you use WSH.wsdl to generate proxy classes, and you do not update
<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.

Step 2. Configure the Web Services Hub 15

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

To configure logging properties:

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

2. Open it with any text editor and update the following parameters:

Table 2-3. WSHLog.properties Parameters

Parameter Description

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

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

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

3. Save and close the file.

Note: When you use debug logging, the Web Services Hub logs verbose messages into the log
file. To avoid overwriting logging messages, increase the maximum file size and the maximum
backup index.
For more information about the Web Services Hub log file, see “Web Services Hub Log File”
on page 43.

Configuring the Web Services Hub for HTTPS

By default, JBoss provides support for HTTP. If you want to run client applications using
HTTPS, you can configure JBoss for HTTPS. The Web Services Hub uses HTTPS to
encrypt messages received from and sent to web service clients. The Web Services Hub also
provides server authentication through HTTPS.
Complete the following steps to configure the Web Services Hub for HTTPS:
1. Configure jboss-service.xml to use HTTPS.
2. Configure WSHConfig.xml to use HTTPS.
3. Replace the dummy keystore file.

Step 1. Edit jboss-service.xml

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

16 Chapter 2: Installing and Configuring Web Services Hub

To edit jboss-service.xml:

1. Find jboss-service.xml. You might find it in a location similar to the following path:
C:\ <WSH_HOME>\jboss-3.2.1\server\default\deploy\jbossweb-tomcat.sar\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:
<!--

<mbean
code="org.jboss.security.plugins.JaasSecurityDomain"

name="Security:service=JaasSecurityDomain,domain=RMI+SSL">

<constructor>
<arg type="java.lang.String" value="RMI+SSL"/>

</constructor>

<attribute

name="KeyStoreURL">WSH_HOME\ssl\wsh.keystore</attribute>

<attribute name="KeyStorePass">changeit</attribute>

</mbean>

-->

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

<Connector className =

" org.apache.catalina.connector.http.HttpConnector"

port = "444" scheme = "https" secure = "true">

<Factory className =
"org.jboss.web.catalina.security.SSLServerSocketFactory"

securityDomainName = "java:/jaas/RMI+SSL"

clientAuth = "false"
protocol = "TLS"/>

</Connector>

-->

4. Comment the following entry in jboss-service.xml:

<!-- A HTTP/1.1 Connector on port 7333 -->

<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="7333" minProcessors="3" maxProcessors="10"

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

Step 2. Configure the Web Services Hub 17

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

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

Step 2. Configure the Web Services Hub to Use HTTPS

Change the URL scheme in WSHConfig.xml to HTTPS. If you use the default installation,
you can find WSHConfig.xml in the following location:
C:\<WSH_HOME>\config\WSHConfig.xml
<!-- WSH URL Scheme (http/https) -->
<URLScheme>http</URLScheme>

Step 3. Replace the Keystore File

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

18 Chapter 2: Installing and Configuring Web Services Hub

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

Starting the Web Services Hub

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

Note: You can disregard the error message that follows startup:
ERROR invalid console appender config detected, console stream is looping

To start the Web Services Hub on Windows:

1. From the Windows Start menu, choose Programs-Informatica Web Services Hub 7.1.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 Installation

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

Step 3. Start the Web Services Hub 19

 Figure 2-1 shows the Web Services Hub console:

Figure 2-1. Web Services Hub Console

The home page displays the following services:

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

To verify the Web Services Hub installation on Windows:

1. From the Windows Start menu, choose Programs-Informatica Web Services Hub 7.1.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 Hub

Use the following procedures to stop the Web Services Hub.

To stop the Web Services Hub on Windows:

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

To stop the Web Services Hub on UNIX:

1. Close the command window.

20 Chapter 2: Installing and Configuring Web Services Hub

Step 4. Run UpdateConfigFile
Complete the following steps after you verify that Web Services Hub starts:
1. Update config.xml. Enter repository information for each repository that you want to
register with the Web Services Hub. You can add multiple repositories to config.xml. Also
enter Web Services Hub parameters for the session expiry and maximum log buffer size.
2. Run UpdateConfigFile. When you run UpdateConfigFile, it reads config.xml and updates
WSHConfig.xml with the values. If you add or update a repository, it encrypts the
repository password.
UpdateConfigFile and config.xml are in the Web Services Hub \configFileLoader directory.

To update config.xml:

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

2. Open it with any text editor and update the following parameters:

Table 2-4. config.xml Parameters

Parameter Description

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

ServerHostName Name of the machine hosting the Repository Server.

ServerPortNumber Repository Server port number.

Username Repository user name.

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

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

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

3. Save and close the file.

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

To run UpdateConfigFile:

1. Verify that the Web Services Hub is running.

2. From a command line, go to the \configFileLoader directory.
3. Run UpdateConfigFile to update WSHConfig.xml.
On Windows, use the following syntax to update WSHConfig.xml:
UpdateConfigFile [-s | -ns] <WSH Hostname> <WSH Port number> [-update |
-delete] [config.xml | Repository Name]

On UNIX, use the following syntax to update WSHConfig.xml:

Step 4. Run UpdateConfigFile 21

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

Note: Values in the format [x | y] represent the options you can use for the command
parameter.
Table 2-5 lists UpdateConfigFile options:

Table 2-5. UpdateConfigFile Options

Required/
Option Description
Optional

-s | -ns Required Indicates secure or nonsecure mode of communication.

Secure mode uses HTTPS, and nonsecure mode uses HTTP.
Enter -ns for nonsecure mode. Enter -s for secure mode.

WSH Hostname Required The name of the machine hosting the Web Services Hub.

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

-update | -delete Required Enter -update to update the WSHConfig.xml file.

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

config.xml | Repository Required If you update parameters in WSHConfig.xml, enter config.xml

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

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.

22 Chapter 2: Installing and Configuring Web Services Hub

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

To register the Web Services Hub:

1. In the Workflow Manager, connect to the repository.

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

3. Click New to register a new hub.

The Web Services Hub Editor dialog box appears.

Figure 2-2. Web Services Hub Editor

Step 5. Register the Web Services Hub 23

 4. Configure the properties as described in Table 2-6:

Table 2-6. Web Services Hub Properties

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.

5. Click OK.

24 Chapter 2: Installing and Configuring Web Services Hub

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

Editing the Port Number in jboss-service.xml

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

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

<Connector className =

" org.apache.catalina.connector.http.HttpConnector"

port = "7333" scheme = "https" secure = "true">

<Factory className =
"org.jboss.web.catalina.security.SSLServerSocketFactory"

securityDomainName = "java:/jaas/RMI+SSL"

clientAuth = "false"
protocol = "TLS"/>

</Connector>

-->

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

Changing the Web Services Hub Port Number 25

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

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

</wsdl:port>

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

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

</wsdl:port>

Editing the Port Number in WSHConfig.xml

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

<HubPortNumber>7333</HubPortNumber>

26 Chapter 2: Installing and Configuring Web Services Hub

Uninstalling Web Services Hub
You can use one of the following methods to uninstall the Web Services Hub:
♦ Run setup.exe on the PowerCenter installation CD. The Informatica Web Services Hub
Setup detects existing installed components and prompts you to remove them.
♦ Use the Add/Remove Programs dialog box. In the Windows Control Panel, choose Add/
Remove Programs, and then choose Informatica Web Services Hub 7.1.1. The Informatica
Web Services Hub Setup detects existing installed components and prompts you to remove
them. You can access the Add/Remove Programs dialog box only if you have system
administrative privileges.
Note: The uninstall program does not remove path and environment settings that you
configured for the Web Services Hub.

Uninstalling Web Services Hub 27

28 Chapter 2: Installing and Configuring Web Services Hub
 Chapter 3

Understanding Web Services

Provider
This chapter includes the following topics:
♦ Overview, 30
♦ Web Services Provider Architecture, 32

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

Web Services Hub

The Web Services Hub is a PowerCenter Service gateway for external clients. It processes
SOAP requests from web service clients that want to access PowerCenter web services. It
receives requests from web service clients and passes them to the PowerCenter Server or the
Repository Server. The PowerCenter Server or the Repository Server process the requests and
send a response to the web service client through the Web Services Hub. The content of the
response depends on the type of service.
The Web Services Hub hosts the following web services:
♦ Batch Web Services. Run and monitor workflows and administer the PowerCenter Server.
♦ Metadata Web Services. Log in to the repository and browse metadata.
♦ Real-time Web Services. Create service workflows that allow you to read and write
messages to a web service client through the Web Services Hub.
For more information about the Web Services Hub, see “Understanding the Web Services
Hub” on page 35.

Batch Web Services

Batch Web Services is a web-enabled version of the PowerCenter Server and the Workflow
Monitor. Use Batch Web Services to perform some Load Manager capabilities, such as
running and monitoring PowerCenter workflows and administering the PowerCenter Server.
Write web service client applications using the functions available with Batch Web Services.
Batch Web Services provides the following types of functions:
♦ PowerCenter Server functions. Perform PowerCenter Server functions, such as connecting
to the PowerCenter Server or getting server properties.
♦ Workflow functions. Perform workflow functions, such as starting, stopping, or
scheduling workflows.
♦ Task functions. Perform task functions, such as starting or stopping a task.
♦ Monitoring and reporting functions. Perform monitoring and reporting functions, such
as monitoring workflows and session performance.
♦ Log functions. Perform log functions, such as getting workflow or session logs.
For more information about Batch Web Services functions, see “Using Batch Web Services
Functions” on page 55.

30 Chapter 3: Understanding Web Services Provider

Metadata Web Services
Metadata Web Services provides the functions that retrieve metadata from PowerCenter
repositories. Write web service client applications using the functions available with Metadata
Web Services. Metadata Web Services provides the following types of functions:
♦ Authentication functions. Perform authentication functions to log in and log out of the
repository.
♦ Browsing functions. Perform browsing functions to get information necessary to run
workflows, such as retrieving repositories, folders, and workflows.
For more information about Metadata Web Services functions, see “Using Metadata Web
Services Functions” on page 49.

Real-time Web Services

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

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

Figure 3-1. Web Services Provider Architecture

Web Service Web Services Hub

Client
Service Workflow
Security Gateway

Real-time Web Services PowerCenter

Server
Workflow
Web Service Batch Web Services
Client Metadata Web Services

Application Server

Repository Server

Repository
Real-time Web Services

Batch Web Services

Metadata Web Services

Repository Server Communication

The Web Services Hub processes service requests in similar ways for the Real-time Web
Services, Batch Web Services, and Metadata Web Services. The following process describes the
architecture of Web Services Provider:
1. A web service client sends a SOAP message to the Web Services Hub to run a service.
2. The Web Services Hub authenticates the web service client based on repository user name
and password.
3. If the service request is for a real-time service, the Web Services Hub generates a message
ID and sends the SOAP request to the PowerCenter Server.
If the service request is for a batch service, the Web Services Hub sends the request to the
PowerCenter Server to process. The request may be to run or monitor a workflow, start or
stop the server, or get log information.
If the service request is for a metadata service, the Web Services Hub sends the request to
the Repository Server to process. The request may be to log in or log out of the
repository.

32 Chapter 3: Understanding Web Services Provider

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

Web Services Provider Architecture 33

34 Chapter 3: Understanding Web Services Provider
 Chapter 4

Understanding the Web Services

Hub
This chapter includes the following topics:
♦ Overview, 36
♦ Using the Web Services Hub Console, 37
♦ Web Services Hub Security, 41
♦ Web Services Hub Log File, 43
♦ SOAP Fault Handling, 45
♦ Session Maintenance, 47

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

36 Chapter 4: Understanding the Web Services Hub

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

Figure 4-1. Web Services Hub Console

Batch and Metadata Web Services

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

<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"/>

Using the Web Services Hub Console 37

 Real-time Services
You can view service information published by the Web Services Hub. You view information
such as service and workflow name, service type, and protected status.
Before you can build a client application to run a service, you need the following information
from the Web Services Hub:
♦ Service name. Identify the service you want to run.
♦ WSDL and referenced schemas. Download the WSDL and referenced schemas associated
with the service. You can view the generated WSDL, but you cannot view the referenced
schema.
♦ Protected status. If the service is protected, you must send a login request to the Web
Services Hub.
Click the Realtime Web Services link to view service information. You can view valid and
invalid services.
Figure 4-2 shows the Transformation Services page:

Figure 4-2. Transformation Services Page

38 Chapter 4: Understanding the Web Services Hub

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

Table 4-1. Transformation Services Page

Column Description

Service Name Service name defined in the service workflow.

Repository Name Repository containing the service.

Folder Name Folder containing the service.

Workflow Name Service workflow associated with the service.

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

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

Figure 4-3. Transformation Service Description Page

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

Table 4-2. Transformation Service Description Page

Property Description

Service Name Service name defined in the service workflow.

Repository Name Repository containing the service.

Folder Name Folder containing the service.

Workflow Name Service workflow associated with the service.

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

Using the Web Services Hub Console 39

 Table 4-2. Transformation Service Description Page

Property Description

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

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

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

40 Chapter 4: Understanding the Web Services Hub

Web Services Hub Security
The Web Services Hub has the following levels of security:
♦ Encryption. The Web Services Hub encrypts the repository login information in the
configuration file used to connect to the repository. It also encrypts the repository
password for web service clients to use to request services.
♦ Authentication. The Web Services Hub authenticates requests from web service clients
based on the user name and password. A web service client logs in to the repository
through a SOAP request sent to the Web Services Hub. This request must contain a
repository name, repository user name, and password. The Web Services Hub
authenticates the request based on the user name and password.
♦ Authorization. A web service client with repository access must have execute permission
on a folder to run a service. For real-time services, a web service client with execute
permission on a folder can run a service in that folder based on service configuration. For
example, if the service is not runnable, a web service client cannot start the service, but it
can invoke the service if the service workflow is running. For more information about
access to services, see “Configuring the Service” on page 101.
Note: If a real-time service is not protected, the Web Services Hub does not perform
authentication or authorization for service requests.

Encrypting Repository Information

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

Encrypting the Configuration File

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

Encrypting Log in Requests

Before a web service client can request to run a web service it must log in to the Web Services
Hub. The Web Services Hub uses the following process to provide a web service client with
encrypted credentials to run services.
1. A web service client sends a login request to the Web Services Hub. This request contains
a repository name, user name, and password.
2. The Web Services Hub authenticates the user and sends a login response containing
credentials that the web service client can use for subsequent requests.

Web Services Hub Security 41

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

42 Chapter 4: Understanding the Web Services Hub

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

Configuring the Log File

You configure log information in the file, WSHLog.properties. You can configure the size of
the log and the level of logging.
By default, the size of wsh.log is 100 KB. If the log size exceeds the maximum configured size,
the Web Services Hub appends a ‘1’ to the file name and creates a new file. When the log file
reaches that size, the Web Services Hub renames the file wsh.log.1 and creates a new file
named wsh.log to continue logging messages. By default, the Web Services Hub can create up
to 10 files.
You can configure logging levels for the Web Services Hub:
♦ Fatal. Indicates the Web Services Hub installation is missing some files. Fatal messages
have the highest severity level.
♦ Error. Indicates the Web Services Hub failed to perform an operation or respond to a
request.
♦ Warning. Indicates the Web Services Hub is performing an operation that may cause an
error. This can cause repository inconsistencies.
♦ Information. Indicates the Web Services Hub is performing an operation that does not
indicate errors or problems.
♦ Debug. Indicates Web Services Hub operations at the thread level. Debug messages
generally record the success or failure of individual internal operations.
Note: When you use debug logging, the Web Services Hub logs verbose messages into the log
file. To avoid overwriting logging messages, increase the maximum file size and the maximum
backup index.
For more information about logging levels, see “Configuring Logging Properties” on page 16.

Viewing the Log File

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

Web Services Hub Log File 43

 Note: The Web Services Hub also writes messages in the fault element of a SOAP response
when it cannot process the request. For more information about fault handling, see “SOAP
Fault Handling” on page 45.

44 Chapter 4: Understanding the Web Services Hub

SOAP Fault Handling
If the Web Services Hub cannot process a request, it sends a response to the web service client
that contains error information indicating the cause of the error. The message target is based
on the task the Web Services Hub was performing when it encountered the error:
♦ If the Web Services Hub cannot process a message in a service workflow, it writes messages
to fault targets.
♦ If the Web Services Hub cannot process the header element of a SOAP request message, it
returns error information related to the header entries of the SOAP request message in a
child element of the SOAP response header element.
♦ If the Web Services Hub encounters any error with the header element of a SOAP request,
it does not process the body element. The SOAP response to the request contains the
header fault element in the SOAP header and a SOAP fault element without the detail
element.
♦ If the Web Services Hub cannot process the contents of the body element, the SOAP fault
element in the SOAP response message contains a detail element contain error
information.
Messages contain a message code, comprised of a prefix and code number, and the message
text. For example, the message code “WSH_95005” has the associated message text “Invalid
request parameter. Shutdown mode cannot be null.” The message code is the ErrorCode
element in the detail element of a SOAP fault, and the message text is the faultstring element
of the SOAP fault.
For a listing of error codes related to the Web Services Hub, see “Web Services Hub Level
Errors” on page 114.

SOAP Fault Header

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

<ErrorCode>
error code

</ErrorCode

<ErrorMessage>
error message

</ErrorMessage>

</ns1:HeaderFault>

SOAP Fault Handling 45

 SOAP Fault Body
The SOAP fault body contains the following sub-elements:
♦ Faultcode. The faultcode determines if the error originates at the web service client or the
PowerCenter Server. If the error originates at the web service client, the message may have
the wrong structure.
♦ Faultstring. The faultstring provides a description of the error. The faultstring value
indicates that the error originated from the PowerCenter Server, Web Services Hub, or
repository.
♦ Detail. The detail element contains error information that includes an error code, and the
extended details provide detailed error information when the faultstring is a Web Services
Hub or repository error.
The Web Services Hub uses the following SOAP fault schema:
<SOAP-ENV: Fault>
<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>

46 Chapter 4: Understanding the Web Services Hub

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

<SessionId>

XYZ
</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
48 Chapter 4: Understanding the Web Services Hub
 Chapter 5

Using Metadata Web Services

Functions
This chapter includes the following topics:
♦ Overview, 50
♦ Authentication Request Functions, 51
♦ Browsing Request Functions, 52

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

50 Chapter 5: Using Metadata Web Services Functions

Authentication Request Functions
Authentication requests validate user names and passwords to access the PowerCenter
repository. For more information on PowerCenter repository security, see the PowerCenter
Repository Guide.

You can use the following authentication requests to access the PowerCenter repositories:
♦ Login
♦ Logout

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

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

Authentication Request Functions 51

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

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

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

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

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

52 Chapter 5: Using Metadata Web Services Functions

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

Browsing Request Functions 53

54 Chapter 5: Using Metadata Web Services Functions
 Chapter 6

Using Batch Web Services

Functions
This chapter includes the following topics:
♦ Overview, 56
♦ PowerCenter Server Functions, 57
♦ Workflow Functions, 59
♦ Task Functions, 61
♦ Monitoring and Reporting Functions, 62
♦ Log Functions, 64

55
Overview
Batch Web Services functions allows you to start and stop existing workflows and tasks. You
can schedule or unschedule existing workflows and tasks. You can get session statistics and
performance data. You can retrieve workflow and session logs. And you can perform
administrative operations, such as stopping the PowerCenter Servers.
The complete set of Batch Web Services request functions consists of the following categories:
♦ PowerCenter Server functions
♦ Workflow functions
♦ Task functions
♦ Monitoring and Reporting functions
♦ Log functions
Note: Log segments obtained by Batch Web Services function calls are either in PowerCenter
Server code page or in UTF-8.

56 Chapter 6: Using Batch Web Services Functions

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

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

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

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

GetDIServerConnectionState
You can use this function to get the state of connection to the PowerCenter Server. This
function returns the following values of the connection state:
♦ ABORTED
♦ CONNECTED
♦ CONNECTING
♦ DISCONNECTED
♦ DISCONNECTING
♦ LOST

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

PowerCenter Server Functions 57

 You can stop the PowerCenter Server in one of the following modes:
♦ COMPLETE. The server waits for all the running workflows to complete before shutting
down
♦ STOP. The server stops all the running workflows, and then it shuts down.
♦ ABORT. The server aborts all running workflows before shutting down.
Note: You can optionally specify the reason for the shutdown.

GetDIServerProperties
You can use this function to get the properties of the PowerCenter Server.
The PowerCenter Server properties include the following information:
♦ 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

58 Chapter 6: Using Batch Web Services Functions

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

StartWorkflow
You can use this function to start the entire workflow, or you can start a workflow from a task.
When you start a workflow from a task, the PowerCenter Server runs the workflow from the
selected task to the end of the workflow. When you want to start a workflow from a task, you
need to specify the task instance path.
The task instance path uniquely identifies a task instance inside a workflow. A task within a
workflow is identified by its task name alone. A task within a worklet is identified by the
form, WorkletName.TaskName.
For instance, if worklet ‘A’ is a worklet in a workflow. Worklet ‘A’ contains another worklet,
‘B,’ and task ‘C’ is a task within worklet ‘B,’ then the task instance path for task ‘C’ is
(A.B.C).

StopWorkflow
You can use this function to stop a running workflow. When you stop a workflow, the
PowerCenter Server tries to stop all the tasks that are currently running in the workflow. If the
workflow contains a worklet, the PowerCenter Server also tries to stop all the tasks that are
currently running in the worklet. In addition to stopping a workflow, you can abort a running
workflow by specifying an “isAbort boolean as true.” Normally, you abort workflows only if
the PowerCenter Server fails to stop the workflow.

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

UnscheduleWorkflow
You can use this function to unschedule a workflow.

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

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

60 Chapter 6: Using Batch Web Services Functions

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

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

StopTask
You can use this function to stop a task running on a PowerCenter Server. You can stop or
abort a task, workflow, or worklet at any time. You can also abort a running task by specifying
an “isAbort boolean as true.” Normally, you abort tasks only if the PowerCenter Server fails to
stop the task.
The task instance path uniquely identifies a task instance inside a workflow. A task within a
workflow is identified by its task name alone. A task within a worklet is identified by the
form, WorkletName.TaskName.
For instance, if worklet ‘A’ is a worklet in a workflow. Worklet ‘A’ contains another worklet,
‘B,’ and task ‘C’ is a task within worklet ‘B,’ then the task instance path for task ‘C’ is
(A.B.C).

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

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

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

MonitorDIServer
You can use this function to retrieve the status of the PowerCenter Server, details of active
and/or scheduled workflows, details of the tasks within the workflows, details of links within
the workflows, and the timestamp for this information.
You can call this function in three modes:
♦ RUNNING. Returns status details for active workflows. Active workflows include
running, suspended, and suspending workflows.
♦ SCHEDULED. Returns status details for scheduled workflows.
♦ ALL. Returns information for all scheduled and active workflows.

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

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

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

62 Chapter 6: Using Batch Web Services Functions

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

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

Monitoring and Reporting Functions 63

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

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

To get workflow logs using the web services:

1. Call StartWorkflowLogFetch once. This returns a LogHandle.

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

GetSessionLog
The PowerCenter Server creates a session log file for each session it runs. It writes information
in the session log, such as initialization of processes, session validation, creation of SQL
commands for reader and writer threads, errors encountered, and load summary. The amount
of detail in the session log depends on the tracing level that you set.

64 Chapter 6: Using Batch Web Services Functions

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

To get session logs through the web services:

1. Call StartSessionLogFetch once. This returns a LogHandle.

2. Call GetNextLogSegment with this LogHandle. This returns a LogSegment object.
3. If EndOfLog field of LogSegment object (obtained in step 2) is false, go to step 2, else
exit.
StartSessionLogFetch function requires folder name, workflow name, and task instance path.
It returns a LogHandle.
The GetNextLogSegment function requires a LogHandle (obtained in the
StartSessionLogFetch) and a timeout value. This timeout value specifies the maximum time
for which the client application can be blocked if no log segments for the session are available
at the Web Services Hub. The Web Services Hub receives the log segments from the
PowerCenter Server. After the timeout value expires, control is returned to the client
application.

Max Log Buffer Size

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

Log Functions 65
66 Chapter 6: Using Batch Web Services Functions
 Chapter 7

Writing Client Applications

This chapter includes the following topics:

♦ Overview, 68
♦ Writing a Simple Client Application, 69
♦ Writing a Client Application in Java Using Axis, 73
♦ Writing a Client Application in C# Using .Net, 77

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

68 Chapter 7: Writing Client Applications

Writing a Simple Client Application
This section discusses the steps to write a Web Services Hub client application using any web
services toolkit.
Later sections of this chapter discuss the steps to develop client applications using the Axis
and .Net Web Services Toolkits.
Developing a client application for web services involves the following processes:
♦ Generate client proxy classes
♦ Initialization
♦ Session maintenance
♦ Metadata and Batch function calls
♦ Clean up
Note: These steps may vary according to the web services toolkit you use. Some toolkits, such
as .Net, handle the session maintenance step automatically by generating the appropriate
information from the WSDL files. As a result, the .Net client applications do not need to
perform session maintenance.

Generating Client Proxy Classes

To use the services offered by Web Services Hub, you need to generate a client proxy with the
WSDL file provided and a web services toolkit.
Use the following steps to generate client proxies:
1. Select the web services toolkit for the platform and language you want to develop in.
2. Change the Web Services Hub host name and port number in the endpoint URL for
Metadata Web Services and Batch Web Services in the WSH.wsdl. You can change these
by editing the address element, which is available in the definitions\service\port hierarchy
in the WSDL file.
3. Generate the client-side proxy classes from the WSH.wsdl using the web service toolkit.
Refer to the web services toolkit documentation for details on the proxy classes
generation. Different toolkits generate the client-side proxy classes in different manners.
4. WSH.wsdl contains two port type definitions, one each for Metadata and Batch Web
Services APIs. The generated client-side proxy classes should have two classes, one each
for Metadata and Batch Web Services APIs apart from other classes.

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

Writing a Simple Client Application 69

 To perform Initialization:

1. Instantiate the proxy class for the Metadata APIs and name this object, for example,
MWSProxy. Use this object to call Metadata Web Services functions.
2. Instantiate the proxy class for the Data Integration APIs and name this object, for
example, DIWSProxy. Use this object to call Batch Web Services functions.
3. Call the Login function of Metadata Web Services using the MWSProxy object.
This function requires three input parameters, repository name, user name, and password
and the return parameter is a LoginHandle string. This function call associates the
MWSProxy object with the repository name and user name pair. All subsequent requests
made to Metadata Web Services using the MWSProxy object use this repository name
and user name.
4. Call the InitializeDIServerConnection function using the DIWSProxy object.
This function requires two input parameters, LoginHandle and the PowerCenter Server
name. This function call associates the DIWSProxy object with the repository name, user
name, and PowerCenter Server name. All subsequent requests made to Batch Web
Services using the DIWSProxy object use this repository name, user name, and
PowerCenter Server name.

Session Maintenance
The Web Services Hub requires session maintenance to cache resources. The SOAP header in
the SOAP message carries the session information facilitating session maintenance.

To set up and perform session maintenance:

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.

70 Chapter 7: Writing Client Applications

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

Cleaning up Server Resources

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

To perform clean up:

1. Call the Batch Web Services DeinitializeDIServerConnection function using the

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

Error Handling
SOAP fault elements in the SOAP response report errors that occur while using Web Services
Provider.
While calling any of the Metadata Web Services or Batch Web Services functions, the client
application should implement the appropriate error handling scheme to retrieve the SOAP
fault. This scheme varies according to the toolkit.
A web services toolkit provides an error, exception handling scheme to obtain the faultcode
and faultstring field of a fault element. However, you might need an XML parser to parse the
detail element field to obtain the error code and extended details.

Writing a Simple Client Application 71

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

Invalidating Proxy Objects

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

72 Chapter 7: Writing Client Applications

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

Generating Client Proxy Classes in Axis

You can generate Client Proxy Classes in Java using the Axis Web Services Toolkit.
Generate client proxy classes in Java in the following manner:
♦ Change the Web Services Hub host name and port number in the endpoint URL for
Metadata Web Services and Batch Web Services in the WSH.wsdl file. You can change
these by editing the address element, which is available in the definitions\service\port
hierarchy in the WSDL file.
♦ Generate the Client Proxy Classes from the WSH.wsdl using the following command:
java org.apache.axis.wsdl.WSDL2Java --NStoPkg
http://www.informatica.com/PowerCenter=ProxyClasses -W WSH.wsdl.

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

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

To perform initialization:

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

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

Otherwise, get the MWSProxy object as follows:

MWSProxy=WSH.getMetadata(new java.net.URL(MWS_URL));

Writing a Client Application in Java Using Axis 73

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

Otherwise, get the DIWSProxy object as follows:

DIWSProxy=WSH. getDataIntegration (new java.net.URL(DIWS_URL));

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

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

loginReq.setRepositoryName(REPO_NAME);

loginReq.setUserName(USER_NAME);

loginReq.setPassword(PASSWORD);

String loginHandle = MWSProxy.login(loginReq);

where REPO_NAME is a string containing a repository name, USER_NAME is a string

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

initializeReq.setDIServerName(DI_SERVER_NAME);
initializeReq.setLoginHandle(loginHandle);

DIWSProxy.initializeDIServerConnection(initializeReq);

Where DI_SERVER_NAME is a string containing the PowerCenter Server name.

74 Chapter 7: Writing Client Applications

Session Maintenance in Axis
The Web Services Hub requires session maintenance to cache resources. The SOAP header in
the SOAP Message carries the session information facilitating session maintenance.

To perform session maintenance:

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

=((org.apache.axis.client.Stub)MWSProxy).getResponseHeader(“http://
www.informatica.com/PowerCenter”,“Context”);

((org.apache.axis.client.Stub)MWSProxy).setHeader(MWSHeader);

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

((org.apache.axis.client.Stub)DIWSProxy).setHeader(MWSHeader);

Making Function Calls in Axis

You are now ready to call Metadata Web Services and Batch Web Services functions using the
MWSProxy and DIWSProxy objects respectively.
For example, you can call the GetAllDIServers function to get a PowerCenter Server:
DIServerInfoArray servers = MWSProxy.getAllDIServers(new VoidRequest());

System.out.println(“WSH Supports following DI Servers “);

for(int i=0; i < servers.getDIServerInfo().length ; i++) {

System.out.println(servers.getDIServerInfo(i).getName());

You can call the PingDIServer function to ping a PowerCenter Server:

PingDIServerRequest pingReq = new PingDIServerRequest();

pingReq.setDIServerName(DI_SERVER_NAME);

pingReq.setTimeOut(30);

Writing a Client Application in Java Using Axis 75

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

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

Cleaning Up in Axis
Cleanup releases the Web Services Hub resources acquired by client applications and performs
cleanup operations.

To perform clean up:

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

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

Error Handling in Axis

You can implement client application error handling in Axis by placing the code in a try block
and catching the FaultDetails object. The FaultDetails class is generated as part of the client
proxies. Code in a try block for catching the FaultDetails object as follows:
try {

// Code for steps explained above.

catch(FaultDetails fault) {

// Display fault code

System.out.println(“fault code : “ + fault.getFaultCode());

// Display fault string

System.out.println(“fault string : “ + fault.getFaultString());

// Display error code

System.out.println(“error code is : “ + fault.getErrorCode());

// Display extended details

System.out.println(“extended detail is : “ +
fault.getExtendedDetails());

76 Chapter 7: Writing Client Applications

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

Generating Client Proxy Classes in .Net

You can create client proxy classes for the Web Services Hub in C# using Microsoft’s .Net
Web Services Toolkit.
You generate client proxy classes in C# in the following manner:
♦ Change the Web Services Hub host name and port number in the endpoint URL for
Metadata Web Services and Batch Web Services in the WSH.wsdl file. You can change
these by editing the address element, which is available in the definitions\service\port
hierarchy in the WSDL file.
♦ Generate the Client Proxy Classes from the WSH.wsdl using the following command:
wsdl WSH.wsdl

This generates a WebServicesHub.cs file that contains two proxy classes,

MetadataServiceSoapBinding and DataIntegrationServiceSoapBinding along with data
container classes. The two proxy classes contain Metadata Web Services and Batch Web
Services functions.
Note: You can use the .Net client proxy classes shipped with Web Services Hub distribution
in samples directory.

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

To perform initialization:

1. Instantiate a MetadataServiceSoapBinding class object (MWSProxy). Use the MWSProxy

object to call Metadata Web Services functions as follows:
MWSProxy= new MetadataServiceSoapBinding();

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

Where MWS_URL is a string containing Metadata Service endpoint URL.

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

Writing a Client Application in C# Using .Net 77

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

Where DIWS_URL is a string containing the Batch Web Services endpoint URL.
3. Call the Login function of Metadata Web Services using the MWSProxy object. This
function takes three input parameters, repository name, user name, and password,
wrapped in an object LoginRequest and returns a LoginHandle string. This function call
associates the MWSProxy object with this repository name and user name pair. All
subsequent requests made to Metadata Web Services using the MWSProxy object use this
repository name and user name. Use the MWSProxy object to call the Login function as
follows:
LoginRequest loginReq = new LoginRequest();
loginReq.RepositoryName = REPO_NAME;

loginReq.UserName = USER_NAME;

loginReq.Password = PASSWORD;

String loginHandle = MWSProxy.Login(loginReq);

where REPO_NAME is a string containing the repository name, USER_NAME is a

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

initializeReq.DIServerName=DI_SERVER_NAME;

initializeReq.LoginHandle= loginHandle;

DIWSProxy.InitializeDIServerConnection(initializeReq);

where DI_SERVER_NAME is a string containing the PowerCenter Server name.

Session Maintenance in .Net

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

78 Chapter 7: Writing Client Applications

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

for(int i=0;i< servers.Length;i++) {

Console.WriteLine(server[i].Name);
}

Similarly, you can call the PingDIServer function of the Batch Web Services as follows:
PingDIServerRequest pingReq = new PingDIServerRequest();

pingReq.DIServerName=DI_SERVER_NAME;

pingReq.TimeOut= 30;

EPingState pingState= DIWSProxy.PingDIServer(pingReq);

Console.WriteLine(“ping result using state” + pingState);

Where DI_SERVER_NAME is a string containing the PowerCenter Server name.

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

To perform clean up:

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

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

Error Handling in .Net

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

//Code for steps explained above.

}

Writing a Client Application in C# Using .Net 79

 catch(SoapException fault) {
// Display fault code

Console.WriteLine(“fault code is : “ + fault.Code);

// Display fault string

Console.WriteLine(“fault string is : “ + fault.Message);

// Parsing detail element

XmlNode detail = fault.Detail;

XmlElement WSHFaultDetails = detail[“WSHFaultDetails”, “http://
www.informatica.com/PowerCenter”];

XmlElement ErrorCode= WSHFaultDetails [“ErrorCode”];

XmlElement ExtendedDetails= WSHFaultDetails [“ExtendedDetails”];

// Display error code

Console.WriteLine (“error code is : “ + ErrorCode.InnerText);

// Display extended details

Console.WriteLine (“extended detail is : “ +

ExtendedDetails.InnerText);

80 Chapter 7: Writing Client Applications

 Chapter 8

Working with Service

Mappings
This chapter includes the following topics:
♦ Overview, 82
♦ Importing Web Service Source and Target Definitions, 83
♦ Viewing and Editing Web Service Definitions, 89
♦ Working with Service Mappings, 95

81
Overview
Before you can define a service in the Workflow Manager, you use the Designer to perform
the following tasks:
♦ Import definitions. Import operations from a WSDL file to create web service source and
target definitions. When you import a source, the Designer imports the input message.
When you import a target, the Designer imports output and fault messages. The Designer
creates multiple groups in a definition based on the XML hierarchy of the file.
♦ View and edit definitions. Most properties of a web service definition are read-only. You
can edit properties such as description, metadata extensions, and precision for String and
Binary datatypes. You can edit the definition in the Designer workspace. You can view the
groups and relationships in the XML Editor.
♦ Create mappings. You can create a service mapping to receive a message from a web service
client, transform the data, and send the response back to the web service client or write it
to any target PowerCenter supports. Based on the source and target definitions,
PowerCenter can receive and send attachments as part of the SOAP request.
You can also create a mapping using flat file or XML source and target and use it in a
service. This allows you receive message data through a SOAP call instead of reading it
from a file.

82 Chapter 8: Working with Service Mappings

Importing Web Service Source and Target Definitions
Web service source and target definitions represent metadata for SOAP request and response
messages. You create web service source and target definitions by importing a WSDL file. The
WSDL file contains information about a web service operation. The Designer creates a source
or target definition based on the operation you choose in the WSDL file you import:
♦ When you import a WSDL file in the Source Analyzer, the Designer imports the input
message of an operation. This represents the metadata for a web service SOAP request.
♦ When you import a WSDL file in the Warehouse Designer, the Designer imports metadata
for a web service soap response. This represents the metadata for a web service SOAP
response.
If the Designer detects an attachment, it creates an attachment group in definition.
Note: You can import definitions from a WSDL file with document/literal encoding.

Importing Web Service Source Definitions

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

Figure 8-1. Web Service Source Definition

Root group contains message ID.

Body group has foreign key pointing to root group.

Detail group has foreign key pointing to body group.

Header group has foreign key pointing to root group.

Importing Web Service Source and Target Definitions 83

 Table 8-1 describes the groups in a web service definition:

Table 8-1. Web Services Definition Groups

Group Name Description

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

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

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

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

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

When you import a web service source definition, the Designer creates ports in the message
header that are not part of the XML hierarchy. When you run a service workflow, the Web
Services Hub uses this information to identify the web service client and generate a message
ID.
Table 8-2 describes the message header ports in a web service definition:

Table 8-2. Message Header Ports

Port Name Description

PK_Message Generated primary key for the root group.

MessageID The Web Services Hub generates the message ID when it receives a request. It uses this ID to
correlate the incoming request with the outgoing response.

ClientID User ID of the web service client.

ClientIP TCP/IP address of the web service client.

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

Importing Web Service Target Definitions

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

84 Chapter 8: Working with Service Mappings

 Figure 8-2 shows a sample output message and fault message:

Figure 8-2. Web Service Target Definitions

Output Message
Fault Message

Note: When the Designer imports a web service target definition, it names the definition based
on the operation and the target type, such as output or target. If you rename the definition,
you can verify the target type on the Metadata Extensions tab.
For information about importing web service target definitions, see “Steps for Importing Web
Service Sources and Targets” on page 85.

Steps for Importing Web Service Sources and Targets

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

To import a web service definition:

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

Importing Web Service Source and Target Definitions 85

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

Select a URL.

Configure default precision. Choose to display import errors.

Choose to import from a local file or a URL.

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

86 Chapter 8: Working with Service Mappings

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

Table 8-3. Advanced Options

Option Description

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

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

3. Choose to import from a local file or a URL.

4. If you choose to import from a URL, select a URL from the Address list and click Open.
If you choose to import from a local file, select a file and click Open.

Importing Web Service Source and Target Definitions 87

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

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

88 Chapter 8: Working with Service Mappings

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

Viewing and Editing Definitions in the Designer

Web service source definitions and target definitions contain the following tabs:
♦ Table. On the Table tab, you can provide the owner name and description, and you can
change the name of the definition. You cannot change the table type.
♦ Columns. On the Columns tab, you can edit the precision for String datatypes. You can
also add business names and column descriptions.
♦ Attributes. On the Attributes tab, you can view attribute values for each column in a
source or target definition.
♦ Metadata Extensions. On the Metadata Extensions tab, you can view the Web Services
Domain metadata extensions. You can also add metadata extensions in the User Defined
Metadata Domain.

Columns Tab
The Columns tab displays column information, such as port name, datatype, precision, and
scale. You can edit precision for String and Binary datatypes, and you can add business names
and column descriptions.
By default, the Designer imports web service definition String datatypes with a precision of
1,000. You can change the default precision for String datatypes when you import the source
or target. When you change the default precision, the Designer uses the updated value the
next time you import a definition. You can also modify the precision of individual columns
after you import a definition.
Note: The Mapping Designer invalidates mappings that use source and target web service
definition with a total column length greater than 500 MB.
For more information about modifying the precision when you import a definition, see “Steps
for Importing Web Service Sources and Targets” on page 85.

Viewing and Editing Web Service Definitions 89

 Figure 8-3 shows the Columns tab for a web service source definition:

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

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

90 Chapter 8: Working with Service Mappings

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

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

MIME Type of Attachment

Metadata Extensions Tab

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

Viewing and Editing Web Service Definitions 91

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

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

Displays message type as

input, output, or fault.

View Definitions in the XML Editor

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

92 Chapter 8: Working with Service Mappings

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

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

To view a web service definition in the XML Editor:

Right-click a definition and choose WSDL Workspace.

Editing Web Service Targets in a Mapping

When you work with web service targets in a mapping, you can configure the load scope on
the Properties tab. Load scope in a web service target definition is similar to the
transformation scope in a transformation. You can configure the following load scope values:
♦ All input. When you configure the load scope to all input, the PowerCenter Server
generates a response after it receives all incoming data. Different groups in the target can
receive data from different transaction generators. The PowerCenter Server ignores
commits when the load scope is all input.

Viewing and Editing Web Service Definitions 93

 ♦ Transaction. When you configure the load scope to transaction, the PowerCenter Server
generates a response when it receives all data in the transaction. All groups in the target
must receive data from the same transaction generator.
For more information about transformation scope, see "Understanding Commit Points" in
the Workflow Administration Guide.

94 Chapter 8: Working with Service Mappings

Working with Service Mappings
You can create service mappings to process web service requests. A service mapping can
contain source or target definitions imported from a Web Services Description Language
(WSDL) file containing a web service operation. It can also contain flat file or XML source or
target definitions.
The mapping you create depends on the type of service that you want to run:
♦ Request-response service. A request-response service receives an incoming request from
the web service client, transforms the data, and sends the response back to the web service
client. A request-response service uses both a web service source and a web service target.
When you create mappings for a request-response service, you must propagate the message
ID from the source to the target. You can create one mapping or multiple mappings to
process a request-response service.
− One mapping. Create one mapping that contains both the web service source and web
service target definitions. This allows you to receive an incoming request, transform the
data, and send the response back in a single session.
− Multiple mappings. Create multiple mappings if you need to stage data before sending a
response back to the web service client. You can create a workflow that contains a session
for each mapping.
♦ One-way service. If you receive updates and notifications from a web service client, but do
not need to send back a response, you can create a one-way mapping. A one-way mapping
uses a web service client for the source. The PowerCenter Server loads data to a target,
often triggered by a real-time event through a web service request. When you create a 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:

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 Can have multiple instances of one target output definition.
web service source definition. Can have multiple target fault definitions.

One-way Must have one instance of one Contains no web service target definition.
web service source definition.

Note: You can also create mappings with flat file or XML source or targets and run them in
service workflows. For more information, see “Running Sessions and Service Workflows” on
page 109.

Working with Service Mappings 95

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

Figure 8-7. Request-Response Mapping

Note: When you create request-response mappings, Informatica recommends that you use
source and target definitions imported from the same WSDL file. If you do not import source
and target definitions from the same WSDL file, you might get unexpected results.

Staged Mappings
If you want to run a request-response session, but you need to stage the data first, you can
create multiple mappings to process the request and response. For example, you receive
message data that you need to process. You must make an asynchronous call to an external
system through IBM MQSeries. You create the following mappings:
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.

96 Chapter 8: Working with Service Mappings

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

Attachment Mappings
Based on the source and target definitions, you can receive and send attachments as part of
the SOAP request. The document type you can attach is based on the MIME content of the
WSDL file. You can attach document types such as XML, JPEG, GIF, or PDF.
For example, you can extract an XML document from an Oracle database and pass it to a web
service client as an attachment to a response message. Or, you might set up a client
application to allow web service clients to send PDF attachments in a request.
Table 8-5 describes the attachment group ports in a web service definition:

Table 8-5. Attachment Group Ports

Port Name Description

FK_Att_Name Generated foreign key pointing to PK_Message in the root group.

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

Att_Index_Name Unique identifier for each attachment in the message.

Att_Type_Name The type of attachment.

Use the following rules and guidelines when you work with attachments:
♦ A request or response can contain zero or more attachments.
♦ If you want to pass attachments through requests or responses, you must connect all ports
in the attachment group.
♦ If a definition in your mapping contains an attachment group, but you do not want to
send or receive attachments, connect none of the ports in the group.
♦ If you receive more than one attachment in a request, you must propagate the index to the
target if you pass the attached request to the response. If you do not pass the attached
request to the response, you do not need to propagate the index to the target.
♦ If you receive messages from other sources, and each message contains the same number of
attachments, you can use a Sequence Generator transformation to generate a unique index
for each attachment you send in a response.

Working with Service Mappings 97

98 Chapter 8: Working with Service Mappings
 Chapter 9

Working With Service

Workflows
This chapter includes the following topics:
♦ Overview, 100
♦ Creating and Configuring a Service, 101
♦ Creating and Configuring a Service Session, 103
♦ Running Sessions and Service Workflows, 109
♦ Troubleshooting, 111

99
Overview
You configure services and service workflows in the Workflow Manager. When you create a
service workflow, you enable it for web services. You configure the service within the
workflow properties. For more information about creating services and service workflows, see
“Creating and Configuring a Service” on page 101.
When you create a session to add to the workflow, you can use a mapping that contains web
service, flat file, or XML sources or targets. If you use a flat file or XML source or target, you
change the reader or writer type. For more information about creating sessions, see “Creating
and Configuring a Service Session” on page 103.
For more information about running sessions, see “Running Sessions and Service Workflows”
on page 109.
Note: Before you can run a service workflow, you must register the Web Services Hub. For
more information, see “Step 5. Register the Web Services Hub” on page 23.

100 Chapter 9: Working With Service Workflows

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

Creating a Service Workflow

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

Figure 9-1. Creating a Service Workflow

Create a service workflow.

Configure service.

Configuring the Service

When you configure a service, you configure a service name, timeout, and accessibility
options.

Creating and Configuring a Service 101

 Figure 9-2 shows the Config Service dialog box:

Figure 9-2. Web Service Configuration

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

Table 9-1. Web Service Properties

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.

102 Chapter 9: Working With Service Workflows

Creating and Configuring a Service Session
When you create a service session, you can use a service mapping or any flat file or XML
mapping.
Configure the following properties when you configure a service session:
♦ Web Services Provider reader. When you configure the reader for a service session, you
configure terminating conditions, such as idle time and message count. For more
information about configuring the reader, see “Configuring the Web Services Provider
Reader” on page 103.
♦ Web Services Provider writer. When you configure the writer for a service session, you
configure caching information that the PowerCenter Server uses to cache target data. For
more information about configuring the writer, see “Configuring the Web Services
Provider Writer” on page 105.
♦ Recovery. When you enable recovery, the PowerCenter Server stores messages in the cache
directory. For more information about message recovery, see “Recovering Messages” on
page 106.
♦ Commit type. Configure real-time sessions for a source-based commit. For more
information about commit behavior, see “Configuring Commit Type” on page 107.
♦ Partitioning. You can configure partitioning properties based on the source and target type
in the mapping. For more information about partitioning, see “Configuring Partitioning”
on page 107.

Configuring the Web Services Provider Reader

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

Creating and Configuring a Service Session 103

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

Figure 9-3. Web Services Provider Reader Properties

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

Table 9-2. Web Services Provider Reader Properties

Property Source Type Description

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

Message Count* Web Service The number of messages the PowerCenter Server reads before it ends
Flat File the session.
XML 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 The amount of time in seconds that the PowerCenter Server reads
Flat File source messages from the Web Services Hub. For example, if you
XML 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.

104 Chapter 9: Working With Service Workflows

 Table 9-2. Web Services Provider Reader Properties

Property Source Type Description

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

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

Treat Empty Content as XML Treats empty strings as null values. By default, empty content is not
Null null.
*The session stops when it meets any of these conditions.

Configuring Real-time Flush Latency

Use flush latency to send response messages to the Web Services Hub after a specified number
of seconds. The PowerCenter Server flushes messages to the Web Services Hub when it
reaches the flush latency period or when the reader buffer is full, whichever comes first. The
PowerCenter Server does not buffer messages longer than the flush latency period.
The Web Services Hub might not send responses to the web service client if you configure
flush latency greater than the service timeout. For more information, see “Running Sessions
and Service Workflows” on page 109.
Consider the following guidelines when you configure flush latency:
♦ The session fails if a pipeline contains a Transaction Control transformation.
♦ The session fails if a pipeline contains any transformation with Generate Transactions
enabled.
♦ The session fails if a pipeline contains any transformation with the transformation scope
set to all input.
♦ The session fails if the load scope is set to all input.
♦ Configure the flush latency greater than the service timeout.
♦ The session fails if a pipeline contains any transformation that has row transformation
scope and receives input from multiple transaction control points.
♦ The PowerCenter Server ignores flush latency when you run a session in debug mode.
♦ If the mapping contains a relational target, configure the Target Load Type to be Normal.

Configuring the Web Services Provider Writer

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

Creating and Configuring a Service Session 105

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

Table 9-3. Web Services Provider Writer Properties

Property Target Type Description

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

Cache Size Web Service The total size in bytes for the memory cache used by writer. Default is
XML 10,000,000 bytes.

Cache Directory Web Service The directory for the target cache files. Default is the $PMCacheDir server
XML variable.

Use the following guidelines when you change the writer type to a Web Services Provider
writer:
♦ When you change the writer type for a flat file target, the PowerCenter Server does not
cache the target messages.
♦ When you change the writer type for a flat file or an XML target, you can use the target as
a web service output message, but not as a fault message.
♦ When you change the writer type for an XML target, you still configure XML writer
properties. For more information about XML writer properties, see the XML User Guide.

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

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

106 Chapter 9: Working With Service Workflows

 Note: The PowerCenter Server ignores the reader time limit, idle time, and message count
when it reads messages from the cache.
For more information about recovery, see the Workflow Administration Guide.

Configuring Commit Type

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

Configuring Source-Based Commit

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

Configuring Target-Based Commit

If you configure a target-based commit, the PowerCenter Server runs the session using 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 Partitioning
When you configure multiple partitions in a session that contains web service source and
target definitions, the PowerCenter Server creates a connection to the Web Services Hub
based on the number of sources, targets, and partitions in the session. For example, if you
configure three partitions in a session that contains one source and one target, the
PowerCenter Server creates six connections to the Web Services Hub, three for each source
and target.
When you run a multi-partitioned session, the Web Services Hub uses a source connection to
pass a request to the PowerCenter Server. The PowerCenter Server uses a target connection to

Creating and Configuring a Service Session 107

 send a response to the Web Services Hub. The Web Services Hub and the PowerCenter Server
use the source and target connections in a round-robin fashion.
When you configure partitioning for a service mapping, you can configure pass-through
partitioning for web service sources and targets. For information about configuring
partitioning for XML sources or targets or flat file sources or targets, see “Pipeline
Partitioning” in the Workflow Administration Guide.

108 Chapter 9: Working With Service Workflows

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

Working with XML and Flat File Sessions

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

Understanding Service Timeout and Flush Latency

When you run a service session, the Web Services Hub must generate the response message in
the timeout period configured in the service properties. When the Web Services Hub reaches
the timeout period, it sends a fault message to the web service client and drops the
connection. If the PowerCenter Server sends a response message to the Web Services Hub
after the timeout period, the Web Services Hub drops the response and writes the following
message to the Web Services Hub log:
WSH_95571 Unable to find invocation for message id <message ID>.
Discarding the response.

The following scenarios describe some session configurations that can result in dropped
response messages:
♦ You configure flush latency greater than the service timeout period.

Running Sessions and Service Workflows 109

 For example, you configure the flush latency to 90 and the service timeout to 60. The Web
Services Hub reaches the timeout period and drops the connection to the web service
client before the PowerCenter Server flushes any response message to the Web Services
Hub.
♦ You disable flush latency and configure terminating conditions to infinite values.
For example, if you disable flush latency, the PowerCenter Server sends a response message
to the Web Services Hub when the session reaches one of the terminating conditions or
when the reader buffer fills. If you configure the terminating conditions to infinite values,
the session runs continuously and never ends. The PowerCenter Server sends response
messages when the buffer fills. If the Web Services Hub reaches the timeout period before
the reader buffer fills, it drops the connection to the web service client and cannot send
response messages received from the PowerCenter Server.
♦ You disable flush latency and use message count as the terminating condition.
For example, you want the session to end after the PowerCenter Server processes 10
messages. You configure message count to 10, and you disable flush latency to flush all the
messages at the end of the session. If the PowerCenter Server does not process all 10
messages in the service timeout period, the Web Services Hub drops the connection to the
web service client and cannot send response messages received from the PowerCenter
Server.
To help ensure that the Web Services Hub does not reach the timeout period, configure flush
latency value less than the service timeout.

110 Chapter 9: Working With Service Workflows

Troubleshooting
I am trying to run the Debugger against a service session, but the session fails, and I get the
following message in the session log:
WSP_34030 Must have workflow context to run this session.

If you want to debug a service session, you must run the Debugger against the service
workflow. You cannot run the Debugger against a service mapping or a reusable session
without the workflow.

When a client application invokes a service, I see a debug message in the Web Services Hub
log similar to the following message:
2004-06-28 14:46:47,400 [Thread-6] DEBUG - WshServlet::logRequestHeaders
vsdebuggercausalitydata :
AwAAAHW5hDm6UwNDh9Cb134tdNUAAAAAAAAAAAAAAAAAAAAAA

AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AA

You cannot debug this message. The Web Services Hub did not generate it. The client
application sends this message in the HTTP header.

I updated the source WSDL file and reimported my source and target definitions. The
workflow is valid, but the service WSDL is not updated.
Changes to a mapping are not dynamically reflected in the Web Services Hub. To generate
WSDL to reflect the mapping changes, you need to edit and save the workflow. When you
save the workflow, the Web Services Hub generates WSDL to run the service.

Troubleshooting 111
112 Chapter 9: Working With Service Workflows
 Appendix A

Web Services Hub Error

Messages
This appendix includes the following topics:
♦ Web Services Hub Level Errors, 114

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

WSH_95000 Web Services Hub ERROR.

Cause: Internal error at the Web Services Hub.
Action: See the Extended Details in the SOAP fault message to determine the exact
problem.
or
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.

116 Appendix A: Web Services Hub Error Messages

Action: Clear the header before calling the InitializeDIServerConnection function.

WSH_95022 Invalid log handle.

Cause: This occurs when you pass an invalid log handle in the GetNextLogSegment
function.
Action: Specify a valid log handle obtained from the StartWorkflowLogFetch or the
StartSessionLogFetch function calls.

WSH_95023 Unable to process request. Login request should not contain a SOAP header.
Cause: This occurs when you pass a SOAP header in the Login function call.
Action: Clear the headers before calling Login function.

WSH_95024 User logged out.

Cause: This occurs when you make any function call after logging out.
Action: Call the Login function again before making any other function calls.

WSH_95025 User session expired.

Cause: This occurs when you make any function calls after your session expires.
Action: Call the Login function again before making any other function calls.

WSH_95026 Unable to deinitialize the connection to PowerCenter Server. Some calls are in
progress.
Cause: This occurs when you try to call the DeinitializeDIServerConnection function
when active calls are in progress.
Action: Wait for active calls to finish and then call the
DeinitializeDIServerConnection function.

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

Web Services Hub Level Errors 117

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

WSH_95029 Folder <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
Action: Contact Informatica Technical Support.

118 Appendix A: Web Services Hub Error Messages

WSH_95035 Invalid SOAP request.
Cause: This occurs when you pass a null SOAP message in the request.
Action: Send the SOAP request as the Web Services Hub WSDL file dictates.

WSH_95036 User logged out or session expired.

Cause: This occurs when you try to make a call after logout or the session expires.
Action: Call the Login function again before making any further calls.

WSH_95040 Unable to log out. Some calls are in progress.

Cause: This occurs when you try to call logout while active calls are in progress.
Action: Wait for the active calls to finish, and then call Logout.

WSH_95041 Depth <depth> is not valid. Depth should be a positive integer value.
Cause: This occurs when you give an invalid depth in the GetAllTaskInstances
function call.
Action: Specify a depth value greater than zero.

WSH_95042 Invalid request parameter. LoginRequest object cannot be null.

Cause: This occurs when you pass a null LoginRequest object in the Login function
call.
Action: Specify a valid LoginRequest object.

WSH_95043 Invalid request parameter. FolderInfo object cannot be null.

Cause: This occurs when you pass a null value for the FolderInfo object in the
GetAllWorkflows function call.
Action: Specify a valid FolderInfo object.

WSH_95044 Invalid request parameter. GetAllTaskInstancesRequest object cannot be null.

Cause: This occurs when you pass a null GetAllTaskInstancesRequest object in the
function call.
Action: Specify a valid GetAllTaskInstancesRequest object.

WSH_95045 Unable to load config file: <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.

Web Services Hub Level Errors 119

 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.

120 Appendix A: Web Services Hub Error Messages

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.
Action: Contact Informatica Technical Support.

WSH_95102 Connection to the PowerCenter Server is lost.

Cause: This error may occur when you call a Batch Web Services function after calling
the InitializeDIServerConnection function. This may happen if the
PowerCenter Server goes down or there is a network problem.

Web Services Hub Level Errors 121

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

122 Appendix A: Web Services Hub Error Messages

 Index

A generating in .Net 77
generating in Axis 73
attachments commit type
mapping 97 configuring 107
authentication configuration file
functions, details 51 parameters 9
security 41 updating dynamically 21
configuring
caching 106
B commit type 107
logging levels 16
Batch Web Services reader properties 103
functions 56 Web Services Hub 21
overview 30 writer properties 105
Browsing console
functions, details 52 Web Services Hub 37

C D
caching DeinitializeDIServerConnection
configuring 106 function 57
Clean Up documentation
in Axis 76 conventions xxvii
using .Net 79 description xxvi
client applications online xxvii
developing 69
Client Proxy Classes
generating 69

123
E StartWorkflow 59
StopDIServer 57
encryption StopTask 61
configuration file 21 StopWorkflow 59
security 41 UnscheduleWorkflow 59
environment variables WaitTillTaskComplete 61
JAVA_HOME 13 WaitTillWorkflowComplete 59
JAVA_OPTS 14
shared library 14
system path 13, 14 G
WSH_HOME 13
Error Codes generating names
in SOAP 46 setting option 87
Web Services Hub 114 Get Session Log
Error Handling function 64
in Axis 76 GetAllDIServers
using .Net 79 function 52
GetAllFolders
function 52
F GetAllTaskInstances
function 52
fault handling GetAllWorkflows
SOAP 45 function 52
fault messages GetDIServerConnectionState
importing 84 function 57
fault schema GetDIServerProperties
SOAP 46 function 58
flat file GetSessionPerformanceData
mappings 97 function 63
Functions GetSessionStatistics
DeinitializeDIServerConnection 57 function 62
GetAllDIServers 52 GetTaskDetails
GetAllFolders 52 function 62
GetAllTaskInstances 52 Getting Workflow Log
GetAllWorkflows 52 function 64
GetDIServerConnectionState 57 GetWorkflowDetails
GetDIServerProperties 58 function 62
GetSessionLog 64
GetSessionPerformanceData 63
GetSessionStatistics 62 I
GetTaskDetails 62
GettingWorkflowLog 64 importing
GetWorkflowDetails 62 fault messages 84
InitializeDIServerConnection 57 input messages 83
MonitorDIServer 62 operations 83, 84
PingDIServer 57 output messages 84
PowerCenter Server 57 web service definitions 85
ResumeTask 61 web service sources 83
ResumeWorkflow 60 infinite precision
ScheduleWorkflow 59 overriding 87
StartTask 61

124 Index
Informatica messageID
documentation xxvi propagating 96
Webzine xxviii messages
Initialization recovering 106
in Axis 73 Metadata and Batch Function Calls
using .Net 77 in Axis 75
InitializeDIServerConnection using .Net 79
function 57 metadata extensions
input messages web service definitions 91
importing 83 Metadata Web Services
installation described 31
verifying 19 MonitorDIServer
installation directories function 62
from install process 11 Monitoring and Reporting
installing functions 62
Web Services Hub 10

N
J naming columns
JAVA_HOME option 87
configuring on UNIX 13
configuring on Windows 13
O
L one-way mappings
defined 95
load scope operations
configuring 93 importing 83, 84
Log output messages
functions, detail 64 importing 84
log file
configuring 43
viewing 43 P
Login
function 51 PingDIServer
Logout function 57
function 51 pipeline partitioning 107
PowerCenter Server
functions, detail 57
M precision
overriding infinite length 87
mappings protected
attachment 97 described 102
flat file 97 published services
one-way 95 viewing 38
request-response 95
staged 96
XML 97 R
Max Log Buffer Size
Web Services Hub 65 reader properties
configuring 103

Index 125
Reader Time Limit Simple Client
description 104 error handling 71
real-time flush latency initialization 69
description 105 session maintenance 70
real-time sessions SOAP
configuring source-based commit 107 Body 4
defined 105 detail 46
setting the real-time flush latency session property 105 Envelope 4
Real-time Web Services extended details 46
overview 31 fault handling 45
using the Designer 82 fault structure 46
viewing published services 38 faultcode 46
recovering faultstring 46
messages 106 header 4
registering how web services work 2
Web Services Hub 23 presentation of 4
repository password staged mapping
encrypting 21 defined 96
request-response mappings starting
defined 95 Web Services Hub 19
ResumeTask StartTask
function 61 function 61
ResumeWorkflow StartWorkflow
function 60 function 59
runnable StopDIServer
described 102 function 57
stopping
Web Services Hub 20
S StopTask
function 61
ScheduleWorkflow StopWorkflow
function 59 function 59
security system path
authentication 41 setting 13, 14
encryption 41
service
configuring 101
service sessions
T
pipeline partitioning 107 Task
service workflow functions, detail 61
creating 101 timeout
session maintenance described 102
in Axis 75
using .Net 78
Web Services Hub 47 U
session properties
Reader Time Limit 104 Universal Description, Discovery and Integration
real-time flush latency 105 UDDI, overview 2
UnscheduleWorkflow
function 59

126 Index
UpdateConfigFile uninstalling 27
command line program 21 verifying installation 19
guidelines 22 writing a client application in .Net using C# 77
writing a client application in Java using Axis 73
Web Services Provider
V architecture 32
webzine xxviii
visible Workflow
described 102 functions, detail 59
Workflow Manager
registering the Web Services Hub 23
W writer properties
configuring 105
WaitTillTaskComplete WSH.wsdl
function 61 downloading 37
WaitTillWorkflowComplete editing 15
function 59 WSH_HOME
Web Service configuring on UNIX 13
configuring 101 WSHConfig.xml
web service editing 15
source definitions 83
target definitions 84
web service definitions
editing 89
X
viewing in the XML Editor 92 XML Editor
web service sessions 107 viewing web service definitions 92
Web Service targets
configuring load scope 93
Web Services
Batch, overview 30
building blocks 3
Metadata Web Services, overview 31
web services
batch functions, detail 56
Metadata Web Services functions, detail 50
overview 2
Web Services Description Language
WSDL, detail 5
WSDL, overview 2
Web Services Hub
configuration file 21
configuring 21
console 37
defined 30
installing on Unix 10
logging 16
Max Log Buffer Size 65
minimum system requirements 8
registering 23
session maintenance 47
starting 19
stopping 20

Index 127
128 Index