Web Services Developer's Guide - Software AG Documentation Web ...

insidiousbehaviorSecurity

Nov 3, 2013 (4 years and 5 days ago)

2,548 views

Web Services Developer’s Guide
Version 8.0
December 2009
Title Page

This document applies to webMethods Integration Server Version 8.0 and webMethods Developer Version 8.0 and to all subsequent releases.
Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions.
Copyright © 1998–2009 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, United States of America, and/or
their licensors.
The name Software AG, webMethods, and all Software AG product names are either trademarks or registered trademarks of Software AG
and/or Software AG USA, Inc. and/or their licensors. Other company and product names mentioned herein may be trademarks of their
respective owners.
Use of this software is subject to adherence to Software AG’s licensing conditions and terms. These terms are part of the product
documentation, located at http://documentation.softwareag.com/legal/
and/or in the root installation directory of the licensed product(s).
This software may include portions of third-party products. For third-party copyright notices and license terms, please refer to "License
Texts, Copyright Notices and Disclaimers of Third Party Products." This document is part of the product documentation, located at
http://documentation.softwareag.com/legal/
and/or in the root installation directory of the licensed product(s).
Document ID: DEV-WS-DG-80SP1-20091204
Copyright
& Docu-
ment ID

Web Services Developer’s Guide Version 8.0 3
Table of Contents
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Documentation Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Online Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
What Is a Web Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Using webMethods Software to Create, Publish, and Invoke Web Services . . . . . . . . . . . . 14
Using webMethods Software to Create Web Services . . . . . . . . . . . . . . . . . . . . . . . . . 14
Using webMethods Software to Publish Web Services to a UDDI Registry . . . . . . . . . 15
Using webMethods Software to Invoke Web Services . . . . . . . . . . . . . . . . . . . . . . . . . 15
What Are Web Service Descriptors and Connectors? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
What Is a WSDL Document? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Security for Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Backward Compatibility for Existing Web Service Connectors . . . . . . . . . . . . . . . . . . . . . . 17
2.Working with Service First Provider Web Service Descriptors . . . . . . . . . . . . . . . . . . . 19
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Creating a Service First Provider WSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Signature Requirements for Service First Provider Web Service Descriptors . . . . . . . . . . . 23
Signature Restrictions for Document/Literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Signature Restrictions for RPC/Encoded . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Signature Restrictions for RPC/Literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Handling Invalid Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Using XML Namespaces and Prefixes with Fields in Service Signatures . . . . . . . . . . 25
How Integration Server Represents Arrays in the WSDL Schema for
Document/Literal and RPC/Literal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Backward Compatibility for Web Service Descriptors Created in
Integration Server 7.x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
3.Working with WSDL First Provider Web Service Descriptors . . . . . . . . . . . . . . . . . . . . 27
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Creating a WSDL First Provider Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.Working with Consumer Web Service Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Creating a Consumer Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Supporting Elements for a Consumer Web Service Descriptor . . . . . . . . . . . . . . . . . . 34
Example Consumer Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Refreshing Web Service Connectors for a Consumer Web Service Descriptor . . . . . . . . . 36
Invoking a Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Table of Contents
4 Web Services Developer’s Guide Version 8.0

5.Editing Web Service Descriptor Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Changing the Target Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Viewing the Namespaces Used within a WSDL Document . . . . . . . . . . . . . . . . . . . . . . . . . 40
Modifying WS-I Compliance for a Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . 41
Reporting the WS-I Profile Conformance for a Web Service Descriptor . . . . . . . . . . . . 42
Enabling MTOM/XOP Support for a Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . 42
Adding SOAP Headers to the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Anatomy of SOAP Headers in the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Example of SOAP Headers in the Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Validating SOAP Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Viewing a WSDL Document for a Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.Working with Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Adding Operations to a Service First Provider Web Service Descriptor . . . . . . . . . . . . . . . 50
Adding an IS Service as an Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Adding an Operation from Another Provider Web Service Descriptor . . . . . . . . . . . . . 51
Using a 6.5 SOAP-MSG Style Service as an Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Modifying the Signature of a 6.5 SOAP-MSG Style Operation . . . . . . . . . . . . . . . . . . . 53
Deleting Operations from a Provider Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . 55
Adding a Header to an Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Adding SOAP Fault Processing to an Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Viewing Document Types for an Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
7.Working with Binders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Binders and Mixed Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Existing Web Service Descriptors with Mixed Use Binders . . . . . . . . . . . . . . . . . . 62
Adding a Binder to a Service First Provider Web Service Descriptor . . . . . . . . . . . . . . . . . 63
Copying Binders Across Provider Web Service Descriptors . . . . . . . . . . . . . . . . . . . . . 64
Deleting a Binder from a Service First Provider Web Service Descriptor . . . . . . . . . . . . . . 65
Deleting an Operation from a Binder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Modifying the SOAP Action for an Operation in a Binder . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Assigning a Web Service Endpoint Alias to a Binder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
How Integration Server Builds the Consumer Endpoint URL . . . . . . . . . . . . . . . . . . . . 68
How the Consumer Web Service Endpoint Alias Affects the Endpoint URL . . . . . . . . 68
How Integration Server Builds the Provider Endpoint URL . . . . . . . . . . . . . . . . . . . . . . 69
8.Working with Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
About Request Handler Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Request Handler Services and Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
About Response Handler Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Response Handler Services and Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Web Services Developer’s Guide Version 8.0 5
Table of Contents

About Fault Handler Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Fault Handler Services and Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Setting Up a Header Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Registering the Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Adding a Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Deleting a Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Example: Measuring Elapsed Time with a Consumer Handler . . . . . . . . . . . . . . . . . . . . . . 82
9.WS-Security Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Usage of WS-Security Standard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
The SOAP Message Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Securing Data at the Message Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Message Direction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Securing Web Service Providers and Consumers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Types of Message Authentication Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Message Security Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Signature Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Encryption Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Security Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Username and X.509 Certificate Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Token References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Policy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Policy File Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Supplied Policy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Certificate and Key Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Encrypting and Decrypting Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Signing and Verifying Signed Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Configuring the WS-Security Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Step Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Specifying the WS-Security Policy File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Assigning a Security Policy to a Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . 94
Passing Security Information into a WS Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Resolution Order of Certificates and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Locating Certificates and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Search Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Certificate Mapping and Usage Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Certificate Mapping: User Resolution Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Certificate Mapping: Usage Resolution Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
10.Authentication and Authorization for Web Service Descriptors . . . . . . . . . . . . . . . . . . 101
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Authentication and Authorization for Consumer Web Service Descriptors . . . . . . . . . . . . . 102
ACL Checking Scenarios for Consumer Web Service Descriptors . . . . . . . . . . . . . . . 104
Table of Contents
6 Web Services Developer’s Guide Version 8.0

Authentication and Authorization for Provider Web Service Descriptors . . . . . . . . . . . . . . . 104
ACL Checking Scenarios for Provider Web Service Descriptors . . . . . . . . . . . . . . . . . 107
11.Publishing IS Services to a UDDI Registry as a Web Service . . . . . . . . . . . . . . . . . . . . 109
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
What Is a UDDI Registry? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Connecting to a UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Refreshing a UDDI Registry Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Disconnecting from a UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Viewing a UDDI Registry in Developer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
UDDI Registry Tab Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
UDDI Registry Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Web Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Publishing a Service to the UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Removing a Service from UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Browsing for Web Services in UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Applying a Filter to UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Clearing an Applied Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
A.WS-Security Key Usage Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
WS-Security Key Resolution Order: Web Services Consumer . . . . . . . . . . . . . . . . . . . . . . 122
WS-Security Key Resolution Order: Web Services Provider . . . . . . . . . . . . . . . . . . . . . . . . 123
B.WS-Security Policy Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Policy File Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Policy Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
SecurityPolicy Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
InboundSecurity and OutboundSecurity Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Setting a Policy Element’s Usage Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Timestamp Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Outbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Inbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
UsernameToken Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Outbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Signature Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Outbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Inbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Encryption Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Outbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Inbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
X509 Authentication Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Outbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Inbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Web Services Developer’s Guide Version 8.0 7
Table of Contents

Sample Policy File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
List of Supplied WS-Security Policy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Consumer Policy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Provider Policy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Consumer and Provider Policy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
C.WS-Security: Detailed Usage and Resolution Order for Certificates and Keys . . . . . . 137
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Web Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Response (Outbound Security) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Request (Inbound Security) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Web Service Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Response (Inbound Security) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Request (Outbound Security) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
D.JAX-RPC Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Writing JAX-RPC Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
E.Web Service-Related Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Message Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
ISC (IS Core) Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
ISS (IS Server) Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
ITD (Developer) Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Table of Contents
8 Web Services Developer’s Guide Version 8.0


Web Services Developer’s Guide Version 8.0 9
About This Guide
This guide is for users who want to create Web services and incorporate Web services into
the integration solutions they develop. This guide explains how to generate Web service
description documents for webMethods services, how to publish services to a registry,
and how to use webMethods software to call Web services located on remote servers.
Terminology
The following terms are interchangeable:
 IS document type and ESB document type
 IS service and ESB service
Document Conventions
Note: This guide describes features and functionality that may or may not be available
with your licensed version of webMethods Integration Server. For information about
the licensed components for your installation, see the Settings > License page in the
webMethods Integration Server Administrator.
Convention
Description
Bold Identifies elements on a user interface.
Narrow font Identifies storage locations for services on webMethods Integration
Server, using the convention folder.subfolder:service.
UPPERCASE Identifies keyboard keys. Keys you must press simultaneously are
joined with a plus sign (+).
Italic Identifies variables for which you must supply values specific to your
own situation or environment. Identifies new terms the first time they
occur in the text.
Monospace
font
Identifies text you must type or messages displayed by the system.
{ } Indicates a set of choices from which you must choose one. Type only
the information inside the curly braces. Do not type the { } symbols.
| Separates two mutually exclusive choices in a syntax line. Type one of
these choices. Do not type the | symbol.
About This Guide
10 Web Services Developer’s Guide Version 8.0

Documentation Installation
You can download the product documentation using the Software AG Installer.
Depending on the release of the webMethods product suite, the location of the
downloaded documentation will be as shown in the table below.
Online Information
You can find additional information about Software AG products at the locations listed
below.
[ ] Indicates one or more options. Type only the information inside the
square brackets. Do not type the [ ] symbols.
...Indicates that you can type multiple options of the same type. Type
only the information. Do not type the ellipsis (...).
For webMethods...
The documentation is downloaded to...
6.x The installation directory of each product.
7.x A central directory named _documentation in the main
installation directory (webMethods by default).
8.x A central directory named _documentation in the main
installation directory (Software AG by default).
Note: The Empower Product Support Web site and the Software AG Documentation
Web site replace Software AG ServLine24 and webMethods Advantage.
If you want to...
Go to...
Access the latest version of product
documentation.
Software AG Documentation Web site
http://documentation.softwareag.com
Convention
Description
Web Services Developer’s Guide Version 8.0 11
About This Guide

Find information about product releases and
tools that you can use to resolve problems.
See the Knowledge Center to:
 Read technical articles and papers.
 Download fixes and service packs.
 Learn about critical alerts.
See the Products area to:
 Download products.
 Get information about product
availability.
 Access older versions of product
documentation.
 Submit feature/enhancement requests.
Empower Product Support Web site
https://empower.softwareag.com
 Access additional articles, demos, and
tutorials.
 Obtain technical information, useful
resources, and online discussion forums,
moderated by Software AG professionals,
to help you do more with Software AG
technology.
 Use the online discussion forums to
exchange best practices and chat with
other experts.
 Expand your knowledge about product
documentation, code samples, articles,
online seminars, and tutorials.
 Link to external Web sites that discuss
open standards and many Web
technology topics.
 See how other customers are streamlining
their operations with technology from
Software AG.
Software AG Developer Community
for webMethods
http://communities.softwareag.com/
webmethods
If you want to...
Go to...
About This Guide
12 Web Services Developer’s Guide Version 8.0


Web Services Developer’s Guide Version 8.0 13
1
Concepts
 What Is a Web Service?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
 Using webMethods Software to Create, Publish, and Invoke Web Services. . . . . . . . . . . . . . . .14
 What Are Web Service Descriptors and Connectors?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
 What Is a WSDL Document?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
 Security for Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
 Backward Compatibility for Existing Web Service Connectors . . . . . . . . . . . . . . . . . . . . . . . . . .17
1 Concepts
14 Web Services Developer’s Guide Version 8.0

What Is a Web Service?
Web services are building blocks for creating open, distributed systems. A Web service is a
collection of functions that are packaged as a single unit and published to a network for
use by other software programs. For example, you could create a Web service that checks
a customer’s credit or tracks delivery of a package. If you want to provide higher-level
functionality, such as a complete order management system, you could create a Web
service that maps to many different IS flow services, each performing a separate order
management function.
Using webMethods Software to Create, Publish, and Invoke
Web Services
You can use webMethods Integration Server and webMethods Developer to create Web
services, publish Web services to a UDDI registry, and invoke Web services located on
remote servers.
Using webMethods Software to Create Web Services
You can turn any service in any Integration Server package into a Web service.
Integration Server provides an environment for executing services efficiently and
securely. It receives and decodes requests from clients, calls the requested services, and
encodes and returns the output to the clients. Integration Server also provides an
extensive library of built-in services. Developer is the integrated development
environment (IDE) that you use to create services on Integration Server.
Integration Server’s service-oriented architecture makes it ideal for use in integration
scenarios because it separates implementation from presentation. When a client
application wants to invoke a Web service, the client need know only the service’s name,
inputs, and outputs. The client does not need to know how the service is implemented
(for example, in Java or C) or what kind of back-end system it accesses.
Similarly, the Web service implementation (that is, the back-end business logic) does not
need to know what kind of client invoked it. A client can use HTTP/HTTPS, FTP, or
SMTP to invoke the same service. You do not need to have multiple versions of the same
service because the webMethods content handler layer takes care of all marshalling and
unmarshalling between the protocol layer and the implementation layer.
Web Services Developer’s Guide Version 8.0 15
1 Concepts

Integration Server’s service-oriented architecture
With webMethods software, you can create Web services using programming languages
such as Java, C, or COM. You can also create Web services from existing back-end
systems, without producing custom code or reconfiguring the back-end systems, using
webMethods adapters.
Using webMethods Software to Publish Web Services to a UDDI
Registry
You can use webMethods Developer to incorporate Web services development into your
integration solution. Developer enables you to create Web services from existing IS
services and publish them to a UDDI registry.
For more information about Web services and the UDDI Registry, see Chapter 11,
“Publishing IS Services to a UDDI Registry as a Web Service” on page 109.
Using webMethods Software to Invoke Web Services
You can use webMethods Integration Server and webMethods Developer to invoke Web
services located on remote servers. To do so, you first generate a consumer Web service
descriptor from the remote Web service; you can then run the Web service connector(s) that
Integration Server generates for the consumer Web service descriptor.
For more information about Web service descriptors and connectors, see “What Are Web
Service Descriptors and Connectors?” on page 15. For more information about using Web
services in Developer, see “Invoking a Web Service” on page 37.
What Are Web Service Descriptors and Connectors?
A Web service descriptor (WSD) is an IS element that defines a Web service in IS terms. The
WSD contains all the information required by the provider or the consumer (requester) of
a Web service. The WSD contains the message formats, data types, transport protocols,
and transport serialization formats that should be used between the consumer (requester)
Java COM C
FTP SMTP
SOAP Doc-
Literal
SOAP
RPC/Encode
EDI
SOAP
RPC/Literal
webMethods invoke handler
HTTP/S
XML
Flow
transports
content handlers
example service types
1 Concepts
16 Web Services Developer’s Guide Version 8.0

and the provider of the Web service. It also specifies one or more network locations at
which a Web service can be invoked. In essence, the WSD represents an agreement
governing the mechanics of interacting with that service.
 A provider Web service descriptor defines a Web service that is hosted on the Integration
Server, that is, a service “provided” to external users. A provider Web service
descriptor will expose one or more IS services as operations, which can be published to
a registry as a single Web service. External users can access the Web service through
the registry and invoke the IS services remotely.
 A consumer Web service descriptor defines an external Web service, allowing Integration
Server to create a Web service connector (WSC) for each operation in the Web service.
The Web service connector(s) can be used in Developer just like any other IS flow
service; when a connector is invoked it calls a specific operation of a Web service.
Web service descriptors and connectors allow you to:
 Expose one or more IS services as operations of a Web service.
 Define and configure Web services. This includes settings used to generate a Web
Service Definition Language (WSDL) document for a provider Web service descriptor
and any information needed to process a SOAP request or response.
 Provide a URL to easily acquire a WSDL document for an IS provider Web service
 Define one or more “aliases” to be used with dynamic endpoint addressing for both
provider and consumer Web services. For a provider Web service descriptor, the alias
is used to populate the endpoint address of the Web service when generating the
WSDL. For a consumer Web service descriptor, the alias is used at runtime, when a
Web service connector is invoked, to determine the actual endpoint address of the
web service and/or to supply user credentials to be used with the request.
 Use Document/Literal, RPC/Literal, and RPC/Encoded style SOAP messages.
 Use either SOAP 1.1 or SOAP 1.2 protocols in Web service invocations.
 Define and process SOAP headers and handle SOAP faults (for both provider and
consumer web services).
 Use WS-Security to secure both provider and consumer Web services.
What Is a WSDL Document?
A Web Services Description Language (WSDL) document is an XML document that
describes Web services that are accessible over a network. The WSDL document for a
Web service contains all the information a Web service consumer needs to send data to
the Web service, invoke the Web service, and receive data from the Web service.
The WSDL document for a Web service describes the following:
 Logic the Web service performs
 Location of the Web service
Web Services Developer’s Guide Version 8.0 17
1 Concepts

 Method to use to access the Web service, including the protocol that the Web service
consumer must use to invoke the Web service and receive a response
 Input parameters that the Web service consumer must supply to the Web service and
the output parameters that the Web service returns
For instructions on viewing a WSDL document, see “Viewing a WSDL Document for a
Web Service Descriptor” on page 47.
Security for Web Services
The Integration Server WS-Security facility is a message-based security implementation
in which authentication information is contained in a SOAP message header that is
delivered along with the message payload. The facility implements a subset of the WS-
Security protection mechanisms described in the WS-Security, version 1.0 standards,
such as message signing and encryption, security timestamps, and use of Username and
X.509 certificate tokens. In contrast to transport-based authentication frameworks such as
HTTPS, which secure the endpoints of a connection against threats, WS-Security secures
the message transmission environment between endpoints. Such a framework provides a
higher level of protection for data passing across public networks than transport-based
security architectures.
By encapsulating security policy definitions in an XML file, the facility allows you to
define different security policies and select any policy for use with one or more
Integration Server-based Web services configured for WS-Security. For more information,
see Chapter 9, “WS-Security Facility” and Appendix B, “WS-Security Policy Reference”.
Backward Compatibility for Existing Web Service Connectors
A Web service connector that worked correctly with previous versions of Developer and
Integration Server should continue to work with version 8.0. In addition, any external
clients created from WSDL generated from previous versions of Developer and
Integration Server should continue to work as they did in the previous version.
1 Concepts
18 Web Services Developer’s Guide Version 8.0


Web Services Developer’s Guide Version 8.0 19
2
Working with Service First Provider Web Service
Descriptors
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
 Creating a Service First Provider WSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
 Signature Requirements for Service First Provider Web Service Descriptors. . . . . . . . . . . . . . .23
2 Working with Service First Provider Web Service Descriptors
20 Web Services Developer’s Guide Version 8.0

Introduction
A provider Web service descriptor is created from one or more IS services or from a single
WSDL document, and is designed to allow the IS services to be invoked as Web services
over a network. The provider Web service descriptor contains all the data required to
create a WSDL document for the IS Web service, as well as the data needed at run time to
process the request and response.
A service first provider WSD refers to provider WSDs created from an existing service on
Integration Server. In this case, you specify the protocol, binding style/use, and host
server when creating the WSD. The IS service becomes an operation in the provider
WSD. Integration Server uses the existing service signature as the input and output
messages for the operation. You can add operations and bindings to a service first
provider WSD.
For information about creating a WSDL first provider WSD, see “Creating a WSDL First
Provider Web Service Descriptor” on page 28.
The provider WSD can be published to a UDDI registry (or other publicly accessible
server) as a Web service, which can be invoked remotely by an external user. A Web
service provider can also distribute WSDL files directly to consumers. For more
information, see “Creating a Service First Provider WSD” and Chapter 11, “Publishing IS
Services to a UDDI Registry as a Web Service” on page 109.
Creating a Service First Provider WSD
Keep the following points in mind when creating a service first provider WSD
 You must have Write access to the folder in which you want to store the provider
WSD.
 The style and use selected for a provider WSD determines what types of fields and
field names are allowed in the service signature. Developer will not create a provider
WSD if the signature of the service does not meet the requirements of the selected
binding style/use. For more information, see “Signature Requirements for Service
First Provider Web Service Descriptors” on page 23.
 Depending on the use and style that you specify, you may have to either rename
certain fields in the IS service or assign an XML namespace to them.
 When using an adapter service to create a provider Web service descriptor, if the
service returns values in the pipeline that do not match the output signature, you
must change those variable properties to optional fields (where applicable), or else
wrap the service in a flow to add or drop variables to match the output signature.
 You can quickly create a service first provider WSD by right-clicking the service,
selecting New > Web Service Descriptor. Developer automatically creates an untitled
provider WSD in the same folder as the selected IS service, using all the default
options.
Web Services Developer’s Guide Version 8.0 21
2 Working with Service First Provider Web Service Descriptors

1 On the File menu, click New.
2 In the New dialog box, select Web Service Descriptor and click Next.
3 In the Web Service Descriptor dialog box, under Create Web service descriptor as, select
Provider.
4 Under Web service source, select Existing IS service(s).
5 Under Enforce WS-I Basic Profile 1.1 compliance do one of the following:

Select Yes if you want Developer to validate all the WSD objects and properties
against the WS-I requirements before creating the WSD.

Select No if you do not want Developer to enforce compliance for WS-I Basic
Profile 1.1.
6 Click Next.
7 In the Name field, specify a name for the provider WSD.
8 Next to Folder, select the folder in which you want to save the provider WSD. Click
Next.
9 Select one or more services to include as operations in the provider WSD. Click Next.
10 Provide the following information:
To create a service first provider WSD
In this field...
Specify...
End Point The address at which the Web service can be invoked:
 To use a provider Web service endpoint alias to specify the
host and port, in the Alias list, select the provider Web service
endpoint alias.
 To specify a host and port, in the Host field specify the host
name for the Integration Server on which the web service
resides. In the Port field, specify an active HTTP or HTTPS
listener port defined on the Integration Server specified in
the Host field.
Directive The SOAP processor used to process the SOAP messages
received by the operation in the provider WSD. The Directive
list displays all of the SOAP processors registered on the
Integration Server. The default processor is ws - Web Services
SOAP Processor.
SOAP Version Whether SOAP messages for this web service should use SOAP
1.1 or SOAP 1.2 message format.
Transport The transport protocol used to access the Web service. Select
HTTP or HTTPS.
2 Working with Service First Provider Web Service Descriptors
22 Web Services Developer’s Guide Version 8.0

11 Click Finish.
Notes:
 If Developer cannot create or cannot completely generate a Web service descriptor,
Developer displays error messages or warning messages. For more information about
errors that can occur when generating descriptors, see Appendix E, “Web Service-
Related Errors and Warnings”.
 You can edit WSD properties to indicate whether Integration Server enforces WS-I
Basic Profile 1.1 compliance, to change the target namespace, to enable SOAP
attachments, and to add SOAP headers to the pipeline. For more information about
editing Web service descriptor properties, see “Editing Web Service Descriptor
Properties” on page 39.
 If you specify a transport, but do not specify a host, port, or endpoint alias,
Integration Server uses the primary port as the port in the endpoint URL. However, if
the selected transport and the protocol of the primary port do not match, Developer
displays the following warning when you save the provider WSD:
Selected transport protocol does not match that of the primary port on
Integration Server.
For example, if you specify a transport of HTTPS when creating the provider WSD,
but do not specify a host, port, or endpoint alias and the primary port is an HTTP
port, Developer displays the above message.
You must resolve this mismatch before making a WSDL document for this provider
WSD available to Web service consumers. Otherwise, the Web service clients will not
execute successfully.
 You can specify that a custom RPC or SOAP processor handle SOAP messages
received by the provider WSD. If you select a custom processor, make sure that the
service(s) for which you are creating the provider WSD conform to the target service
requirements for the custom processor.
 You can add edit the provider WSD by adding or removing operations. For more
information, see Chapter 6, “Working with Operations”.
Use and Style for
Operations
The style/use for operations in the provider WSD. Select one of
the following:
 Document - Literal
 RPC - Literal
 RPC - Encoded
Target
Namespace
The URL that you want to use as the target namespace for the
provider WSD. In a WSDL document generated for this
provider WSD, the elements, attributes, and type definitions
will belong to this namespace.
In this field...
Specify...
Web Services Developer’s Guide Version 8.0 23
2 Working with Service First Provider Web Service Descriptors

 You can add or remove binders to a service first provide WSD. For more information,
see Chapter 7, “Working with Binders”.
 You can add service handlers to aWeb service descriptor. For more information about
adding handlers, see Chapter 8, “Working with Handlers”.
 You can add header or fault elements to an operation in the WSD. For more
information, see “Adding a Header to an Operation” on page 55 or “Adding SOAP
Fault Processing to an Operation” on page 57.
Signature Requirements for Service First Provider Web
Service Descriptors
When creating a WSDL document for a provider WSD, Integration Server uses the
service signature as the input and output messages for each operation. Integration Server
allows constructs within service signatures that cannot be represented in certain Web
service style/use combinations. The style/use specified for a binder in a service first
provider WSD determines the signature restrictions and/or requirements for its
operations. If a service signature does not meet the style/use signature requirements,
Integration Server will not add the service as an operation, or in the case of creating a
service first provider WSD, Integration Server will not create the WSD.
The list of restrictions and requirements for each style/use may not be exhaustive.
Signature Restrictions for Document/Literal
Signature Restrictions for RPC/Encoded
Signature Restrictions
*body fields are not allowed at the top level
@attribute fields (fields starting with the “@” symbol) are not allowed at the top level
String table fields are not allowed
Signature Restrictions
* body fields are not allowed
@attribute fields are not allowed (fields starting with the “@” symbol
Top-level fields cannot be namespace qualified
Top-level field names cannot be in the format prefix:localName
2 Working with Service First Provider Web Service Descriptors
24 Web Services Developer’s Guide Version 8.0

Signature Restrictions for RPC/Literal
Handling Invalid Signatures
When you expose a service in an Integration Server package as a Web service, the
exposed Web service must have valid input and output signatures. That is, the input
signature of the service must accurately reflect the expected input, and the output
signature of the service must accurately reflect the expected output. If the signatures are
not valid, the Web service descriptors derived from the service will be created with
incorrect signature information, and the Web service connector will not execute as
expected.
When working with services that do not have valid input or output signatures, you must
create a wrapper flow service with input and output signatures containing all of the
parameters and properties from both the service and the source and that invokes the
service you want to expose. Then you can expose the wrapper flow service as your Web
service.
For example, you want to expose an XSLT service as a Web service on one Integration
Server and invoke it from another. However, the XSLT source contains an optional
property (that can be specified at run time) for an input parameter. This optional
property is not reflected in the input signature of the XSLT service. The Web service
descriptors and Web service connector created for the XSLT service will not account for
this property, and the invocation will fail.
To successfully use the XSLT service, you would complete the following tasks:
1 Create a wrapper flow service that:

Defines all of the input parameters of the XSLT service in its input signature.

Defines the run-time property of the XSLT source in its input signature.

Invokes the XSLT service.
2 On the Integration Server that hosts the wrapper flow service and the XSLT service,
create a provider Web service descriptor from the wrapper flow service.
Signature Restrictions
*body fields are not allowed at the top level
@attribute fields (fields starting with the “@” symbol) are not allowed at the top level
String table fields are not allowed
List fields (String List, Document List, Document Reference List, and Object List) are
not allowed at the top level
Duplicate field names (identically named fields) are not allowed at the top level
Top-level fields cannot be namespace qualified
Top-level field names cannot be in the format prefix:localName
Web Services Developer’s Guide Version 8.0 25
2 Working with Service First Provider Web Service Descriptors

3 On the Integration Server from which you will invoke the Web service, create a
consumer Web service descriptor from the WSDL of the provider Web service
descriptor.
Using XML Namespaces and Prefixes with Fields in Service
Signatures
Although it is not always necessary to do so, you can associate the name of an Integration
Server field (such as an IS document variable) with an XML namespace. When you do so,
the local name is the name of the field and the XML namespace name is the URI that
identifies the namespace. You can also include a prefix as part of the name.
In Developer, assign XML namespaces and prefixes to Integration Server fields as
follows:
 To assign an XML namespace to an Integration Server field, complete the XML
Namespace property in the General category of the field’s Properties panel.
 To assign a prefix to an Integration Server field, precede the field name with the prefix
followed by a colon (for example, prefix:variableName).
How Integration Server Represents Arrays in the WSDL Schema for
Document/Literal and RPC/Literal
As of Integration Server version 8.0, the way in which Integration Server represents
arrays in the schema for a generated WSDL document with a Document/Literal or
RPC/Literal binding style has changed.
In Integration Server 7.x, Integration Server used a wrapping technique to represent an
array element. As of Integration Server 8.0, Integration Server represents an array as a
series of repeating elements without adding a wrapper element.
In the 7.x wrapping technique, Integration Server used the name of the array field as the
name of wrapper element in the schema. Integration Server declared the wrapper
element to be of a complex type named ArrayOflistType, where listType was the actual
data type for the repeating element. Integration Server defined the complex type
ArrayOflistType to be an unbounded sequence of an element named ArrayOflistTypeItem,
where listType was the actual data type of the repeating element. The ArrayOflistTypeItem
elements contained the actual data at run time.
The following examples illustrate how Integration Server represents an array for a
Document/Literal or RPC/Literal service in version 7.x and version 8.0. In these examples,
a flow service named myFlowService contains an input parameter named myStringList
which is of type String list.
Integration Server 7.x: String List in a WSDL Schema
<xsd:complexType name="myFlowService">
<xsd:sequence>
<xsd:element name=”myStringList” nillable=”true” type=”tns:ArrayOfstring”/>
2 Working with Service First Provider Web Service Descriptors
26 Web Services Developer’s Guide Version 8.0

</xsd:sequence>
<xsd:/complexType>
<xsd:complexType name=”ArrayOfstring”>
<xsd:sequence>
<xsd:element name=”ArrayOfstringItem” type=”xsd:string”
maxOccurs=”unbounded”/>
</xsd:sequence>
</xsd:complexType>
Integration Server 8.0: String List in a WSDL Schema
<xsd:complexType name="myFlowService">
<xsd:sequence>
<xsd:element name=”myStringList” nillable=”true” type=”xsd:string”
maxOccurs=”unbounded”/>
</xsd:sequence>
<xsd:/complexType>
Backward Compatibility for Web Service Descriptors Created in Integration
Server 7.x
The change in how Integration Server represents arrays in a WSDL schema for
Document/Literal and RPC/Literal Web services affects the structure and content of the
SOAP requests and SOAP responses for the operations of the Web service. To ensure that
Web service consumers created using a WSDL generated in Integration Server 7.x still
execute successfully, Integration Server only uses the new array handling approach for
provider Web service descriptors created in version 8.0 or higher. A WSDL generated for
any Web service descriptor created in Integration Server 7.x continues to use the array
wrapping technique even after the Web service descriptor is edited in Integration Server
8.0.
To determine which array handling technique is used for a Web service descriptor that
specifies an RPC/Literal or Document/Literal binding, examine the WSDL file for a Web
service descriptor with an operation (service) that contains an array in the signature.
If you want a Web service descriptor created in Integration Server 7.x to use the new
array format in the WSDL schema, you need to create a 8.x provider Web service
descriptor that uses the same operations (IS services) as the 7.x provider Web service
descriptor. The WSDL for the new provider Web service descriptor contains a schema
that makes use of the new array format. Consumers must create new Web service clients
based on the new WSDL.
Important! Integration Server uses the new, simpler array format only when creating
WSDL documents for provider Web service descriptors created in Integration Server
8.0 or higher. WSDL documents for provider Web service descriptors created in
Integration Server 7.x will continue to use the array wrapping format. For more
information, see “Backward Compatibility for Web Service Descriptors Created in
Integration Server 7.x”, below.

Web Services Developer’s Guide Version 8.0 27
3
Working with WSDL First Provider Web Service
Descriptors
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
 Creating a WSDL First Provider Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28
3 Working with WSDL First Provider Web Service Descriptors
28 Web Services Developer’s Guide Version 8.0

Introduction
A provider Web service descriptor is created from one or more IS services or from a single
WSDL document, and is designed to allow the IS services to be invoked as Web services
over a network. The provider Web service descriptor contains all the data required to
create a WSDL document for the IS Web service, as well as the data needed at run time to
process the request and response.
A WSDL first provider WSD refers to a provider WSD created from an existing WSDL
document or from a Web service acquired from a UDDI registry. In this case Developer
uses the message and operation definitions from the WSDL to generate a “placeholder”
flow service for each operation encountered in the WSDL, along with IS document types
defining the input and output signature of the generated flow services. You can then
implement any required logic within the placeholder flow service. Note that you cannot
add operations and bindings to a WSDL first provider WSD.
For information about creating a service first provider WSD, see “Creating a Service First
Provider WSD” on page 20.
Creating a WSDL First Provider Web Service Descriptor
You can create a WSDL first provider WSD from a WSDL document accessed via a URL
or from a UDDI registry.
Keep the following points in mind when creating a WSDL first provider WSD:
 You must have Write access to the folder in which you want to store the provider
WSD.
 If you are creating a provider WSD from a WSDL located on a Web site, if the Web site
on which the document resides is password protected, you must download the
WSDL document to your local file system and then create the provider WSD. If the
WSDL document imports WSDL documents or XML Schema definitions, you must
download those to your local file system as well and edit the original WSDL to point
to the local copies of those files.
 Relative URIs are disallowed by the WS-I Basic Profile 1.1 Compliance standard. If
you indicate that Developer enforces WS-I compliance and the WSDL file uses
relative URIs in any of the XSD import or include statements, Developer will not
create the provider WSD.
Important! Before making a WSDL document available for a WSDL first provider
WSD, the WSDL URL itself and any WSDL documents or schemas that are
imported or included in the WSDL must be made anonymously network
addressable. Otherwise, the files may not be addressable by a consumer.
Web Services Developer’s Guide Version 8.0 29
3 Working with WSDL First Provider Web Service Descriptors

 To create a WSDL first provider WSD from a Web service in a UDDI registry,
Developer must be configured to connect to that UDDI registry. For more
information about connecting Developer to a UDDI registry, see“Connecting to a
UDDI Registry” on page 111.
1 On the File menu, click New.
2 In the New dialog box, select Web Service Descriptor and click Next.
3 In the Web Service Descriptor dialog box, under Create Web service descriptor as, select
Provider.
4 Under Web service source, do one of the following:
5 Under Enforce WS-I Basic Profile 1.1 compliance do one of the following:

Select Yes if you want Developer to validate all the WSD objects and properties
against the WS-I requirements before creating the WSD.

Select No if you do not want Developer to enforce compliance for WS-I Basic
Profile 1.1.
6 Click Next.
7 In the Name field, specify a name for the provider WSD.
8 Next to Folder, select the folder in which you want to save the provider WSD. Click
Next.
9 If you specified WSDL URL in step 4, in the Enter a URL or select a local file field, do one of
the following:

Enter the URL for the WSDL document. The URL should begin with http:// or
https://

Click to navigate to and select a WSDL document on your local file system.
10 If you specified UDDI in step 4, select the Web service from the UDDI registry.
If Developer is not currently connected to a UDDI registry, the dialog box displays
the message “UDDI Registry Not Connected”.
11 Click Finish.
To create a WSDL first provider WSD
Select...
To generate a provider WSD from...
WSDL URL A WSDL document identified by a URL
UDDI A WSDL document in a UDDI registry
3 Working with WSDL First Provider Web Service Descriptors
30 Web Services Developer’s Guide Version 8.0

Notes:
 Developer creates the provider WSD and saves it to the folder you specified.
Developer also creates with any supporting IS elements, such as flow services and IS
document types.
 If Developer cannot create or cannot completely generate a provider WSD, Developer
displays error messages or warning messages. For more information about errors that
can occur when generating WSDs, see Appendix E, “Web Service-Related Errors and
Warnings”.
 Integration Server does not support mixed use across bindings and operations. That
is, all bindings and operations in a provider WSD must specify the same use (Literal
or Encoded). Developer does not create a provider WSD if the WSDL document
contains mixed “use” values across the binders and operations.
 You can edit WSD properties to indicate whether Integration Server enforces WS-I
Basic Profile 1.1 compliance, to enable SOAP attachments, and to add SOAP headers
to the pipeline. For more information about editing Web service descriptor properties,
see “Editing Web Service Descriptor Properties” on page 39.
 Operations and binders cannot be added, edited, or removed from a WSDL first
provider WSD.
 You can add service handlers to a WSDL first provider WSD. For more information
about adding handlers, see Chapter 8, “Working with Handlers”.
 You can add header or fault elements to an operation in the WSD. See “Adding a
Header to an Operation” on page 55 or “Adding SOAP Fault Processing to an
Operation” on page 57.

Web Services Developer’s Guide Version 8.0 31
4
Working with Consumer Web Service Descriptors
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
 Creating a Consumer Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
 Example Consumer Web Service Descriptor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
 Refreshing Web Service Connectors for a Consumer Web Service Descriptor. . . . . . . . . . . . . .36
 Invoking a Web Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37
4 Working with Consumer Web Service Descriptors
32 Web Services Developer’s Guide Version 8.0

Introduction
A consumer Web service descriptor (WSD) defines an external Web service. It contains all the
data from the WSDL document that defines the Web service, as well as data needed for
certain Integration Server run-time properties. Integration Server creates a Web service
connector (WSC) for each operation in the Web service. A WSC is a flow service with an
input and output signature that corresponds to the input and output messages of the
Web service operation. When Integration Server executes a Web service connector, the
Web service connector calls a specific operation of a Web service.
A consumer WSD is created from a Web service in a UDDI registry or from a WSDL
document.
Creating a Consumer Web Service Descriptor
You can create a consumer WSD from a WSDL document in a UDDI registry or a WSDL
document accessible via a URL.
 You must have Write access to the folder in which you want to store the consumer
WSD.
 If you are creating a consumer WSD from a WSDL located on a Web site, if the Web
site on which the document resides is password protected, you must download the
WSDL document to your local file system and then create the consumer Web service
descriptor. If the WSDL document imports WSDL documents or XML Schema
definitions, you must download those to your local file system as well and edit the
original WSDL to point to the local copies of those files.
 Relative URIs are disallowed by the WS-I Basic Profile 1.1 Compliance standard. If
you indicate that Developer enforces WS-I compliance and the WSDL file uses
relative URIs in any of the XSD import or include statements, Developer will not
create the consumer WSD.
 To create a consumer WSD from a Web service in a UDDI registry, Developer must be
configured to connect to that UDDI registry. For more information about connecting
Developer to a UDDI registry, see“Connecting to a UDDI Registry” on page 111.

1 On the File menu, click New.
2 In the New dialog box, select Web Service Descriptor and click Next.
3 In the Web Service Descriptor dialog box, under Create Web service descriptor as, select
Consumer.
4 Under Web service source, do one of the following:
To create a consumer Web service descriptor
Web Services Developer’s Guide Version 8.0 33
4 Working with Consumer Web Service Descriptors

5 Under Enforce WS-I Basic Profile 1.1 compliance do one of the following:

Select Yes if you want Developer to validate all the WSD objects and properties
against the WS-I requirements before creating the WSD.

Select No if you do not want Developer to enforce compliance for WS-I Basic
Profile 1.1.
6 Click Next.
7 In the Name field, specify a name for the provider WSD.
8 Next to Folder, select the folder in which you want to save the provider WSD. Click
Next.
9 If you specified WSDL URL in step 4, in the Enter a URL or select a local file field, do one of
the following:

Enter the URL for the WSDL document. The URL should begin with http:// or
https://.

Click to navigate to and select a WSDL document on your local file system.
10 If you specified UDDI in step 4, select the Web service from the UDDI registry.
If Developer is not currently connected to a UDDI registry, the dialog box displays
the message “UDDI Registry Not Connected”.
11 Click Finish.
Notes:
 Developer creates the consumer WSD and saves it to the folder you specified.
Developer also creates with any supporting IS elements, such as Web service
connectors and IS document types and places them in the same folder. For more
information about what elements Integration Server creates, see “Supporting
Elements for a Consumer Web Service Descriptor” on page 34.
 If Developer cannot create or cannot completely generate a consumer WSD,
Developer displays error messages or warning messages. For more information about
errors that can occur when generating WSDs, see Appendix E, “Web Service-Related
Errors and Warnings”.
 Developer does not create a consumer WSD if the WSDL document contains mixed
“use” values across the binders and operations.
Select...
To generate a provider WSD from...
WSDL URL A WSDL document identified by a URL
UDDI A WSDL document in a UDDI registry
4 Working with Consumer Web Service Descriptors
34 Web Services Developer’s Guide Version 8.0

 You can edit WSD properties to indicate whether Integration Server enforces WS-I
Basic Profile 1.1 compliance, to enable SOAP attachments, to add SOAP headers to
the pipeline, and to validate the SOAP response received by Web service connectors
in this consumer WSD. For more information about editing Web service descriptor
properties, see “Editing Web Service Descriptor Properties” on page 39.
 Operations and binders cannot be added, edited, or removed from a consumer WSD.
 You can add service handlers to a consumer WSD. For more information about
adding handlers, see Chapter 8, “Working with Handlers”.
 You can add header or fault elements to an operation in the Web service descriptor.
See “Adding a Header to an Operation” on page 55 or “Adding SOAP Fault
Processing to an Operation” on page 57.
Supporting Elements for a Consumer Web Service Descriptor
When Developer creates a consumer Web service descriptor, it also creates supporting IS
elements. Each of the IS elements that Developer creates corresponds to an element in the
WSDL document.

Example Consumer Web Service Descriptor
The following consumer Web service descriptor was generated from a WSDL document
that describes a Web service that authorizes a credit card. The WSDL document specified:
This IS element...
Corresponds to this WSDL element...
wsdName_ The WSDL document. All supporting IS elements for the
consumer Web service descriptor are contained in this new
folder. The folder name is the same as the Web service
descriptor, with a suffix of an “_” (underscore).
docType folder All of the IS document types generated from the messages
in the WSDL document
connectors folder All of the Web service connectors generated from the
operations in the WSDL document
Web service
connector
Each unique
<operation>
element in a
<portType>
element;
the Web service connector name corresponds to the
operation name
IS document type Each
<message>
element in the WSDL document. The IS
document type name corresponds to the message name
IS schema Each target namespace to which the element declarations,
attribute declarations, and type definitions that define the
message parts (input and output signature) belong
Web Services Developer’s Guide Version 8.0 35
4 Working with Consumer Web Service Descriptors

 An input message named AuthorizeCreditCard that specified the inputs
AccountNumber and OrderTotal
 An output message named AuthorizeCreditCardResponse that specified the output
AuthorizationCode and TransNumber
 A
<binding>
element that specified SOAP RPC as the protocol
 A
<service>
element that contained one
<port>
named
CreditCardAuth_AuthorizeCreditCard_Port
 A single
<operation>
element named AuthorizeCreditCard
On the Input/Output tab for the Web service connector, note that the Web service connector
uses references to the input and output IS document types to define the service signature.
Input/Output tab for a Web service connector
Developer inserts flow steps into the Web service connector by following an internal
template for inserting input data into the service request, sending the request, processing
the response, and adding service output values to the pipeline. The template that
Developer follows depends on the protocol specified in the WSDL document. The
following illustration shows the Web service connector generated for the Web service that
performs credit card authorization.
The IS document type
generated from the output
message is used to declare
the output signature.
The IS document type
generated from the input
message is used to declare
the input signature.
Developer creates these
elements from the WSDL
document.
4 Working with Consumer Web Service Descriptors
36 Web Services Developer’s Guide Version 8.0

Web service connector for credit card authorization Web service
Refreshing Web Service Connectors for a Consumer Web
Service Descriptor
When you create a consumer WSD, Developer automatically generates the Web service
connector(s). After you have added, deleted, or modified a header, fault, or endpoint
alias within a binder for a consumer WSD, you must refresh (or regenerate) the Web
service connectors. This process overwrites all the existing Web service connectors for a
consumer WSD.
1 In the Navigation panel, open the consumer WSD for which you want to refresh Web
service connectors.
2 Click the operation editing area or the Binders tab.
3 Click or right-click and select Refresh Web Service Connectors. Integration Server
regenerates all Web service connectors in the consumer WSD, overwriting the existing
Web service connectors.
Note: The $default port corresponds to the first named
<port>
element in the WSDL
document.
Important! When refreshing a Web service connector, Integration Server deletes the
consumerWSDName_ folder and all elements contained in that folder and its
subfolders.
To regenerate a Web service connector
This BRANCH step contains
a child step for each named
port.
This BRANCH step contains
a child step for each named
binding.
This SEQUENCE
corresponds to a binding for
the SOAP RPC protocol.
Web Services Developer’s Guide Version 8.0 37
4 Working with Consumer Web Service Descriptors

Invoking a Web Service
When you locate a Web service that you want to use in your integration solution,
generate a consumer Web service descriptor from the WSDL document for the remote
Web service.
When Developer generates the consumer WSD, it automatically creates a Web service
connector for each operation in the Web service.
The Web service connector is a flow service that:
 Uses an input and output signature that corresponds to the input and output
messages defined in the WSDL document
 Contains flow steps that create and send a message to the Web service using the
transport, protocol, and location information specified in the Web service’s WSDL
document
 Contains flow steps that extract data from the output message returned by the service
To run the Web service, you invoke the Web service connector. The client (Integration
Server) binds directly to the endpoint of the Web service. When the Web service
connector executes, the request to invoke the Web service goes directly to the Web
service.
4 Working with Consumer Web Service Descriptors
38 Web Services Developer’s Guide Version 8.0


Web Services Developer’s Guide Version 8.0 39
5
Editing Web Service Descriptor Properties
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
 Changing the Target Namespace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
 Viewing the Namespaces Used within a WSDL Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
 Modifying WS-I Compliance for a Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
 Enabling MTOM/XOP Support for a Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . .42
 Adding SOAP Headers to the Pipeline. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
 Validating SOAP Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
 Viewing a WSDL Document for a Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
5 Editing Web Service Descriptor Properties
40 Web Services Developer’s Guide Version 8.0

Introduction
After you create a Web service descriptor, you can use properties to do the following
 Change the target namespace used for components the WSDL document (for service
first provider WSD only)
 Enable or disable enforcement of compliance with the WS-I Basic Profile 1.1
 Allow SOAP attachments based on the MTOM/XOP specifications
 Add the contents of SOAP headers to the pipeline
 Validate the SOAP response received by a Web service connector in a consumer WSD
 Set permissions for the WSD. For information about assigning permissions to an IS
element, see Developing Integration Solutions: webMethods Developer User’s Guide
Changing the Target Namespace
For a service first provider Web service descriptor, you can change the target namespace
that Integration Server uses in the generated WSDL document. The target namespace
specifies the XML namespace to which the elements, attributes, and type definitions in
the WSDL belong.
You can only change the target namespace for service first provider WSD. For a WSDL
first provider WSD or a consumer WSD, the target namespace is determined by the
WSDL document used as the source.
1 In the Navigation panel, open and lock the service first provider WSD for which you
want to change the target namespace.
2 In the Property panel, in the Target namespace field, specify the URL that you want to
use as the target namespace for elements, attributes, and type definitions in the
WSDL generated for this provider WSD.
3 On the File menu, click Save.
Viewing the Namespaces Used within a WSDL Document
You can view a list of all the XML namespaces used by the Web service descriptor when it
is first created. You can also view the prefix associated with each XML namespace.
To change the target namespace for a service first provider WSD
Web Services Developer’s Guide Version 8.0 41
5 Editing Web Service Descriptor Properties

1 In the Navigation panel, open the Web service descriptor for which you want to view
the list of XML namespaces.
2 In the Properties panel, click View in the Namespaces field.
The Namespaces dialog box appears displaying a list of XML namespaces used
within the WSDL document. This is an array of namespace prefixes and their
associated XML namespace names. This information is not editable.
3 Click OK to close the dialog box.
Modifying WS-I Compliance for a Web Service Descriptor
The WS-I option specifies whether the Web service descriptor enforces compliance with
the WS-I Basic Profile 1.1, a set of guidelines for using web services specifications to
maximize interoperability (including guidance for such core Web services specifications
such as SOAP, WSDL, and UDDI).
As an example, using the RPC/Encoded style and use is not supported by the WS-I
profile. If a Web service descriptor makes use of the RPC/Encoded style, and WS-I
compliance is enabled, Developer displays indicating that the WSD is not compliant and
prompts you to save the WSD as non-compliant.
Enforcing WS-I compliance also affects the contents and signature for operations in the
WSD. For example, the use of multiple top-level fields is not supported in the WS-I
profile; if a service (operation) in a provider WSD includes multiple top-level fields,
Developer prompts you to save the WSD as non-compliant
The WS-I compliance option is set to Yes or No when you create a Web service descriptor
(No is the default). You can modify this option by changing the WS-I compliance property.
To view the namespaces and prefixes used in a Web service descriptor
Note: The WS-I profile only address the SOAP 1.1 protocol. If the Web service
descriptor is using the SOAP 1.2 protocol, Developer will display an error message
when True is selected.
5 Editing Web Service Descriptor Properties
42 Web Services Developer’s Guide Version 8.0

1 In the Navigation panel, open and lock the Web service descriptor for which you
want to change WS-I compliance enforcement.
2 On the Property panel, next to WS-I compliance, select True if you want Integration
Server to enforce WS_I Basic Profile 1.1 compliance. Otherwise, select False.
3 On the File menu, click Save.
Reporting the WS-I Profile Conformance for a Web Service Descriptor
You can analyze aWeb service descriptor for conformance to the WS-I Basic Profile 1.1.
Developer displays the results in a WS-I Profile Conformance Report.
1 In the Navigation panel, open and lock the Web service descriptor for which you
want to generate a WS-I Profile Compliance report.
2 Click to generate and display the WS-I Profile Conformance Report.
Enabling MTOM/XOP Support for a Web Service Descriptor
Integration Server supports SOAP attachments based on the MTOM/XOP specifications
for Web service descriptors that:
 Use the SOAP 1.2 protocol
 Specify style/use of RPC/Literal or Document Literal
The Message Transmission Optimization Mechanism (MTOM) feature provides
optimization of binary message transportation using XOP (XML-binary Optimized
Packaging). If attachments are enabled for the Web service descriptor, instances of XML-
type base64Binary are transported using MIME attachments, which improves the
performance of large binary payload transport.
You need to configure the watt.server.SOAP.MTOMThreshold property with the
appropriate value before enabling SOAP attachments for a Web service descriptor. This
property specifies the field size, in kilobytes, that determines whether Integration Server
sends base64binary encoded data in a SOAP message as a MIME attachment or whether
it sends it inline in the SOAP message.
To modify WS-I compliance for a Web service descriptor
To generate a WS-I Profile Conformance Report
Web Services Developer’s Guide Version 8.0 43
5 Editing Web Service Descriptor Properties

1 In the Navigation panel, open the Web service descriptor for which you want to
enable or disable SOAP attachments.
2 On the Property panel, next to Attachment enabled, select True if you want to enable
SOAP attachments for the WSD. Otherwise, select False.
3 On the File menu, click Save.
Adding SOAP Headers to the Pipeline
For a Web service descriptor, you can instruct Integration Server to add the contents of
SOAP headers to the pipeline, making the contents of the SOAP headers available to
subsequent services. The value of the Pipeline headers enabled property determines
whether or not Integration Server places the contents of the SOAP header in the pipeline
as a document named soapHeaders.
If the Pipeline headers enabled property is set to true for a provider WSD, when an IS
service that corresponds to an operation in the WSD is invoked, Integration Server places
the contents of the SOAP request header in the input pipeline for the IS service.
If the Pipeline headers enabled property is set to true for a consumer WSD, when one of the
Web service connectors is invoked, Integration Server places the contents of the SOAP
response header in the output pipeline for the Web service connector.
To enable SOAP attachments for a Web service descriptor
Tip! By default, the public service pub.string:base64Encode inserts a new line after 76
characters of data. This is not the canonical lexical form expected by MTOM
implementations. If you use this public service rather than a custom service for
base64 encoding, you can use the optional input parameter useNewLine to remove the
line break and the optional input parameter encoding to change the encoding. The
default value for useNewLine is true, which keeps the line break at 76 characters. If
you do not specify the encoding, ASCII will be used.
If you use the public service pub.string:base64Decode for base64 decoding, you can use
the optional input parameter encoding to change the encoding. If you do not specify
the encoding, ASCII will be used.
Note: For Web service descriptors contained in packages created in versions of
Integration Server prior to version 8.0, the Pipeline headers enabled property is set to
True.
5 Editing Web Service Descriptor Properties
44 Web Services Developer’s Guide Version 8.0

1 In the Navigation panel, open the Web service descriptor for which you want to
enable or disable adding SOAP headers to the pipeline.
2 On the Property panel, next to Pipeline headers enabled, select True if you want to enable
SOAP attachments for the WSD. Otherwise, select False.
3 On the File menu, click Save.
Anatomy of SOAP Headers in the Pipeline
For an IS service invoked as a Web service, the soapHeaders document contains the
element and parameter information from the SOAP request header and allows the header
information to be passed to the service. For a Web service connector, the soapHeaders
document contains the element and parameter information from the SOAP response
header.
The soapHeaders document adheres to the following generic structure:
The following table describes the contents of the soapHeaders document in the pipeline:
To add SOAP headers to the pipeline
soapHeaders Document An IData containing the SOAP headers
HDRDOC1:local
Name
Document List Structure of a header element (block)
from the SOAP message. The
HDRDOC1:localName document list contains one
document for each header with the same QName.
Note: HDRDOC1 represents the prefix of the first
header block. localName is a placeholder and will
be replaced by the local name of the header block.
Note: The soapHeaders document contains a
document list named HDRDOC#:localName for
each header element (block) in the SOAP message
header.
Web Services Developer’s Guide Version 8.0 45
5 Editing Web Service Descriptor Properties

Key
Description
ns1:fieldName String Name of the first field in
the header element (block)
Note: The prefix ns1 is a
placeholder and will be replaced
by the prefix of the child element
of the header element (block).
Likewise, fieldName is a
placeholder and will be replaced
by the local name of the first
child element contained in the
header element (block).
nsDecls Document Namespaces
associated with any namespace
prefixes that are used in the
child element names in
HDRDOC1:localName. Each
entry in nsDecls represents a
namespace prefix/URI pair,
where a key name represents a
prefix and the value of the key
specifies the namespace URI.
Key
Description
ns1 String Namespace
declaration associated
with the prefix ns1,
where ns1 is a
placeholder and will
be replaced by the
prefix used with the
first child element of
the header element
(block).
nsDecls Document Namespaces associated with any
namespace prefixes used by the header elements
(blocks).
Note: This document will contain a child string
named HDRDOC# for each namespace prefix
used with a header element (block).
5 Editing Web Service Descriptor Properties
46 Web Services Developer’s Guide Version 8.0

Example of SOAP Headers in the Pipeline
For example, suppose that an IS service invoked as a Web service received this SOAP
request:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header>
<pfx1:firstHdrElement xmlns:pfx1=”namespace1” xmlns:hdr1ns=”ns1namespace”>
<hdr1ns:firstField>Value of firstField in firstHdr</hdr1ns:firstField>
</pfx1:firstHdrElement>
<pfx2:secondHdrElement xmlns:pfx2=”namespace2”
xmlns:hdr2ns=”ns2namespace”>
<hdr2ns:firstField>Value of firstField in secondHdr</hdr2ns:firstField>
</pfx2:secondHdrElement>
</SOAP-ENV:Header>