Web Services Developer S Guide Software Ag Documentation Web PDF

Title Page
Web Services Developer’s Guide
Version 8.0
December 2009
Copyright
& Docu-
ment ID
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

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
Web Services Developer’s Guide Version 8.0 3

Table of Contents
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
4 Web Services Developer’s Guide Version 8.0

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
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
Signature Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Encryption Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
X509 Authentication Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

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

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.
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.
Terminology
The following terms are interchangeable:
 IS document type and ESB document type
 IS service and ESB service
Document Conventions
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 Identifies text you must type or messages displayed by the system.
font
{} 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
Convention Description
[] 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 (...).
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.
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).
Online Information
You can find additional information about Software AG products at the locations listed
below.
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 Software AG Documentation Web site
documentation.
http://documentation.softwareag.com

About This Guide
If you want to... Go to...

Find information about product releases and Empower Product Support Web site
tools that you can use to resolve problems.
https://empower.softwareag.com
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.
 Access additional articles, demos, and Software AG Developer Community
tutorials. for webMethods
 Obtain technical information, useful http://communities.softwareag.com/
resources, and online discussion forums, webmethods
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.

About This Guide

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

1 Concepts
Integration Server’s service-oriented architecture
transports HTTP/S FTP SMTP
content handlers SOAP Doc- SOAP SOAP

XML EDI
Literal RPC/Encode RPC/Literal
webMethods invoke handler
example service types Flow Java COM C
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)

1 Concepts
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

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

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

To create a service first provider WSD
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:
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.

Use and Style for The style/use for operations in the provider WSD. Select one of
Operations the following:
 Document - Literal
 RPC - Literal
 RPC - Encoded
Target The URL that you want to use as the target namespace for the
Namespace provider WSD. In a WSDL document generated for this
provider WSD, the elements, attributes, and type definitions
will belong to this namespace.
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”.

 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
*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 for RPC/Encoded
* 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

Signature Restrictions for RPC/Literal
*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
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.

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

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

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

 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.
To create a WSDL first provider WSD

Provider.
4 Under Web service source, do one of the following:
Select... To generate a provider WSD from...
WSDL URL A WSDL document identified by a URL

UDDI A WSDL document in a UDDI registry
Profile 1.1.
6 Click Next.
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 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.
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.

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

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.
To create a consumer Web service descriptor

Consumer.
4 Under Web service source, do one of the following:

Select... To generate a provider WSD from...
WSDL URL A WSDL document identified by a URL

UDDI A WSDL document in a UDDI registry
Profile 1.1.
6 Click Next.
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.

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.
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 Each unique <operation> element in a <portType> element;
connector 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
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:

 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 creates these

elements from the WSDL
document.
The IS document type
generated from the input
message is used to declare
the input signature.
The IS document type

generated from the output
message is used to declare
the output signature.
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.

Web service connector for credit card authorization Web service
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.
Note: The $default port corresponds to the first named <port> element in the WSDL
document.
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.
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
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.

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.


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

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.
To change the target namespace for a service first provider WSD
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 view the namespaces and prefixes used in a Web service descriptor
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.
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.

To modify WS-I compliance for a Web service descriptor
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.
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.
To generate 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 enable SOAP attachments for a Web service descriptor
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.
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.
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.
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.

To add SOAP headers to the pipeline
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.
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:
soapHeaders Document An IData containing the SOAP headers

HDRDOC1:local Document List Structure of a header element (block)
Name 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.

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

Key Description
HDRDOC1 String Namespace declaration

associated with the prefix
HDRDOC1.
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>
<SOAP-ENV:Body>
...
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Integration Server creates a soapHeaders document that looks like the example and adds it
to the input pipeline of the IS service:

Validating SOAP Responses

For a consumer Web service descriptor, you can indicate whether or not Integration
Server validates a SOAP response received by any Web service connectors within the
consumer WSD.
The value of the watt.server.SOAP.validateResponse server configuration parameter
determines whether or not the Validate SOAP response property is honored or ignored.
 When watt.server.SOAP.validateResponse is set to true, the value of the Validate SOAP
response property determines whether or not Integration Server validates the SOAP
response.
 When watt.server.SOAP.validateResponse is set to false (or anything besides true),
Integration Server ignores the Validate SOAP response property and does not validate
the SOAP response.
By default, the watt.server.SOAP.validateResponse is set to true.
To validate the SOAP responses received by Web service connectors
1 In the Navigation panel, open the consumer WSD for which you want to enable or
disable SOAP response validation.
2 On the Property panel, next to Validate SOAP response, select True if you want to
Integration Server to validate SOAP response messages received by Web service
connectors included with this consumer WSD. Otherwise, select False.
Viewing a WSDL Document for a Web Service Descriptor

Using the default browser application, Developer displays a read-only version of the
WSDL document on which a Web service descriptor is based.
 For a consumer Web service descriptor, the WSDL document is a local copy of the
original WSDL document used to create the consumer Web service descriptor with
the addition of any headers or faults added to the consumer Web service descriptor.
The displayed WSDL document does not reflect any changes made to the editable
properties of the consumer Web service descriptor or its constituents, such as the use
of a Web service endpoint alias for the Port alias property. The displayed WSDL
document does not reflect any modifications made either locally or in the source
URL.
 For a service first provider Web service descriptor, the WSDL document contains all
the information a consumer needs to create a Web service client that invokes the
operations described in the WSDL.

 For a WSDL first provider Web service descriptor, the WSDL document is the original
source WSDL with the addition of any headers or faults added to the provider Web
service descriptor. The displayed WSDL document also updates the location of the
operations to point to the endpoint service on Integration Server. The displayed
WSDL document reflects any changes made to the editable properties of the provider
Web service descriptor or its constituents, such as the use of a Web service endpoint
alias for the Port alias property. The displayed WSDL document contains all the
information a consumer needs to create a Web service client that invokes the
operations described in the WSDL.
Note: You can use the URL of the generated WSDL document to download the WSDL.
To view a WSDL document for a Web service descriptor
1 In the Navigation panel, open the Web service descriptorfor which you want to view
the WSDL document.
2 Click anywhere in the operation editing area to enable the operation toolbar.
3 Click on the operation toolbar. Developer locates the WSDL document for the
Web service descriptor and displays it using the system’s default browser.

6 Working with Operations
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
 Adding Operations to a Service First Provider Web Service Descriptor . . . . . . . . . . . . . . . . . . . 50
 Using a 6.5 SOAP-MSG Style Service as an Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
 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

Introduction
An operation is the WSDL element that exposes some functions of a Web service and
defines how data is passed back and forth. In a Web service descriptor, an operation
corresponds to a service on Integration Server.
Each operation contains a single request and a single response. Each request and
response contains a single, read-only body element and one or more header elements. A
response can also contain fault elements.
The body elements contain the application-defined XML data being exchanged in the
SOAP message:
 In a service first provider WSD, the body elements represent the signature of the
service. The body element in the request contains the input properties. The body
element in the response contains the output properties.
 In a WSDL first provider WSD or a consumer WSD, the input/output properties and
the body element are defined by the remote WSDL document. Neither the
input/output definitions nor the operations can be changed, added, or deleted.
A header element defines the format of the SOAP headers that may be present in a SOAP
message (request or response). Headers are optional and can be added to or deleted from
any Web service descriptor.
A fault element provides a definition for a SOAP fault (that is, the response returned to the
sender when an error occurs while processing the SOAP message). Fault elements are
optional and can be added to or deleted from any Web service descriptor.
Adding Operations to a Service First Provider Web Service

Descriptor
You can only add operations to a service first provider WSD. When you add operations to
a service first provider WSD, the operations are also added to every binder in the WSD.
The values defined by a specific binder will apply to the operation.
You can add operations by:
 Adding one or more IS services from the Navigation panel. Each service will be
converted to an operation in the provider WSD.
 Copying or moving an operation from another provider WSD.
 Adding a 6.5 SOAP-MSG Style Service as an operation. For more information, see
“Using a 6.5 SOAP-MSG Style Service as an Operation” on page 52.

Adding an IS Service as an Operation
To add an IS service as an operation to a provider Web service descriptor
1 In the Navigation panel, open and lock the service first provider WSD to which you
want to add an IS service as an operation.
2 Click (Add Operation) on the operations editing area toolbar. Or, right-click in the
operations editing area and select Add Operation.
3 In the Select one or more services to include in the Web service descriptor dialog box,
select one or more services and click Finish.
The specified operations are added to the provider WSD. The operations appear in
the operation editing area edit tree and are also added to each binder contained in the
provider WSD.
Notes:
 If a service signature does not meet the style/use signature requirements established
by the existing binder, Developer does not add the service as an operation.
 If the operation already exists in the Web service descriptor, Developer adds it as a
copy and appends “_n” to its name, where n is an incremental number.
 You can also add operations by selecting one or more services in the Navigator panel
and dragging them into the operation editing area.
 You can also add an operation using the button on either the operation editing
area or on the Binders tab. The operation will be displayed in both areas of the editor.
Adding an Operation from Another Provider Web Service Descriptor

You can copy or move an operation from another Web service descriptor to a service first
provider WSD.
To copy or move an existing operation from one provider WSD to another
1 In the Navigation panel, open and lock the provider WSD that contains the operation
you want to copy or move.
2 In the operations editing area, select one or more operations. Then select Cut or Copy
from either the right-click menu or the main Edit menu.
3 In the Navigation panel, open and lock the provider WSD into which you want to
paste the cut or copied operations (the target provider WSD).

4 In the operations editing area of the target WSD, right-click and select Paste. Or, on
the Edit menu, click Paste.
Notes:
 Developer adds the specified operations to the provider WSD. In addition to
displaying the operations in the operation editing area edit tree, Developer adds the
operations to all binders in the target Web service descriptor exactly as they existed in
the source Web service descriptor. The binder values for each individual binder apply
to the operations within the binders.
 If the operation being added already exists in the provider WSD, Developer adds it as
a copy and appends “_n” to its name, where “n” is an incremental number.
Using a 6.5 SOAP-MSG Style Service as an Operation

In webMethods Integration Server version 6.5, you could expose an IS service as a SOAP-
MSG Web service. The 6.5 SOAP-MSG style services used the default SOAP processor,
specified SOAP version 1.1, and specified a style/use of Document/Literal. You can
migrate 6.5 SOAP-MSG style services to the Web service descriptor framework
introduced in Integration Server 7.1 by adding the service as an operation to a provider
WSD. By migrating the service, you can leverage the inherent functionality of a provider
WSD, such as headers, handlers, faults, and WS-Security header handlers.
By default, Integration Server derives the input and output signatures for operations
from the services used to create the operation. Integration Server 6.5 required that an IS
service in the SOAP-MSG style use a signature that took a soapRequestData object and a
soapResponseData object as input and produced a soapResponseData object as output. This
signature requirement does not result in meaningful signature information for the
operation in WSDL documents generated for the provider WSD. To produce a
meaningful, descriptive signature for an operation that corresponds to a 6.5 SOAP-MSG
style service, you must select an IS document type or an XML schema element declaration
to represent the service input and output signature.
Keep the following points in mind when adding a 6.5 SOAP-MSG style service as an
operation to a provider WSD:
 You can add the 6.5 IS service to an existing provider WSD or create a new provider
WSD for the IS service. For information about adding an IS service as an operation to
a provider WSD, see “Adding an IS Service as an Operation” on page 51. For
information about creating a service first provider WSD, see “Creating a Service First
Provider WSD” on page 20.
 The provider WSD must have a single binder with the following properties:
 SOAP version = SOAP 1.1 protocol
 SOAP binding style = document
 SOAP binding use = literal

 To produce a meaningful signature for the operation in a WSDL document, you must
select an IS document type or an XML schema element declaration to represent the
input and output signatures. For information about changing the input or output
signature for an operation, a provider WSD, see“Modifying the Signature of a 6.5
SOAP-MSG Style Operation” on page 53.
 If you use an IS document type for the input and/or output signature, the IS
document type must satisfy the service signature requirements for the SOAP-MSG
style as specified in theWeb Services Developer’s Guide version 6.5.
 If you add any headers to the operation, any existing clients for the 6.5 service must
be modified to include the header in the SOAP request.
 Any header handler processing that changes the SOAP message and occurs before
service invocation affects the SOAP message passed to the service. Note that 6.5
SOAP-MSG style services expect the SOAP message to be in a certain format.
Specifically, any changes to the SOAP body might affect the ability of the 6.5 SOAP-
MSG style service to process the request.
 When a 6.5 SOAP-MSG style service is added as an operation, you can add fault
processing to the operation response. For fault processing to work, you need to
modify the 6.5 SOAP-MSG style service to detect a Fault condition, add Fault output
data to the pipeline, and drop the SOAP response message (soapResponseData object)
from the pipeline.
Modifying the Signature of a 6.5 SOAP-MSG Style Operation

A Web service requires the input parameters from a signature and produces the output
parameters. By default, an operation derives the input and output signatures from the
services used to create the operation. However, in the case of a 6.5 SOAP-MSG style
service, the input and output signatures consist of a soapRequestData and
soapResponseData objects. In a WSDL document, this would result in an vague,
meaningless signature. To create a meaningful service signature for a 6.5 SOAP-MSG
style operation, you can override the original service signature by selecting an element
declaration in an XML schema definition or an IS document type as the service signature.
Overriding the service signature is necessary after adding a 6.5 SOAP-MSG style service
as an operation to a provider WSD.
Keep the following points when modifying the operation signature source:
 You can only modify the operation signature source in a provider WSD that was
created from an IS service. You cannot add or modify the signature of a provider
WSD created from a WSDL URL or a UDDI Registry.
 The XML schema definition you select must be located on the Web and must be
network accessible to consumers of the WSDL. Do not use a local file URL to refer to
an external schema.
 If you use an IS document type as the signature for an operation that corresponds to
an Integration Server 6.5 SOAP message service, the IS document type must satisfy
the service signature requirements for the SOAP MSG protocol a specified in the Web

Services Developer’s Guide version 6.5. For more information about adding an IS 6.5
SOAP message service as an operation, see “Using a 6.5 SOAP-MSG Style Service as
an Operation” on page 52.
To modify the signature type of an operation
1 In the Navigation panel, open and lock the provider Web service descriptor
containing the operation whose signature you want to modify.
2 In the operation editing area, select and expand the operation whose signature you
want to modify.
3 Do one of the following:
To change the... Do this...
Input signature Expand Request and select the Body element.

Output signature Expand Response and select the Body element.
4 Next to the Signature property, click Modify Signature.

5 In the Modify I/O Signature dialog box, do one of the following:
Select... To...
Original IS Use the input or output signature from the originating IS service
service as the input or output signature. This is the default.
Existing external Use an element declaration from an XML schema definition as
XML schema the input or output signature.
Document type Use an IS document type as the input or output signature.
6 If you selected Existing external XML schema in step 5, do the following:

a In the URL field, after http://, type the Web location and name of the XML
schema definition that contains the element declaration you want to use to
describe the signature.
b Click Load. Developer groups the element declarations in the XML Schema under
the ELEMENTS heading. Expand the heading to view the global element
declarations in the XML Schema.
c Select the global element declaration for the input or output signature from the
Elements list.
7 If you selected Document type in step 5, next to Folder, select the IS document type that
you want to use to represent the input or output signature.
8 Click OK.

Deleting Operations from a Provider Web Service Descriptor

You can delete operations from a service first provider WSD only.
To delete an operation from a provider Web service descriptor
1 In the Navigation panel, open and lock the provider WSD that contains the operation
to delete.
2 In the operations editing area, select the operation to be deleted.
3 Click on the operations editing toolbar. Or right-click and select Delete. Developer
deletes the selected operation from the Web service descriptor.
4 Click OK.
Notes:
 Developer removes deleted operations from within all the binders in the provider
WSD.
 If you delete an operation from within a binder, any other instances of that operation
in other binders remain in the Web service descriptor. (If an operation exists in only
one binder and is deleted from that binder, the operation is removed from the Web
service descriptor.) For more information, see “Deleting an Operation from a Binder”
on page 65.
Adding a Header to an Operation

A header is optional in an operation’s request or response. You can use headers to add
extra features and functionality to a SOAP message or for functions such as security,
transactions, or language preferences.
For a... You can...
Consumer WSD  Add new headers to the request or the response

 Edit or delete any of the headers you have added
 Edit the Must understand and Role properties for
headers derived from the source WSDL

For a... You can...
WSDL First Provider WSD  Add new headers to the request or the response
 Delete any headers (the ones derived from the source
WSDL as well as any you have added)
 Edit the headers you have added.
 Edit the Must understand and Role properties for
headers derived from the source WSDL.
Service First Provider WSD  Add new headers to the request or the response
 Delete any headers
 Edit any headers
Keep the following points in mind when adding headers to operations:

 You can copy or move header document types between headers or between faults,
but not between a header and a fault. You can use the same document type for a
request and a response, subject to the handlers available in the Web service
descriptor.
 When adding a header element to a provider Web service descriptor, be sure that the
header does not have the same name as any of the fault elements for that Web service
descriptor.
 An IS document type used as a header or fault for an operation with a binding
style/use of RPC/Encoded cannot contain fields named *body or @attribute fields
(fields starting with the “@” symbol).
 A header must have a registered header handler. However, you can add the header to
an operation and register a header handler for it later. A header without a handler
will be ignored or will cause the request to fail (depending on whether the Must
Understand property for the header is set to False or True).
 After a header handler is registered in Integration Server, the IS document types
associated with the handler will be listed in the selection dialog box that is displayed
when you add a header. For more information about handlers, see Chapter 8,
“Working with Handlers”. For more information about registering handlers, see
“Registering the Handler” on page 81.
 This version of webMethods Integration Server includes the WS Security Handler,
which implements a WS-Security process. This handler does not expose supported
headers, so the selection dialog box will not be populated if this handler is the only
one registered. For more information about implementing WS-Security, see
Chapter 9, “WS-Security Facility” on page 85.
 You can also add headers to an operation by dragging IS document types from the
Navigation panel to the operations editing area.

To add a header to an operation
1 In the Navigation panel, open and lock the Web service descriptor to which you want
to add a header.
2 In the operations editing area, expand the operation and the request or response to
which you want to add the header.
3 Select the header icon and click (Add Header or Fault) on the editor toolbar.
Because a header was selected when you clicked this button, the document selection
dialog box displays only those IS document types supported by the header handlers
listed in the Handler tab.
4 Select the IS document type to use as a header. Click OK.
Important! When you add a header (or a fault) to a consumer Web service descriptor,
you must refresh the Web service connector(s). See “Refreshing Web Service
Connectors for a Consumer Web Service Descriptor” on page 36.
Adding SOAP Fault Processing to an Operation

Within an operation, the fault element describes a SOAP fault — that is, the response
returned to the sender by the Web service if an error occurs while processing the SOAP
message. Fault elements are optional and can be added to the response in any operation.
When generating a Web service descriptor from an existing WSDL, each message element
is converted into an IS document type. If an operation defines a soap:fault element, the
corresponding Web services connector includes steps to detect the fault element within
the SOAP response message and to format the fault element into an IS document type in
the pipeline.
To generate a fault, the underlying IS service should return an instance of one of the fault
document types added to the response. Integration Server recognizes that the pipeline
contains a fault document and generates a SOAP message whose body contains a SOAP
fault element with the SOAP 1.1 or SOAP 1.2 format and the Detail element contains a
fault document.
Multiple documents can be added to the response. If the underlying Integration Server
service returns multiple instances of the fault document types in the pipeline, the Detail
element contains only one fault message which is the fault document that is listed first in
the response.
For example, if the provider Web service descriptor defines a fault named
InvalidInvoiceFault and the pipeline the IS service returns contains a document object
named InvalidInvoiceFault, Integration Server generates a SOAP message whose SOAP
body contains a SOAP Fault element and whose Detail element contains the
InvalidInvoiceFault document.

Keep the following points in mind when adding fault processing to an operation:
 You can only add fault elements to a response, not to a request.
 For existing Web service descriptors, the fault document must be an IS document
type.
 When adding a fault element to a provider Web service descriptor, make sure that the
fault does not have the same name as any of the headers for that Web service
descriptor.
 You can also add fault elements to an operation by dragging an IS document type
from the Navigation panel and dropping it onto the operation fault element.
To add a fault element to an operation
to add a fault element.
2 In the operation editing area, expand the operation and the response to which you
want to add the fault element.
3 Select the Fault icon and click (Add Header or Fault button) on the editor toolbar.
Because a fault was selected when you clicked this button, Developer displays the
default document selector dialog.
4 Select the IS document type to use as the fault element. Click OK.
Important! After you add a fault (or header) to a consumer Web service descriptor, you
must refresh Web service connector(s). See “Refreshing Web Service Connectors for a
Consumer Web Service Descriptor” on page 36.
Viewing Document Types for an Operation

You can view the IS document types used by the header, body, or fault elements of an
operation on the Document tab. The Document tab is read-only. To modify IS document
types, you must open them from the Navigation panel, edit them, and then add or
replace them in the operations to which they belong.
To view document types
1 In the Navigation panel, open the Web service descriptor for which you want to view
used IS document types.
2 Select the Document tab.

3 In the operation editing area, select and expand an operation. Then, select and
expand a request or response.
4 In the operation editing area, click a header, body, or fault element.
Developer displays the IS document types used by the element (if any) in the
Document tab.


7 Working with Binders
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
 Binders and Mixed Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
 Adding a Binder to a Service First Provider Web Service Descriptor . . . . . . . . . . . . . . . . . . . . . . 63
 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

Introduction
A binder is a webMethods term for a collection of related definitions and specifications for
a particular port. The binder is a container for the endpoint address, WSDL binding
element, transport protocol, and communication protocol information. Developer creates
at least one binder when it generates the Web service descriptor based on the data in the
WSDL or IS service. The Binders tab displays the binders defined for a Web service
descriptor.
You can add new binder definitions to a service first provider WSD. Binders cannot be
added to a WSDL first provider WSD or a consumer WSD.
You can define a separate binder for each combination of endpoint address and protocol
information that you want the service first provider WSD to support. The Web service
descriptor can contain any combination of RPC/Encoded, RPC/Literal, or
Document/Literal binders.
Note: If the WS-I compliance property is set to True, you can only create binders that
comply with the WS-I profile.
Binders and Mixed Use

Integration Server and Developer do not support mixed “use” across binders and
operations in a single Web service descriptor. That is, the binders in aWeb service
descriptor must specify the same value for the SOAP binding use property.
Integration Server and Developer enforce this restriction in the following way:
 In a service first provider WSD, the first binder determines the “use” for all
subsequent binders. If the first binder specifies a SOAP binding use of “literal”, any
additional binder added to the provider WSD must specify literal as the SOAP binding
use.
 When creating a WSDL first provider WSD or a consumer WSD from a WSDL
document, Integration Server will not create the WSD if the WSDL document
contains bindings with different use value or operations with different use values.
Integration Server throws the following exception:
[ISS.0085.9285] Bindings or operations with mixed "use" are not supported.
Existing Web Service Descriptors with Mixed Use Binders

Integration Server continues to support existing Web service descriptors that contain
binders with mixed use as long as the Web service descriptors are not modified. Once the
WSD is modified, Developer will not save the WSD if it has mixed use binders.

To edit and save an existing provider WSD with mixed binders, create separate provider
WSDs for each binder use. For example, if a provider WSD contains binder1 which
specifies a “use” of literal and binder2 which specifies a “use” of encoded, copy the
provider WSD. In the provider WSD copy, remove binder1. In the original provider
WSD, remove binder2. The provider Web service descriptors can then be saved.
Adding a Binder to a Service First Provider Web Service

Descriptor
You can add a binder definition to a service first provider WSD. All existing operations
will be duplicated within the new binder.
Keep in mind that the new binder must specify the same “use” as the binder that already
exists in the provider WSD. For more information about mixed use in binders, see
“Binders and Mixed Use” on page 62.
To add a binder to a service first provider Web service descriptor
1 In the Navigation panel, open and lock the provider WSD to which you want to add a
binder.
2 On the Binders tab, click on the Binder tab toolbar or right-click and select Add
Binder.
3 In the New Binder Options dialog box, specify the following information:
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.
Use and Style for The style/use for operations in the provider WSD. Select one of
Operations the following:
 Document - Literal
 RPC - Literal
 RPC - Encoded
Important! Make sure to specify a style/use with the same “use”

as the existing binder in the provider WSD.
4 Click OK. Developer adds the new binder to the Binder tab.
Notes:
 If the binder “use” does not match the “use” for the existing binder, Developer does
not save the binder. Instead, Developer displays the following message
[ISS.0085.9282] Bindings or operations with mixed "use" are not supported.
 The new binder contains all the operations in the Web service descriptor.
 To rename a binder, right-click the binder and select Rename.
 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 H TTPS 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.
Copying Binders Across Provider Web Service Descriptors

You can cut or copy an existing binder from another provider WSD and paste it into the
Binder tab of a service first provider WSD. (Note that drag and drop of binders is not
supported).

Keep the following points in mind when pasting in a binder from another provider WSD:
 The endpoint, directive, WS-I, transport, and use-style values are the same as those in
the original (source) binder. You can modify these in the Properties panel.
 All operations in the cut or copied binder are carried with it. If a pasted binder
contains an operation that is not already in the Web service descriptor, the operation
is added to the Web service descriptor.
Deleting a Binder from a Service First Provider Web Service

Descriptor
You can delete a binder from a service first provider WSD.
A Web service descriptor must contain at least one binder. If you delete the last binder in
a Web service descriptor, you must add a new binder before the Web service descriptor
can be saved (the binder can be empty).
To delete a binder from service first provider Web service descriptor
1 In the Navigation panel, open and lock the service first provider WSD from which
you want to delete a binder.
2 On the Binders tab, select the binder to delete.
3 Click on the Binder tab toolbar or right-click and select Delete.

Deleting an Operation from a Binder

If two binders share an operation, you can delete the operation from one binder but not
the other. The operation will still be in the provider WSD, but only be in one binder. You
can delete operations from a service first provider WSD only.
To delete an operation from a binder in a provider Web service descriptor
1 In the Navigation panel, open and lock the service first provider WSD.
2 On the Binders tab, expand the binder containing the operation to delete.
3 In the binder, select the operations you want to delete.
4 Click on the Binder tab toolbar or right-click and select Delete.

Developer displays a Delete Confirmation dialog box.

5 Click OK.
Developer deletes the selected operation from the binder.
Notes:
 If other binders in the provider WSD contain the operation, that operation remains in
the WSD.
 If an operation only exists in one binder, deleting it from that binder removes it
entirely from the Web service descriptor.
 If you delete an operation from the operation editing area, it is deleted entirely from
the WSD and from all the binders that exist for that WSD. For more information about
deleting operations, see “Deleting Operations from a Provider Web Service
Descriptor” on page 55.
Modifying the SOAP Action for an Operation in a Binder

You can change the SOAP action specified for an operation in a binder in a service first
provider WSD. At run time, the values associated with a SOAP action are used to find the
actual operation being invoked. By default, the SOAP action uses the format
binderName_operationName to ensure that it is unique within a Web service.
For provider WSDs, the values for the SOAP action property are used to populate the
soapAction attribute of the WSDL Binding operation element when Integration Server
generates a WSDL document. At run time, these attributes should be present in the
SOAPAction Header on the inbound request.
For consumer WSDs, the values for the SOAP action property are extracted from the
WSDL Binding operation elements in the WSDL used to generate the consumer Web
service descriptor. These attributes will be placed into the SOAPAction header of the
outbound request.
To modify the SOAP Action property for an operation in a provider Web service descriptor
1 In the Navigation panel, open and lock the provider WSD.

2 On the Binders tab, select the binder containing the operations for which you want to
edit the SOAP action.
3 In the Properties panel, next to the SOAP action property, click the View button.
Developer displays the Binder SOAP Actions dialog box which identifies the
SOAPAction string associated with each operation in the selected binder.
4 Change the values in the SOAP Action column as required. Make sure that the new
SOAP Action values remain unique.

5 Click OK.
Developer applies the SOAP action change to the operation in this binder only.
Assigning a Web Service Endpoint Alias to a Binder

You can associate a Web service endpoint alias with a binder in a provider or consumer
Web service descriptor. A Web service endpoint alias represents the network address
and, optionally, any security credentials to be used with Web services. The network
address properties can be used to enable dynamic addressing for Web services. The
security credentials can be used to control both transport-level and message-level
security for Web services.
For a consumer WSD and its associated Web service connectors (WSC), the alias
information (including the addressing information and any security credentials), is used
at run time to generate a request and invoke an operation of the Web service. For WSCs
behind a firewall, the endpoint alias also specifies the proxy alias for the proxy server
through which Integration Server routes the Web service request.
For a provider WSD, the endpoint alias is used to construct the “location=” attribute of
the soap:address element within the wsdl:port element when WSDL is requested for the
Web service. The security credentials may be used when constructing a response to a Web
service request.
For information about creating a Web service endpoint alias, see Administering
webMethods Integration Server.
To associate an endpoint alias with a Web service descriptor
to associate the Web service endpoint alias.
2 On the Binders tab, select the binder to which you want to assign an endpoint alias.
3 In the Properties panel, next to the Port alias property, select the Web service endpoint
alias that you want to associate with the WSD. Developer lists only those endpoint
aliases of the same type as the WSD.
Note: When the Port alias property is modified for a consumer Web service descriptor
and, the Web service descriptor is viewed as WSDL (the View WSDL button is clicked),
the generated WSDL does not reflect the change to the port alias. However, the new
value will be used at run-time.

How Integration Server Builds the Consumer Endpoint URL

When invoking a Web service connector, Integration Server constructs the endpoint URL
using the following pieces of information:
 The port address specified by the location attribute in the WSDL from which the
consumer WSD was created.
 The value of the _url input parameter passed in to the Web service connector
 The consumer Web service endpoint alias specified in the binding of the consumer
WSD.
The value of the _url parameter and the assigned consumer Web service endpoint alias
can determine the URL used to invoke the Web service operation. That is, the _url
parameter and the consumer Web service endpoint alias can override all or portions of
the endpoint URL specified in the WSDL.
Integration Server builds the endpoint URL at run time as follows:
Step 1 Determine the initial URL

If a value is specified for the _url input parameter for a Web service
connector, that value overrides the entire endpoint URL as specified in the
original WSDL. Otherwise, Integration Server uses the endpoint URL from
the original WSDL.
Step 2 Override the host/port portion of the URL.
If a consumer Web service endpoint alias is assigned to the binder for the
invoked operation, the endpoint alias host and/or port information overrides
the host and/or port information in the URL resulting from Step 1. For more
information about how Integration Server uses the host and/or port
information to construct the endpoint URL, see “How the Consumer Web
Service Endpoint Alias Affects the Endpoint URL” on page 68.
How the Consumer Web Service Endpoint Alias Affects the Endpoint
URL
The host and/or port information provided in the consumer Web service endpoint alias
assigned to a binder determine the host:port portion of the endpoint URL. The following
table explains how Integration Server builds the endpoint URL at run time when host
and/or port are specified in the consumer Web service endpoint alias.
Note: If a value is specified for the _url input parameter for a Web service connector
the url value takes overrides the original URL from the WSDL. Additionally,
Integration Server ignores the host and port information provided in the consumer
Web service endpoint alias.

Original URL in WSDL

or If Host Integration Server constructs this
Value of _url input parameter Name is... If Port is... endpoint URL...
http://localhost:5555/ws/ http://localhost:5555/ws/
folder:wsName folder:wsName
http://localhost:5555/ws/ newHost http://newHost:5555/ws/
http://localhost:5555/ws/ 6666 http://localhost:6666/ws/
http://localhost:5555/ws/ newHost 6666 http://newHost:6666/ws/
http://localhost/ws/ http://localhost/ws/
http://localhost/ws/ newHost 6666 http://newHost:6666/ws/
http://localhost/ws/ 6666 http://localhost:6666/ws/
http://localhost/ws/ newHost http://newHost/ws/
How Integration Server Builds the Provider Endpoint URL

When creating a WSDL for a provider WSD, Integration Server determines the host and
port portions of the endpoint URL using information from one of the following:
 Provider web service endpoint alias assigned to the binder
 Port address property value specified for the binder
 Integration Server hostname and primary port
Integration Server determines the host and port portions of the endpoint URL as follows:
Step 1 If provider Web service endpoint alias is assigned to the binder, Integration
Server uses the host name and port from the provider web service endpoint
alias in the endpoint URL.
Step 2 If provider Web service endpoint alias is not provided, Integration Server
uses the host name and port from the value of the Port address property.
Step 3 If provider Web service endpoint alias is not provided and the Port address
property does not have a value, Integration Server uses the Integration
Server host name and primary port.

The following table describes how Integration Server determines the host and port
portions in the URL for the soap:address element for a binding:
Provider Web Service Port Address

Endpoint Alias assigned? specified? Endpoint URL uses...
Yes Yes Provider web service endpoint
alias hostname and port
Yes No Provider web service endpoint
alias hostname and port
No Yes Port address hostname and port
No No Integration Server hostname and
primary port

8 Working with Handlers
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
 About Request Handler Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
 About Response Handler Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
 About Fault Handler Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
 Setting Up a Header Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
 Example: Measuring Elapsed Time with a Consumer Handler . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Introduction
When working with Web services on Integration Server, the SOAP body portion of the
SOAP message contains the data representing the input and output signatures of the
underlying SOAP operation. In typical processing, Integration Server converts the SOAP
body between its XML representation in the SOAP message and the Document (IData)
representation used within Integration Server automatically.
In addition to the data contained in the SOAP body, a SOAP message might contain data
in the SOAP headers. The best way to access the SOAP headers is to use handlers. A
handler, sometimes called a header handler, provides access to the entire SOAP message.
Handlers can be used to perform various types of processing, including processing SOAP
headers, adding SOAP headers, removing SOAP headers, passing data from the header
to the endpoint service or vice versa.
In Integration Server, a handler is a set of up to three handler services. The handler can
contain one of each of the following handler services:
 Request handler service
 Response handler service
 Fault handler service
Any IS service can be used as a handler service. However, handler services must use a
specific service signature. Integration Server defines the service handler signature in the
pub.handler.soap:handlerSpec specification. Integration Server also provides several services
that you can use when creating handler services. These services are located in the
pub.soap.handler folder in the WmPublic package.
When you register a handler, you name the handler, identify the services that function as
the request, response or fault handler services, and indicate whether the handler is for
use with providerWeb service descriptors or consumer Web service descriptors.
You can assign multiple handlers to a Web service descriptor. Developer displays the
handlers on the Handlers tab. The collection of handlers assigned to a Web service
descriptor is called a handler chain. For a consumer Web service descriptor, Integration
Server executes the handler chain for output SOAP requests and inbound SOAP
responses. For a provider Web service descriptor, Integration Server executes the handler
chain for inbound SOAP requests and outbound SOAP responses.
When executing the handler chain, Integration Server executes request handler services
by working through the handler chain from top to bottom. However, Integration Server
executes response handler services and fault handler services from bottom to top.
The order of handlers in the handler chain may be important, depending on what
processing the handlers are performing. For example, a WS-Security handler that is
performing encryption or digitally signing a request should generally be the final handler
in the list for a consumer, but the first handler in the list for a provider.

About Request Handler Services

A request handler service is used with a SOAP request. The processing point at which
Integration Server invokes a request handler service depend on whether the Web service
descriptor is a consumer or a provider.
 For a consumer Web service descriptor, Integration Server invokes the request
handler service for each handler in the handler chain after creating the initial
outbound SOAP request but before sending the SOAP request to the Web service
provider.
 For a provider Web service descriptor, Integration Server invokes the request handler
service for each handler in the handler chain immediately after the provider receives
the SOAP request. After successfully executing the request handler service for each
handler in the handler chain, Integration Server invokes the endpoint service.
A request handler service is sometimes referred to as a handleRequest service.
Request Handler Services and Status Codes

Each request handler service must return a status code. The status code is an integer from
0–3, indicates the success or failure of the request handler service, and indicates how
Integration Server will proceed.
 For a consumer Web service descriptor, the request handler service status determines
whether or not Integration Server sends the SOAP request to the Web service
provider. Integration Server sends the SOAP request only after all request handler
services in the handler chain return a status code of 0. If a request handler service
returns a status code of 1, 2, or 3, handler chain processing stops and Integration
Server does not send the SOAP request to the provider.
 For a provider Web service descriptor, the request handler service status determines
whether or not Integration Server invokes the endpoint service. Integration Server
invokes the endpoint service only after all request handler services in the handler
chain return a status code of 0. If a request handler service returns a status code of 1,
2, or 3, handler chain processing stops and Integration Server does not invoke the
endpoint service.
The following table describes the meaning of each status code for a request handler
service and the action Integration Server takes based on the status code.

Status Code Description

0 Indicates that the request handler service executed successfully.
Integration Server executes the next request handler service in the
handler chain.
Consumer Side Behavior
If this is the last handler in the handler chain, Integration Server sends
the SOAP request to the Web service provider.
Provider Side Behavior
If this is the last handler in the handler chain Integration Server invokes
the endpoint service, passing in data from the SOAP request.
1 Indicates that the handler service ended in failure. Integration Server
suspends execution of the handler chain. Integration Server then invokes
the response handler service for each handler that has already executed
in the handler chain. Integration Server starts with the current handler
and continues in reverse order until it invokes all the response handlers
for the executed request handlers in the handler chain.
Integration Server constructs a SOAP fault and places it in the message
context which can be accessed by the response handler services. The
SOAP fault contains the following information:
 [ISS.0088.9430] Handler processing failed on the <provider or
consumer>. where <provider or consumer> indicates whether the
handler processing failed on the provider or consumer.
 Fully qualified name of the request handler service that failed.
If the request handler failed while processing a SOAP request for a
consumer Web service descriptor, Integration Server does not send the
SOAP request to the provider.
provider Web service descriptor, Integration Server does not invoke the
endpoint service.


2 Indicates that the request handler service ended in failure. Integration
Server suspends execution of the handler chain.
Integration Server constructs a SOAP fault. The SOAP fault contains the
following information:
 Contents of the faultMessage output parameter.
consumer Web service descriptor, Integration Server returns a
SOAPFault to the Web service connector.
Integration Server does not send the SOAP request to the provider.
provider Web service descriptor, Integration Server returns a SOAP
response containing the SOAP fault to the Web service consumer.
Integration Server does not invoke the endpoint service.
3 Indicates that the request handler service ended in failure. Integration
Server suspends execution of the handler chain. Integration Server then
invokes the fault handler service for each handler that has already
executed in the handler chain. Integration Server starts with the current
handler and continues in reverse order until it invokes all the fault
handlers for the request handlers executed in the handler chain.
Note: One of the fault handler services in the handler chain should
contain logic that constructs a SOAP fault message. If it does not, the
SOAP fault message will be empty. This service also needs to replace the
SOAP message in the current message context with the SOAP fault
message.
consumer Web service descriptor, Integration Server does not send the
SOAP request to the provider.
provider Web service descriptor, Integration Server does not invoke the
endpoint service.

About Response Handler Services

A response handler service is used with a SOAP response. The processing point at which
Integration Server invokes a response handler service depends on whether the Web
service descriptor is a consumer or a provider.
 For a consumer Web service descriptor, Integration Server invokes the response
handler service for each handler in the handler chain after it receives the initial SOAP
response from the Web service provider.
Integration Server also invokes a response handler service for a consumer Web
service descriptor if a request handler service failed and returned a status code of 1. In
this situation, Integration Server does not invoke the response handler service for
every handler in the handler chain. Instead, Integration Server invokes the response
handler service for each handler that has already executed in the handler chain.
Integration Server starts with the current handler and continues in reverse order until
it invokes all the response handlers for the executed request handlers in the handler
chain.
 For a provider Web service descriptor, Integration Server invokes the response
handler service after the IS service exposed as an operation executes successfully and
creates a SOAP response. Integration Server invokes each response handler service in
the handler chain for the provider Web service descriptor and then sends the updated
SOAP response to the Web service client.
Integration Server also invokes a response handler service for a provider Web service
descriptor if a request handler service failed and returned a status code of 1. In this
situation, Integration Server does not invoke the response handler service for every
handler in the handler chain. Instead, Integration Server invokes the response
handler service for each handler that has already executed in the handler chain.
Integration Server starts with the current handler and continues in reverse order until
it invokes all the response handlers for the executed request handlers in the handler
chain.
A response handler service is sometimes referred to as a handleResponse service.
Response Handler Services and Status Codes

Each response handler service must return a status code. The status code is an integer
from 0–3, indicates the success or failure of the response handler service, and indicates
how Integration Server will proceed. The following table describes the meaning of each
status code for a response handler service and the action Integration Server takes based
on the status code.


0 Indicates that the response handler service executed successfully.
Integration Server executes the next response handler service in the
handler chain.
If this is the last handler in the handler chain, Integration Server returns
the SOAP response to the Web service connector.
If this is the last handler in the handler chain, Integration Server sends
the SOAP response to the Web service consumer.
Note: Integration Server executes response handler services in the reverse
order in which it executes request handler services.
1 Indicates that the response handler service ended in failure. Integration
Integration Server generates a SOAP fault. The SOAP fault contains the
 Fully qualified name of the response handler service that failed.
If the response handler executed for a consumer Web service descriptor,
Integration Server returns a SOAPFault to the Web service connector.
If the response handler executed for a provider Web service descriptor,
Integration Server returns a SOAP response containing the SOAPFault to
the Web service consumer.


2 or 3 Indicates that the response handler service ended in failure. Integration
 Contents of the faultMessage parameter specified as output for the
response handler service.
If the response handler executed for a consumer Web service descriptor,
If the response handler executed for a provider Web service descriptor,
Note: For a response handler service, status codes 2 and 3 have identical
behavior.
About Fault Handler Services

A fault handler service is used when a SOAP fault occurs during request handler service
processing for a consumer or provider Web service descriptor. Integration Server invokes
a fault handler service if a request handler service failed and returned a status code of 3.
In this situation, Integration Server does not invoke the fault handler service for every
handler in the handler chain. Instead, Integration Server invokes the fault handler service
for each handler that has already executed in the handler chain. Integration Server starts
with the current handler and continues in reverse order until it invokes all the fault
handlers for the executed request handlers in the handler chain.
A fault handler service is sometimes referred to as a handleFault service.
Fault Handler Services and Status Codes

Each fault handler service must return a status code. The status code is an integer from 0–
3, indicates the success or failure of the fault handler service, and indicates how
Integration Server will proceed.The following table describes the meaning of each status
code for a fault handler service and the actions Integration Server takes based on the
status code.


0 Indicates that the fault handler service executed successfully. Integration
Server executes the next handler in the handler chain.
If this is the last handler in the handler chain, Integration Server returns
the SOAPFault to the Web service connector.
If this is the last handler in the handler chain, Integration Server sends a
SOAP response containing the SOAPFault to the Web service consumer.
Note: Integration Server executes fault handler services in the reverse
order in which it executes request handler services.
1 Indicates that the fault handler service ended in failure. Integration
 Fully qualified name of the fault handler service that failed.
If the fault handler executed for a consumer Web service descriptor,
If the fault handler executed for a provider Web service descriptor,


 Contents of the faultMessage output parameter provided by the fault
handler service.
 [ISS.0088.9133] Error while encoding RPC output
 Contains the Java stack trace that occurred when the fault handler
service failed.

Setting Up a Header Handler

To create and implement a header handler, you need to:
 Build the services for handling a request, handling a response, and handling a fault.
Use the pub.soap.handler:handlerSpec specification as the signature for a service that acts
as a header handler.
 Register the combination of those services as a header handler.
 Assign the header handler to the Web service descriptor.
Registering the Handler

To register a handler, you use the pub.soap.handler:registerWmConsumer or
pub.soap.handler:registerWmProvider service. The service you use depends on whether the
handler will be used with consumer Web service descriptors or provider Web service
descriptors, respectively. During registration:
 You provide a logical name for the handler.
 You specify the services for handling a request, a response, and a fault as input.
 You optionally specify the list of QNames on which the handler operates.
Specify QNames only if you want to associate with handler with one or more
QNames. Registering QNames with a handler provides the following benefits:
 Integration Server can perform mustUnderstand checking for the header with the
QName at run time. If a service receives a SOAP message in which a header
requires mustUnderstand processing by the recipient, Integration Server uses the
header QName to locate the handler that processes the header. Note that the
handler must be part of the handler chain for the WSD that contains the service.
 When adding headers to a WSD, Designer and Developer populate the list of IS
document types that can be used as headers in the WSD with the IS document
types whose QNames were registered with the handlers already added to the
WSD. If you add a IS document type as a header to a WSD and the QName of that
IS document type is not associated with a handler, Designer and Developer add
the header but display a warning stating that there is not an associated handler.
 When consuming WSDL to create a provider or consumer WSD, Integration
Server automatically adds a handler to the resulting WSD if the WSDL contains a
QName supported by the handler.
Note: Integration Server stores information about registered header handlers in

memory. Integration Server does not persist registered header handler information
across restarts. Consequently, you must register header handlers each time
Integration Server starts. To accomplish this, create a service that registers a header
handler and make that service a start up service for the package that contains the
services that act as header handlers.

Adding a Handler
Use the following procedure to add a handler to a Web service descriptor.
To add a handler to a Web service descriptor
to add handlers.
2 On the Handler tab, click on the toolbar. Or right-click and select Add Header Handler.
3 Select the registered handler that you want to add to the Web service descriptor.
Once a handler is added to a Web service descriptor, you may optionally add any
headers associated with the handler to the request or response elements of operations
within the Web service descriptor.
Deleting a Handler
You can delete a handler from a Web service descriptor.
To delete a header handler from a Web service descriptor
to add handlers.
2 Click the Handlers tab.
3 Select the handler that you want to delete.
4 Click on the Handlers tab toolbar or right-click and select Delete.

Developer removes the selected handler is deleted from the Handlers tab and from the
Web service descriptor. If the Web service descriptor still contains a header associated
with the deleted handler, Developer displays a warning.
Example: Measuring Elapsed Time with a Consumer Handler

Following is an example of a consumer service handler that measures the elapsed time
between the issuing of a SOAP request message and its response.

1
Consumer handler
2
handleRequest
Web Service Web Service
Consumer 3
Provider
handleResponse
The following table describes the sequence of events.
Step Description
1 A consumer handler containing a handleRequest and handleResponse

implementation is registered and assigned to a consumer WSD.
2 handleRequest invokes the service pub.date:getCurrentDateString to get the time at
which the outgoing request is sent to the Web service provider. handleRequest
then uses soap.handler:setProperty to insert the value into a defined key named
“Time” in the client message context.
3 handleResponse is invoked when the message flow returns to the client side.
During invocation, the service pub.date:getCurrentDateString gets the present time,
and then uses pub.soap.handler:getProperty against the Time key to retrieve the
previously stored value in the message context.
The difference between the two values indicates the approximate time taken to
execute the Web service.


9 WS-Security Facility
 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
 Policy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
 Certificate and Key Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
 Configuring the WS-Security Facility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
 Resolution Order of Certificates and Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
 Certificate Mapping and Usage Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Introduction
This chapter explains Integration Server’s WS-Security implementation. It describes basic
concepts needed to understand the facility, including the settings that comprise a policy,
the XML components, and how policy information is delivered via SOAP message
headers. The chapter also covers the information you need to know about key and
certificate usage, so that the keys, certificates, and trusted roots are correctly configured
for use with the facility.
The chapter details the steps needed to configure WS-Security for Web service providers
and consumers, including the creation, customizing, and selection of a policy file; and
passing security information to a Web services connector.
Lastly, the chapter describes how run-time resolution orders for certificates and keys
work, and how the WS-Security facility uses Integration Server certificate mappings.
Usage of WS-Security Standard

The Integration Server WS-Security facility follows the guidelines of the WS-Security,
version 1.0 standards for:
 SOAP Message Security
 Username Token Profile
 X.509 Certificate Token Profile
The facility implements a subset of the message protection mechanisms for the WS-
Security model described in these specifications, including usage of the UsernameToken
as a means of identifying a requestor and the X.509 Certificate Token authentication
framework.
For more information, refer to the WS-Security specifications at:
 http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-
1.0.pdf
 http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-
1.0.pdf
 http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0.pdf
The SOAP Message Header

The security information for a SOAP message is contained in an optional header
component that follows the SOAP envelope. Its XML semantics and syntax are based on
WS-Security design specifications and recommendations for authentication components
such as signing, encryption, use of authentication tokens, and security timestamps.

The particular combination of these XML authentication components, and their attributes
and settings, constitutes a Web service’s security policy; the SOAP message header is the
“container” for this information.
Securing Data at the Message Level

The WS-Security facility for Integration Server Web services is a message-based
implementation that is designed to provide end-to-end network coverage.
In a transport-based implementation such as HTTPS, credentials and authentication
information secure the endpoints of a connection. However, if the information
transmitted between the endpoints is not contained within a closed network, or the
message traffic is routed through intermediate public nodes, messages may be exposed to
threats such as eavesdropping, unauthorized access, message replay, and parameter
manipulation.
In a message-based implementation, such as one built according to the WS-Security
standard, the security information required to pass information between Web services is
contained within each message header. This design caters to the securing of the message
transmission environment between endpoints. When authentication safeguards such as
signing and encryption are implemented at the individual message level, higher levels of
data protection are possible than when using similar authorization features in a
transport-based security architecture.
Note that the two security architectures are not mutually exclusive. You can design a
solution for your Web services that uses a transport-based security architecture such as
SSL to secure the connection endpoints, along with a message-based, WS-Security
implementation.
Note: The security attributes you assign to a Web service with the Integration Server’s
WS-Security facility do not enable or enforce any of the transport-level security
measures provided by SSL and HTTP authentication.
Message Direction
When configuring message-level security for a Web service, messages must be
categorized as either inbound or outbound. This distinction is important, because
authorization properties can only be applied to messages flowing in one of these
directions.
The authorization properties of an outbound/inbound message pair often share a
dependency. For example, if an outbound message is signed by a Web service, the Web
service receiving the signed message must define the security parameters of an inbound
message so that it can address (for example, verify) signed messages.

Message direction is specified by XML components in the policy file: Rules for inbound
messages are specified within an <InboundSecurity> section, and rules for outbound
messages are specified within an <OutboundSecurity> section. Security elements
specifying username/password, signing, encryption, and all other properties, are
contained within these sections.
For more information and XML code examples specifying message direction, see
“InboundSecurity and OutboundSecurity Elements” on page 127.
Securing Web Service Providers and Consumers

WS-Security is structured around a request-response message exchange model between a
Web service consumer and a Web service provider. As shown in the following figure, the
message exchange is initiated by a Web service consumer requesting a service from a
Web service provider, who processes the request and sends a response to the consumer.
1 2
Outbound Inbound
(consumer) (provider)
SOAP message request
Web Service Web Service

Consumer 4 3 Provider
Inbound Outbound
(consumer) (provider)
SOAP message response
Step Description
1 The Web service consumer constructs an outbound request and sends it to a

Web service provider.
2 The provider receives the inbound request.
3 The provider constructs an outbound response and sends it back to the

consumer.
4 The consumer receives the inbound response from the provider.
When implementing WS-Security, you configure the security settings for a Web service
consumer or provider’s inbound and outbound messages. The following table lists
examples of typical security settings for a Web service consumer and provider.

Web Service Type Outbound Message Inbound Message

Consumer Sends request Receives response
 Include UsernameToken  Decrypt messages
 Use digital signature
 Timestamp message
Provider Sends response Receives request
 Encrypt messages  Authenticate the
UsernameToken
 Verify signature
 Enforce message
expiration
A complete reference of the inbound and outbound security settings for consumers and
providers is available in Appendix B, “WS-Security Policy Reference”.
Types of Message Authentication Supported

Integration Server’s WS-Security facility lets you implement policies for several standard
message-based authentication scenarios:
 Username/password. You can include a UsernameToken in the header of an outbound
message containing the user name and password credentials in plain text. The token
is authenticated by the message recipient if it is found on inbound messages. The
password must be plain text.
Note: The WS-Security facility does not support the use of password digests.
Since the credentials are in plain text, it is recommended that you provide additional
transport-level security such as SSL to secure the endpoints of the connection.
 X.509 Signature Authentication. Allows the use of a private key from an X.509 standard
certificate to sign a document, thus authenticating the identity of the sender to the
receiver. The recipient verifies the signed messages through the matching public key.
 Proprietary X.509 authentication. You can include an X.509 certificate or a reference to an
X.509 certificate as an authentication token in the message header, without any
signing or encryption. This combination of settings supports non-standard X.509
configurations.
Since no signing or encryption is used, you may need to provide additional transport-
level security such as SSL to secure the endpoints of the connection.

In addition to these standard categories of authentication, the flexibility afforded by the

XML policy elements allows for a high degree of customizing. You can assemble and
implement many combinations of authentication options to protect your Web service, as
long as the Web service supports the particular option.
Message Security Options

Following are some of the principal categories of security options available with the
Integration Server WS-Security facility. For more information, see “Policy File Elements”
on page 126.
Signature Options
A signature is a means of authenticating a message so that the recipient is certain of the
sender’s identity and the integrity of the message content. Signing a message involves
encrypting a message digest with the sender’s private key. To verify a signed message,
the recipient uses the public key corresponding to the sender’s private key. Signature
attributes include the following:
 Allow a signature with an expired certificate
 Require the SOAP message body to be signed
 Authenticate the message with the signing certificate
The following signature options are not supported by this implementation of WS-
Security:
 Selecting the algorithm to use in creating the message digest
 Selective or multiple signing of an outbound message
Encryption Options
The WS-Security implementation encrypts SOAP message bodies using the recipient’s
public key. The available encryption options include the following:
 Select an encryption algorithm
 Select a key wrapping algorithm
 Require the SOAP body of inbound messages to be encrypted
The following encryption options are not supported by this implementation of WS-
Security:
 The C14N canonicalization algorithm
 Selective or multiple encryption of an outbound message
 Encrypting outbound messages with a password

Security Timestamps
You can use a Timestamp element that specifies message expiration time, as well as the
precision of the time measurement. This element offers protection against replay attacks,
since inbound messages arriving after the expiration time can be invalidated.
Username and X.509 Certificate Tokens

The facility allows you to use either of two WS-Security standard authentication token
categories for authenticating a Web service:
Username. The Web services consumer supplies a UsernameToken block to identify the
requestor by “username” and a password (text) to authenticate the identity to a Web
services producer. Generally, you should use a Timestamp element specifying message
expiration with the UsernameToken.
X509 Certificate Authentication. A binary token type that represents either a single certificate
or certificate path in X.509 certificate format.
Token References
You can specify handling of certificate information through direct or indirect references:
 In a direct reference, the actual certificate, or a path to the URI specifying a remote
data source containing the token element, is embedded in the SOAP header.
 In an indirect reference, a certificate property, such as the X.509 key identifier, is
embedded in the SOAP header. Using this property value, the recipient extracts the
property value from the message header and uses it to locate the certificate.
Policy Files
A policy file is equivalent to a complete XML Header component of a Web service
descriptor. During WS-Security configuration, a policy file is mapped to a Web service
descriptor file. Each time a message is sent or received by the Web service, the
authentication, signing, and encryption settings specified in the SOAP header are
enabled.
Policy File Components

A complete listing and description of the Integration Server WS-Security facility’s XML
components and attributes is provided in Appendix B, “WS-Security Policy Reference”.
A description of the authentication settings for a typical policy file is shown in “Sample
Policy File” on page 134.

Supplied Policy Files

A number of pre-defined policy files supplied with Integration Server are located in the
Software AG_directory\IntegrationServer\config\policy directory. These policy files
contain the settings for a number of standard security configurations.You can use these
file out of the box, or as templates for creating custom policy files. For more information,
see “List of Supplied WS-Security Policy Files” on page 135.
Certificate and Key Requirements

In a SOAP conversation, there is no mechanism to automatically exchange public keys
(unlike SSL). The consumer and provider Web services have access to or possess copies of
the keys needed to authenticate message requests and responses as dictated by the
specifications of their message policies.
The certificates and keys that are used to enforce a policy assertion are determined jointly
by how WS-Security is configured for the Web service provider or consumer, and the
run-time resolution orders of certificates and keys for policy selections. For more
information, see “Resolution Order of Certificates and Keys” on page 97.
Encrypting and Decrypting Messages

To encrypt outbound messages, a Web service needs:
 A copy of the partner Web service’s public key. The Web service uses the public key to
encrypt outbound messages that it sends to the partner.
To decrypt inbound messages, a Web service needs:
 The private key corresponding to the public key that the partner Web service is using
to encrypt messages.
Signing and Verifying Signed Messages

To sign outbound messages, a Web service needs:
 The private key corresponding to the public key that the partner Web service will use
to verify the signature.
To verify the signature of inbound messages, a Web service needs:
 A copy of the public key, corresponding to the private key that the partner Web
service uses to sign outbound messages.
 If the signing certificate will be validated to ensure that it is signed by a trusted
authority, access to the certificate file containing the trusted root of the signing CA
(trusted authority directory).

Configuring the WS-Security Facility

The following sections provide step-by-step instructions for configuring WS-Security on
IS Web service providers and consumers.
Prerequisites
Several prerequisites are necessary before beginning the WS-Security configuration
process:
 Make sure that the following applications have been started and are running:
 The Integration Server hosting the Web service for which you are configuring WS-
Security.
 An instance of Developer.
 Certificate files for the Web service provider or consumer must exist.
You will need to specify the locations of these certificate files during the configuration
process. The certificate files contain the signed certificate (or chain of certificates), and
the trusted authority directory contains the trusted roots of the certificate signing
authority. For more information, see “Certificate and Key Requirements” on page 92,
“Resolution Order of Certificates and Keys” on page 97 and “Certificate Mapping
and Usage Settings” on page 98.
 Verify that the security policy you want to enforce is already specified in an XML
policy file.
Integration Server provides several “out-of-the-box” policies for coverage of typical
message-based security situations. In most cases, you will be able to use one of these
policy files as is.
If your security needs require the creation of a custom policy file, you can do so by
copying one of the supplied XML policy files and editing the copy. Make sure to give
the copied file a unique ID (see “Sample Policy File” on page 134 for more
information).
Step Summary
Following is a summary of the step sequence to follow when configuring WS-Security:
Title Description
“Specifying the WS-Security Verify the existence and location of the XML
Policy File” policy file.
“Assigning a Security Policy to a Using Developer, specify the XML policy file and
Web Service Descriptor” assign it to a Web service descriptor.

Title Description
Creating a Consumer Web Service Configure an endpoint alias for a consumer Web
Endpoint Alias service descriptor
- OR - - OR -
Creating a Provider Web Service Configure an endpoint alias for a provider Web
Endpoint Alias service descriptor
Note: For details about creating a consumer or

provider Web service endpoint alias, see
Administering webMethods Integration Server.
“Assigning a Web Service The set of properties associated with the alias
Endpoint Alias to a Binder” on must be linked to a Web services descriptor
page 67
“Passing Security Information into Note: This item is an alternate to WS endpoint
a WS Connector” alias configuration for the WSC.
Integration Server uses the information from the

Web services connector to build the WS-Security
header and the SOAP message request
Specifying the WS-Security Policy File

Verify that the XML policy file contains the settings you want and is located in the proper
directory. WS-Security policy files must be placed in the following folder on the machine
hosting Integration Server:
Software AG_directory\IntegrationServer\config\policy
Assigning a Security Policy to a Web Service Descriptor

The following sequence of steps uses Developer to add a header handler to the Web
service descriptor.
To assigning a WS-Security policy to a Web service descriptor
1 In the Navigation panel, locate and open and lock the Web service descriptor for
which you want to configure the WS-Security policy.
2 In the Web service descriptor editor, on the Handlers tab, use one of the following
mechanisms for adding a header handler:
 Click click on the toolbar. Or right-click and select Add Header Handler. A list of
available header handlers appears. Select WS Security Handler and click OK.

 Right-click in the Handlers tab and click Add Header Handler on the pop-up menu.
A dialog box appears with a list of available header handlers. Select WS Security
Handler and click OK.
 Cut or copy an existing WS-Security handler using Developer.
3 In the Properties panel, select the policy name that you want to associate with the
WS-Security handler.
Developer sets the value of the Effective policy name property to match the selected
policy name.
Note: Developer sets the value of the effective policy name to match policyName
the first time only that a policy name is specified. If you later change the policy
name, Developer does not automatically update the effective policy name. If you
want the effective policy name to match the new policy name, you must specify
the new policy in the Effective policy property.
4 Save the Web service descriptor.
Important! The order of handlers is important. For provider Web service descriptors, it
is recommended that the WS-Security handler be the first handler listed. For
consumer Web service descriptors, it is recommended that the WS-Security handler
be the last handler listed.
Passing Security Information into a WS Connector

The following procedure describes the steps a user takes to pass security information
directly into a Web service connector (WSC). At run-time, Integration Server uses the
information to build the WS-Security header and the SOAP message request.
To pass security information into a WSC
1 Start Developer.
2 Open and lock the service that invokes the WSC.
3 If the SOAP message request requires credentials for a UsernameToken, do the
following in the pipeline for the WSC:
a Map or set the value of auth/message/user to the user name used to authenticate
the consumer client on the Web services host.
b Map or set the value of auth/message/pass to the password used to authenticate
the consumer client on the Web services host.

4 If the SOAP message request needs to be signed, set the following fields in the WSC:
In this field... Specify
auth/message/serverCerts/keyStoreAlias Alias to the keystore that contains the

private key used to sign outbound SOAP
requests.
auth/message/serverCerts/keyAlias Alias to the private key used to sign and/or
include X.509 authentication token for
outbound SOAP messages and/or decrypt
inbound SOAP responses. The key must be
in the keystore specified in
auth/message/serverCerts/keyStoreAlias
Note: The method you use to fetch these credentials depends upon their location at
your site. If they are stored in the file system, you can retrieve them using the
pub.file:getFile service. If they are stored in a special repository or a DBMS,
you may need a custom service for their retrieval.
5 If the SOAP message request requires encryption, set the following field:
auth/message/partnerCert The path and file name of the provider’s

certificate, which contains its public key.
6 If the SOAP message response needs to be verified, do the following:
auth/message/partnerCert The path and file name of the provider’s certificate,

which contains its public key.
7 If the SOAP message must be decrypted, do the following:
auth/message/serverCerts/keyStoreAlias Alias to the keystore that contains the

private key that the consumer will use to
decrypt the SOAP response.
auth/message/serverCerts/keyAlias Alias to the private key used to decrypt
inbound SOAP responses. The key must be
in the keystore specified in
auth/message/serverCerts/keyStoreAlias

Resolution Order of Certificates and Keys

The WS-Security facility allows you to configure a Web service to select which certificates
and keys to use at run time. This capability allows you to design and implement a variety
of security configurations for Web service providers and consumers, and modify them
without having to change their policy files.
When an outbound message is sent or an inbound message received, and a policy
assertion invoked, a search for a certificate or key is initiated. The search follows a fixed
sequence based on the type of policy assertion, whether the Web service is a provider or
consumer, and a number of other factors (see “Locating Certificates and Keys” and
“Search Order”, following). Once a certificate or key is found the search ends. The
process is repeated for each policy assertion/attribute/value setting within a message that
requires certificate or key resolution. When the next message is sent or received, the
process begins again and repeats for each outgoing or incoming message.
The WS-Security facility maintains lists of resolution orders that specify where to search
for certificates and keys for every possible policy/attribute/value combination. The topics
below describe this process and explain how the different resolution orders work.
Locating Certificates and Keys

At run time, the Web service resolves the locations of the certificates and keys it needs for
policy assertions by initiating a series of searches. The locations searched depend upon
factors such as:
 Whether the Web service is a provider or consumer
 Which policy assertion (for example, signing or encryption) needs the key or
certificate
 Whether the policy assertion is for an inbound or outbound message
 The policy attributes (for example, Validate Signing Certificate) and their settings
Search Order
The search order for certificates and keys is different for Web service providers and
consumers.
For consumers, the search order is as follows:
1 Passed in through generated WSC (Web service connector)
2 Specified in the Web service’s endpoint alias
3 Specified in the Integration Server settings
4 From the WS-Security message header

For providers, the search order is as follows:

1 Specified in the Web service’s endpoint alias
2 Specified in the Listener (ports) settings
3 Specified in the Integration Server settings
4 From the WS-Security message header
5 From an Integration Server certificate mapping (see “Certificate Mapping and Usage
Settings” on page 98)
Once the certificate or key is found, the search ends. The resolved key or certificate loads
and is used for the policy assertion.
For more information regarding resolution order, see Appendix A, “WS-Security Key
Usage Reference”. A more detailed reference of the certificate and key resolution order
for policy assertions and attributes is provided in Appendix C, “WS-Security: Detailed
Usage and Resolution Order for Certificates and Keys”.
Certificate Mapping and Usage Settings

Integration Server supports the mapping of a client certificate with a user ID (User) and
the certificate’s Usage (for more information, see Administering webMethods Integration
Server).
For example, a certificate located at “c:\certs\certfile.der” may be mapped to a Usage of
“VerifyAndEncrypt” and the User name “Developer”. Whenever User “Developer” is
resolved as an authenticated user to be used for certificate mapping, then Integration
Server uses the mapped certificate for encrypting the provider’s response.
At run time, a Web service provider may use the information in a certificate mapping. For
more information, see Appendix C, “WS-Security: Detailed Usage and Resolution Order
for Certificates and Keys”.
Certificate Mapping: User Resolution Order

WS-Security maintains a resolution order for the User setting when searching through
Integration Server certificate mappings:
1 User associated with the certificate that is used for authentication (X.509 token or
signature token)
2 User specified in a WS-Security UsernameToken (not in a certificate)
3 User authenticated at the transport level (SSL or HTTP)

Certificate Mapping: Usage Resolution Order

The following table lists the order for matching a requested Usage by a policy assertion
against the Usage value in a certificate mapping.
If this Usage is requested... A mapping with the first of these Usage values is returned...
Verify Verify, VerifyAndEncrypt, SSL
Encrypt Encrypt, VerifyAndEncrypt, SSL
VerifyAndEncrypt VerifyAndEncrypt, SSL
MessageAuth MessageAuth, SSL
SSLAuth SSL


10 Authentication and Authorization for Web Service
Descriptors
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
 Authentication and Authorization for Consumer Web Service Descriptors . . . . . . . . . . . . . . . . . 102
 Authentication and Authorization for Provider Web Service Descriptors . . . . . . . . . . . . . . . . . . . 104

10 Authentication and Authorization for Web Service Descriptors
Introduction
At specific points in the execution of a Web service descriptor, Integration Server
performs authentication and authorization to verify that the user has permission to
execute the Web service descriptor or one of its associated services. For the Web service
descriptor and its associated services, this can include checking the execute ACL assigned
to the descriptor or service.
 On the consumer and provider sides, Integration Server always performs ACL
checking for the Web service descriptor.
 On the consumer side, Integration Server performs ACL checking for the Web service
connector if the connector is a top-level service (one that is invoked directly by a
user). If another service invokes the Web service connector, Integration Server
performs ACL checking only if the Enforce execute ACL option for the Web service
connector is set to Always.
Integration Server performs ACL checking for handler services, if the service has
permissions configured such that the Enforce execute ACL option is set to Always.
 On the provider side, Integration Server performs ACL checking for handler services,
endpoint service, or any services called by the endpoint only if the service has
permissions configured such that the Enforce execute ACL option is set to Always.
Authentication and Authorization for Consumer Web Service

Descriptors
When Integration Server acts as the Web service consumer, Integration Server authorizes
the user by performing ACL checking for the consumer Web service descriptor.
Integration Server may perform authorization at other points by performing ACL
checking for the Web service connector and handler services. The following table
summarizes the points at which Integration Server performs authorization and indicates
when Integration Server executes the services used with a consumer Web service
descriptor.
Note: On the consumer side, Integration Server performs ACL checking with the
credentials used to connect to the Integration Server. The transport and message
credentials passed into the Web service connector or specified in the consumer web
service endpoint alias are used only when sending the SOAP request to the provider.

Step Description
1 Authorization check for the Web service connector.
Integration Server determines whether the user is authorized to invoke the Web
service connector by checking the user credentials against the execute ACL
assigned to the Web service connector.
 If the Web service connector is the top-level service, Integration Server
performs ACL checking for the Web service connector.
 If the Web service connector is not the top-level service, Integration Server
performs ACL checking for the Web service connector only if the Web
service connector permissions specify that the Enforce execute ACL option is
set to Always.
If access is denied, Integration Server does not continue to the next steps and
the Web service connector fails.
2 Authorization check for the consumer Web service descriptor.
Integration Server determines whether the user is authorized to access the Web
service descriptor by checking the user credentials against the execute ACL
assigned to the Web service descriptor.
If access is denied, Integration Server does not continue to the next steps and
the Web service connector fails.
3 Authorization check for all handler services.
Integration Server determines whether the user is authorized to access the
handler services by performing ACL checking. Integration Server checks the
execute ACL for a handler service only if the handler service permissions
specify that the Enforce execute ACL option is set to Always. Integration Server
does not consider handler services to be top-level services.
If access is denied to any of the handler services, Integration Server does not
continue to the next steps and the Web service connector fails.
Note: Note that Integration Server performs ACL checking for all request,
response, and fault handler service at this point in the process.
4 Request handler services execute.
Integration Server executes the request handler services in the handler chain.
For more information, see “About Request Handler Services” on page 73.
5 Send SOAP Request
Integration Server sends the SOAP request to the Web service provider.
6 Response handler services execute.
Integration Server receives the SOAP response and executes the response
handler services in the handler chain. For more information, see “About
Response Handler Services” on page 76.

ACL Checking Scenarios for Consumer Web Service Descriptors

The following table identifies the various combinations of the ACL checking results for a
consumer Web service descriptor and its handler services.
Note: Note that the following table assumes that the user-supplied credentials passed the
ACL check for the Web service connector. If the user-supplied credentials did not pass
the ACL check, Integration Server does not perform ACL checking for the consumer Web
service descriptor or its handler services.
WSD ACL Handler SOAP Fault Exception

Result ACL Result Returned? Thrown? Behavior
Pass Pass NA NA Integration Server executes the

request handler services.
Pass Fail No Yes Integration Server returns a SOAP
fault with the message:
[ISS.0088.9433] Access denied to
Handler Service
<handlerServiceName> in the
Handler Chain
Fail NA Yes No Integration Server returns a SOAP
fault with the message
[ISS.0088.9164] Access to
WSDescriptor
<webServiceDescriptorName>
denied.
Authentication and Authorization for Provider Web Service

Descriptors
When Integration Server acts as the Web service provider, Integration Server
authenticates the user when it receives a Web service request. Integration Server
performs authorization by checking the execute ACL for the provider Web service
descriptor and, if necessary, for the handler services and endpoint service. Integration
Server performs these tasks using the credentials of the effective user. The identity of the
effective user begins as Anonymous, but may be supplanted by transport-level
credentials or message-level credentials.
Within the context of authentication and authorization for provider Web service
descriptors, the terms below have the specified definitions:
 Transport-level credentials. The credentials present within the transport layer. For
example, the userid and password in the HTTP headers are considered transport-
level credentials.

 Message-level credentials. The WS-Security credentials present inside the actual SOAP
message as contained within the WS -Security SOAP headers. The use of message-
level credentials for authorization purposes is only possible if the WS Security
handler is engaged for the Web service descriptor.
 Effective user. The user identity that is currently being used for purposes of
authorization. The effective user identity begins as Anonymous and may be replaced
subsequently by a user identity from the transport-level credentials or the message-
level credentials.
 Authentication. The act of validating a set of credentials to verify the identity of a user.
For example, authentication may involve checking the validity of a provided
userid/password combination or checking the validity of an X509 certificate or its
expiration. After the user is authenticated, the user identity becomes the “effective
user”.
 Authorization. The act of determining whether a given user identity is allowed to access
a particular resource.
The following table summarizes the processing points at which Integration Server
performs authentication and authorization and indicates when Integration Server
executes the services used with a provider Web service descriptor.
Step Description
1 Transport-level authentication.
When Integration Server receives an inbound Web service request, the
transport mechanism authenticates the transport-level credentials.
 If the transport-level credentials were supplied and successfully
authenticated, the user associated with the transport-level credentials
becomes the effective user. Processing continues to step 2, Authorization
check for all handler services.
 If the transport-level credentials were supplied and are invalid, the
transport mechanism rejects the Web service request and no further
processing occurs.
 If no transport-level credentials were provided, the effective user is set to
Anonymous and processing continues to step 2, Authorization check for all
handler services.

Step Description
2 Authorization check for all handler services.
handler services by performing ACL checking. Integration Server performs
ACL checking for a handler service only if the handler service permissions
specify that the Enforce execute ACL option is set to Always. Integration Server
does not consider handler services to be top-level services.
Integration Server uses the credentials of the effective user when performing
ACL checking for handler services. If access is denied to any of the handler
services, Integration Server processing does not continue.
Note: Note that Integration Server performs ACL checking for all request,
response, and fault handler service at this point.
3 Request handler services execute.
Integration Server takes the SOAP request from the consumer and executes
the request handler services in the handler chain. For more information, see
“About Request Handler Services” on page 73.
If the WS Security handler is not engaged for the provider Web service
descriptor, processing continues with step 4, Authorization check for the provider
Web service descriptor.
If the WS Security handler is engaged for the provider Web service
descriptor, Integration Server authenticates the message-level credentials.
 If authentication succeeds, Integration Server extracts the message-level
credentials. The user associated with the message-level credentials
becomes the effective user. Processing continues with step 4, Authorization
check for the provider Web service descriptor.
 If authentication fails for the message-level credentials, Integration Server
rejects the request and processing skips to step 7, Response handler services
execute.
4 Authorization check for the provider Web service descriptor.
Web service descriptor by checking the credentials of the effective user
against the execute ACL assigned to the Web service descriptor.
 If access is granted, processing continues with step 5, Authorization check
for the endpoint service.
 If access is denied, Integration Server adds a SOAPFault to the SOAP
response and skips to 7, Response handler services execute.

Step Description
5 Authorization check for the endpoint service.
endpoint service by performing ACL checking.
Integration Server performs ACL checking for an endpoint service only when
the service permissions specify that the Enforce execute ACL option is set to
Always. Integration Server does not consider an endpoint service to be a top-
level service.
If Integration Server performs ACL checking for the endpoint service,
Integration Server uses the credentials of the effective user.
 If access is granted, processing continues to step 6, Endpoint service
executes.
 If access is denied, Integration Server adds a SOAPFault to the SOAP
response and skips to step 7, Response handler services execute.
6 Endpoint service executes.
Integration Server executes the endpoint service.
 If service execution succeeds, Integration Server converts the response
from the endpoint service to a SOAP response and processing continues
to step 7, Response handler services execute.
 If service execution fails, Integration Server converts the failure to a
SOAPFault and places it in the SOAP response. Processing continues to
step 7, Response handler services execute.
7 Response handler services execute.
Integration Server takes the SOAP response produced by the endpoint
service and begins to execute the response handler services in the handler
chain. For more information, see “About Response Handler Services” on
page 76.
ACL Checking Scenarios for Provider Web Service Descriptors

The following tables identify the various combinations of the ACL checking results for a
providerWeb service descriptor and its handler services.
Transport Handler Request Message WSD SOAP Response

Credentials ACL Handler Credentials ACL Fault Handler
Provided? Result Executes? Provided? Result Returned? Executes? Behavior
No Pass Yes No Pass NA Yes 1

No Pass Yes Yes Pass NA Yes 1
Yes Pass Yes No Pass NA Yes 1

Transport Handler Request Message WSD SOAP Response

Credentials ACL Handler Credentials ACL Fault Handler
Provided? Result Executes? Provided? Result Returned? Executes? Behavior
Yes Pass Yes Yes Pass NA Yes 1

No Pass Yes No Fail Yes Yes 2
No Pass Yes Yes Fail Yes Yes 3
Yes Pass Yes No Fail Yes Yes 3
Yes Pass Yes Yes Fail Yes Yes 3
No Fail No NA NA Yes No 4
Yes Fail No NA NA Yes No 5
Behavior Description
1 Endpoint service executes.

2 Integration Server returns the following:
 An HTTP response status code of 401
 A SOAP fault with the message [ISS.0088.9164] Access to WSDescriptor
<webServiceDescriptorName> denied.
 A SOAP fault with the message [ISS.0088.9164] Access to WSDescriptor
<webServiceDescriptorName> denied.
 A SOAP fault with the message [ISS.0088.9433] Access denied to
Handler Service <handlerService>
5 Integration Server does the following:
 A SOAP fault with the message [ISS.0088.9433] Access denied to
Handler Service <handlerService>

11 Publishing IS Services to a UDDI Registry as a Web
Service
 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
 Publishing a Service to the UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
 Removing a Service from UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
 Browsing for Web Services in UDDI Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

11 Publishing IS Services to a UDDI Registry as a Web Service
Introduction
This chapter provides information about using webMethods Developer to connect to a
UDDI Registry and view or publish Web services.
Important! Developer only supports UDDI v3; it will not connect to a registry based on
earlier versions of UDDI.
What Is a UDDI Registry?

A UDDI Registry (Universal Description, Discovery, and Integration) is an XML-based
registry for businesses worldwide to list themselves on the Internet. It allows users to
view, find, and share Web services.
When working with a UDDI Registry from Developer you can:
 Discover the Web services published in a UDDI Registry. Developer displays a list of the
Web services that are published in a UDDI Registry. By default, Developer displays
all published services, but you can use a filter to limit the number of services shown.
 Incorporate a Web service into Integration Server. You can incorporate a Web service in the
UDDI Registry into your integration solution by creating a consumer Web service
descriptor from the Web service. Developer automatically generates a Web service
connector for each operation in the Web service, which can be invoked in the same
way as any other IS service. For more information, see “Invoking a Web Service” on
page 37.
 Publish services to a UDDI Registry. You can make a service that resides on Integration
Server (such as a flow service, Java service, C service, or adapter service) available as
an operation of a Web service and then publish the Web service to a UDDI Registry.
Requirements
To use Developer to publish or browse Web services in a UDDI Registry, you must have
the following:
 webMethods Developer 7.1
 webMethods Integration Server 7.1
 A valid UDDI v3 registry account, configured with the proper permissions to
perform UDDI activities

Connecting to a UDDI Registry

To use Developer to view or publish Web services, you must first connect to a UDDI
Registry (UDDI Version 3 is required). The specified UDDI v3 registry must contain at
least one business entity. A business entity is a logical grouping of Web services, used to
represent businesses and providers within UDDI. Each Web service must be published
within a business entity.
Note: You can only connect to one UDDI Registry at a time from Developer. To
connect to another UDDI Registry, you must first disconnect from the existing
session.
To connect to UDDI Registry
1 Start Developer.
2 Select Session > Open UDDI Registry session or click on the UDDI Registry tab.
3 In the Open UDDI Registry Session dialog box, complete the following fields as
appropriate:
To... Select...
Connect to the URL configured for browsing the UDDI Inquiry URL
registry. This field is mandatory.
Connect to the security URL for the UDDI registry. This field Security URL
can be mandatory or optional, depending on the registry.
Connect to the URL configured for publishing services to the Publish URL
UDDI registry. This field is optional.
Note: You can log in to the UDDI v3 registry in inquiry

(browse) mode only. When a “browsing” user attempts to
publish a Web service descriptor to the UDDI registry, the
user must specify a Publish URL and login credentials.
Note: Developer saves URLs that were used previously for successful connections
and lists the one that provided the “last good connection” first.
4 Enter your UDDI user ID and password.

5 Click OK. The UDDI Registry tab displays a hierarchical view of all the business entities
registered to that UDDI registry and the Web services each has published.
Important! If you want to reduce the number of services displayed in the UDDI Registry
tab, try defining a filter. See “Applying a Filter to UDDI Registry” on page 118 for
instructions.

Refreshing a UDDI Registry Session

Developer automatically refreshes the UDDI Registry tab when you create a Web service,
except in the following circumstances:
In this circumstance... Do this...
When other users add or delete Web services Refresh the UDDI Registry as
from the UDDI Registry described below.
When Developer loses its connection to a UDDI Refresh the UDDI Registry as
Registry described below.
If the registry operates with some form of Refresh the UDDI Registry as
governance and a newly added Web service described below.
does not appear immediately
If you are alerted with a message stating that a Clear the filter, as described in
newly-created service does not meet with the “Clearing an Applied Filter” on
currently applied filter criteria page 119.
Use the following procedure to refresh the display.
To refresh the UDDI Registry session
Select Session > Refresh UDDI Registry display or click on the UDDI Registry tab.
Disconnecting from a UDDI Registry

Use the following procedure to refresh the display and disconnect from UDDI Registry.
To disconnect from the UDDI Registry
Select Session > Close UDDI Registry session or click on the UDDI Registry tab.

Viewing a UDDI Registry in Developer

In Developer, the UDDI Registry tab displays the Web services published in the UDDI
Registry to which you are connected. The UDDI Registry tab is located below the
Navigation panel.
On the UDDI Registry tab, Web services are sorted in alphabetical order. Select a Web
service to view more information about the service.
Working with a UDDI Registry in Developer
UDDI Registry
tab
Note: When you select a Web service in the UDDI Registry tab, the Properties panel
displays the properties of the Web service you selected, but the editor (the middle
area of the Developer window between the Navigation and the Properties panels)
does not change. It still displays details for the service selected in the Navigation
panel. This is because Web service details and logic for a UDDI Registry service
cannot be modified using Developer.

UDDI Registry Tab Icons

The UDDI Registry tab contains icons that represent the UDDI Registry and the Web
services that are published within UDDI Registry. The following table identifies these
icons.
This icon... Represents...

A UDDI Registry Node. Below the UDDI Registry name, Developer displays
all of the business entities registered in that UDDI Registry. As part of
the UDDI Registry name, Developer displays URL of the UDDI Registry
registry to which you are connected.
A Business Entity. A business entity is a publisher of Web services to the
UDDI Registry. Below the business entity name, Developer displays the
Web services published by that entity.
Note: Infravio X-Registry users can view only business services that
belong to them or to which they have been granted explicit “view”
permissions, unless the user has Administrator permissions. Business
services that do not belong to the user will be listed under the Unknown
Business entities for read-only purposes. This is a registry limitation and
applies to Infravio only.
A Web Service. A Web service is a service that uses specific XML- based
protocols and interface descriptions to communicate. It represents an
endpoint that hosts an actual service. Using Developer, you can create a
consumer Web service descriptor and connector(s) from a Web service
and then invoke the connector to run the Web service remotely. From an
existing IS service or WSDL, you can create a provider Web service
descriptor and publish it to a UDDI Registry, so that the IS service it
describes can be invoked by an external user.
Note: You cannot modify any of these elements (registry node, business entity, or Web
service) using Developer. The only way to manipulate the UDDI registry is by
registering new Web services, deleting existing registrations, and by using registered
Web services as the basis for generating an Integration Server Web service descriptor.

UDDI Registry Toolbar

The following buttons on the UDDI Registry tab toolbar are shortcuts to frequently-used
commands.
Use this
button... To...
Connect to a UDDI Registry session while working in Developer
(equivalent to Session > Open UDDI Registry).
Disconnect from a UDDI Registry session while working in Developer
(equivalent to Session > Close UDDI Registry).
Refresh the display of Web services (equivalent to Session > Refresh
UDDI Registry).
Create an expression that filters the contents of the UDDI Registry tab
based on the value of a Web service property.
Remove the filter from the contents of the UDDI Registry tab and
display all the published Web services.
Web Service Properties

Web service properties are read-only because Developer cannot directly edit Web
services that are published to the UDDI Registry. When you select a Web service in the
UDDI Registry tab, Developer displays the following set of properties in the Properties
panel.
Property Description
Service name Name of the Web service.

Description Description of the Web service.
Service Key Universally unique identifier of the UDDI businessService entry
that corresponds to this Web service in the UDDI Registry.
Access Point Network address where the Web service can be invoked.
Overview URL URL of the OverviewDoc, which contains additional information
about this Web service.
Category Bag A list of other properties defined for the Web service using the
Model entity keys.
Important! When you select a Web service in the UDDI Registry tab, the editor (the
middle area of the Developer window between the Navigation and Properties panels)
does not change. This is because a Web service’s details and logic cannot be modified
by Developer.

Publishing a Service to the UDDI Registry

For a service (flow, Java, C, adapter) to be available as a Web service through a UDDI
Registry, you must first create an IS Web service and then publish that Web service to the
UDDI Registry.
When you use Developer to publish a Web service to a UDDI Registry, the Integration
Server creates a WSDL file and adds it to the registry. The WSDL describes the
information a Web service consumer needs to send data to, invoke, and receive data from
a Web service. This information includes the operations the service performs, location of
the service, the protocol required to invoke the service, and required input and output
parameters.
Keep the following points in mind when you publish a service to a UDDI Registry using
Developer:
 Only provider Web service descriptors are published to UDDI using Developer.
 The following SOAP style and use combinations are supported for provider Web
service descriptors:
 Document/Literal
 RPC/Literal
 RPC/Encoded
Tip! You can publish a service by creating a provider Web service descriptor for the
service and dragging it directly from the Navigation panel to the UDDI Registry tab.
The service will be published in the UDDI Registry with the following characteristics:
 SOAP 1.1 as the protocol
 SOAP Document/Literal as the style and use
 http://host:port as the as the address of the web service
To publish a service to a UDDI Registry
Tip! To automatically publish a service to a UDDI Registry, drag the provider Web
service descriptor for the IS service from the Navigation panel to your business entity
folder on the UDDI Registry.
1 If you have not already done so, create a provider Web service descriptor using the IS
service as an operation of the Web service (as described in “Creating a Service First
Provider WSD” on page 20).
2 From the UDDI Registry tab, connect to the UDDI Registry in which you want to
publish the Web service (as described in “Connecting to a UDDI Registry” on
page 111).

3 In the Navigation panel, select the provider Web service descriptor for the IS service
you want to publish and click Publish to UDDI Registry from the Tools menu (or from the
right-click menu). Developer opens the Select Business Entity dialog box.
4 Type a name and description for the service and select the business entity in which to
create the Web service.
Note: Infravio X-Registry users can view only business services that belong to
them or to which they have been granted explicit “view” permissions, unless the
user has Administrator permissions. Business services that do not belong to the
user will be listed under the Unknown Business entities for read-only purposes.
This is a registry limitation and applies to Infravio only.
5 Click OK. Developer publishes the service to the UDDI Registry.

6 If the published service is not immediately displayed in the UDDI Registry tab, select
Session > Refresh UDDI Registry display or click on the UDDI Registry tab. Governance
policies established in the registry may delay the display of the web service.
Note: If Developer cannot display the service you just published in the UDDI
Registry tab because of the filter setting, it will display a message stating so. Clear
the filter by clicking on the UDDI Registry tab or by selecting Clear UDDI Filter
from the right-click menu.
Important! If you publish the same Web service descriptor to a registry twice (without
first deleting the original version), two Web services will exist with the same name in
the registry. However, the Service Key property values will be different for these two
services. If you cannot determine which version is the newest, delete both Web
services from the UDDI Registry tab and re-publish the new version.
Removing a Service from UDDI Registry

Perform the following steps to remove a Web service from a UDDI Registry. When you
remove a Web service, the IS service and its associated Web service descriptor still exist
on the Integration Server but the Web service is no longer published to the UDDI
Registry.
To remove a Web service from UDDI Registry
1 Click on the UDDI Registry tab to connect to the UDDI Registry from which you
want to remove a service.
2 In the UDDI Registry tab, select the service you want to remove and click , or select
Delete Web Service from the right-click menu.
Note: You cannot delete a Web service from another business’ folder in the
registry. The Delete Web Service option will be disabled.

Browsing for Web Services in UDDI Registry

After you connect to a UDDI Registry, you can browse for Web services that you would
like to incorporate into your integration solution. You can discover Web services by
scrolling through the UDDI Registry tab. By default, the UDDI Registry tab displays all
services published in the UDDI Registry.
To help find a particular Web service, you can reduce the number of displayed Web
services by filtering the contents of the UDDI Registry tab based on the value of a specified
Web service property.
Applying a Filter to UDDI Registry

Perform these steps to create and apply a filter to the contents of the UDDI Registry tab.
To filter the contents of the UDDI Registry tab
1 Click on the UDDI Registry tab, or put your cursor anywhere in the UDDI Registry
area and select Filter UDDI Registry display from the right-click menu.
2 In the Filter on field, type the text to use as the filter criteria.
The text is treated as a partial string. For example, if you enter “vic”, “victory” and
“services” will both fit the search criteria. The percent sign (%) can be used for an
approximate search within the text. For example, for “a%n”, “ain”, “Amazon”, and
“American” all fit the search criteria.
3 Under Text to match select the check boxes for Service name, Service description, or both
to specify which properties you want Developer to examine for the Filter on text
string.
4 Click Apply to apply the filter.
If you click Apply, the Filter UDDI Registry Display dialog box remains open. Click OK
if you want to apply the filter and close the Filter UDDI Registry Display dialog box.
Notes:
 Developer continues to apply the specified filter until you explicitly clear the filter.
Developer saves the filter string across Developer and UDDI Registry sessions.
 When the button on the UDDI Registry tab is active, it indicates that Developer is
using a filter to limit the displayed Web services.
 If you publish a service that does not meet the criteria specified in the currently
applied filter, Developer does not display the newly published Web service in the
UDDI Registry tab.

 Developer applies each filter that you create to the entire contents of the UDDI
Registry. For example, if you apply two filters in succession, Developer clears the first
filter before applying the second filter. Developer does not apply the second filter to
the results of the first filter.
Clearing an Applied Filter

Developer continues to use a filter to limit the contents of the UDDI Registry tab until you
explicitly remove the filter. The following procedure explains how to remove a filter.
To clear a filter
Click on the UDDI Registry tab, if it is enabled, or put your cursor anywhere in the
UDDI Registry area and select Clear UDDI Filter from the right-click menu.
Developer removes the filter and displays all the published Web services in the UDDI
Registry.


A WS-Security Key Usage Reference
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
 WS-Security Key Resolution Order: Web Services Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . 122
 WS-Security Key Resolution Order: Web Services Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Introduction
This appendix describes the WS-Security facility’s key usage order when multiple private
or public keys are available to a Web service. The appendix lists the key usage order for
combinations of several parameters:
 Consumers vs. provider
 Request vs. response message
 Security setting (sign, verify, encrypt, decrypt)
WS-Security Key Resolution Order: Web Services Consumer

The following table lists the key resolution order for a Web services consumer’s request
and response messages when the indicated security settings are enabled.
Security Setting Request Message Response Message

Sign 1 Private key passed in to
WSC signature
2 Private key specified in
WS endpoint alias
the Server Settings
Encrypt 1 Public key passed in to
WSC signature
2 Public key specified in
WS endpoint alias
Verify 1 Public key in message.
header
2 Public key passed in to
WSC signature
3 Public key specified in
WS endpoint alias
Decrypt 1 Private key passed in to
WSC signature
WS endpoint alias
the Server Settings

WS-Security Key Resolution Order: Web Services Provider

The following table lists the key resolution order for a Web services provider’s request
and response messages when the indicated security settings are enabled.
Security Setting Request Message Response Message

Sign 1 Private key specified in
WS endpoint alias
the HTTPS listener port
the Server Settings
Encrypt 1 Public key from certificate
mapping
2 Public key in request
message header
Verify 1 Public key in message
header
2 Public key from certificate
mapping
Decrypt 1 Private key in WS
endpoint alias
the HTTPS listener port
the Server Settings


B WS-Security Policy Reference
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
 Policy File Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
 Sample Policy File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
 List of Supplied WS-Security Policy Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Introduction
This appendix contains reference information for WS-Security policy files. The appendix
describes the XML elements, attributes, and settings. A sample XML policy file
explaining commonly-used security components and attributes is provided. In addition,
the appendix lists the complete set of policy files included with Integration Server.
Policy File Elements

The following table describes the XML elements of a WS-Security policy document.
Element Description
<Policy> Specifies the policy namespace and the unique identifier of
the policy.
<SecurityPolicy> Contains the elements that describe a WS-Security policy.
<InboundSecurity> Indicates whether the security and authentication
-OR- information is for an inbound message or an outbound
<OutboundSecurity>
message from the Web service.
<Timestamp> Generates a timestamp that enforces message expiration.
<UsernameToken> Includes a WS-Security UsernameToken for authentication.
<Signature> Specifies use of a digital signature.
<Encryption> Specifies encryption of the SOAP message body.
<X509Authentication> Include a WS-Security X.509 Certificate token reference for
authentication.
Policy Element
The <Policy> element contains two attributes: the namespace for WS-Security policy files,
and an identifier for the policy specification. The identifier must be specified by the
policy file writer or author and must be unique.
Example:
<Policy xmlns=”http://www.webmethods.com/2007/07/policy”
Id=”Confidential File Policy A”>
SecurityPolicy Element
The <SecurityPolicy> element contains all of the elements that specify the policy’s
security settings.

Example:
<SecurityPolicy xmlns=”http://www.webmethods.com/2007/07/policy/security”>
InboundSecurity and OutboundSecurity Elements

The differences in the authentication requirements for incoming vs. outgoing messages
(message direction) or a Web service are covered by specifying their properties within
separate XML sections, labeled <InboundSecurity> and <OutboundSecurity>,
respectively.
<InboundSecurity>
. . .
</InboundSecurity>
<OutboundSecurity>
. . .
</OutboundSecurity>
Setting a Policy Element’s Usage Attribute

The “Usage” attribute applies to any policy element in an <InboundSecurity> section to
explicitly indicate how the element should be treated.
Usage Value Description

Optional If the element is present, it will be processed. Absence of the
policy element will not result in an error being generated.
Required The element must be present or processing will fail with an
error.
Rejected The incoming message must not contain any instances of
this element. If one or more instances are present,
processing fails and the message will be rejected with an
error.
Ignored Instances of this token type are not processed. Whether the
element is present or absent, an error will not be generated.
As an example, this setting could be used to disable the
processing of UsernameToken credentials when more secure
credentials (such as X.509 certificates) are being used.
Default: All policy elements are treated as “Optional”.

Example:
<InboundSecurity>
. . .
<Signature
Usage=”Optional”
. . . />
<Encryption
Usage=”Required”
. . . />
. . .
</InboundSecurity>
Timestamp Element
The <Timestamp> element supplies settings to enforce message expiration.
Outbound Messages
For outbound messages, the presence of this element generates a timestamp with a
specified “time to live” value. You can increase the precision of the value by specifying
milliseconds.
The default value is 5 min (300 sec).
Example:
<Timestamp
TimeToLiveInSeconds=”300”
IncludeMilliseconds=”True”/>
Inbound Messages
By default, expired messages generate an exception. However, you can use a setting to
turn off message expiration.
Default: Expiration is enforced.
Example:
<Timestamp
EnforceExpiration=”False”/>
UsernameToken Element
For outbound messages, the <UsernameToken> element specifies whether or not to include
a WS-Security UsernameToken in the message header.

Outbound Messages
Password Type
The “PasswordType” attribute specifies the password form to use. Currently, the only
setting is “Text”, which specifies the use of plain or clear text. You do not have to specify
the “PasswordType” attribute to use a password with the UsernameToken.
Important! The use of password digests is not supported.
Examples:
<UsernameToken
PasswordType=”Text”/>
Signature Element
Outbound Messages
Inclusion of this element causes the facility to sign the outbound SOAP message body.
Token Reference Type
The token reference type attribute indicates how the signed certificate will be included in
the message header:
Reference Type Item Included in Header

Direct The token itself, as a sequence of base-64-encoded bytes
IssuerAndSerial The token’s X.509 issuer and serial umber
SubjectKeyIdentifier The token’s X.509 subject key identifier
Thumbprint The token’s thumbprint
Example:
<Signature
TokenReferenceType=”IssuerAndSerial”/>
Include Certificate Path

This parameter controls whether to send the signing certificate as a single certificate or as
a certificate path (specified as “True” or “False”).
Default: False (meaning, send the signing certificate as a single certificate). Applies only
when the TokenReferenceType is set to “Direct.”
Note: Partial or multiple signing of a message, or changing the message digest

algorithm, is not supported.

Example:
<Signature
TokenReferenceType=”Direct”
IncludeCertPath=”True”/>
Inbound Messages
These settings indicate how to process signature information contained in the incoming
SOAP header.
Allow Expired Certificates
If this attribute is set to “False,” generates an exception when a signature is encountered
that was created with an invalid certificate (either expired or not yet valid). If this
attribute is set to “True,” message signatures created with an expired signing certificate
are allowed.
Default: False
Example:
<Signature
AllowExpiredCerts=”True”/>
Validate Signing Certificate

When set to “True,” the signing certificate will be validated to ensure that it is signed by a
trusted authority.
Default: False
Example:
<Signature
ValidateSigningCert=”True”/>
Authenticate with Signing Certificate

This setting specifies that the certificate used for authentication has been mapped to a
valid user using Integration Server’s certificate mapping facility.
Default: False
Example:
<Signature
AuthenticateWithSigningCert=”True”/>
Require Signed Body

When set to “True,” requires that the body of the SOAP message body be signed or else
an exception is thrown. Signatures are still verified when this attribute is set to “False,”
however, no exception is thrown if the SOAP body is not digitally signed.

Default: True
Example:
<Signature
RequireSignedBody=”False”/>
Encryption Element
Outbound Messages
Inclusion of this element causes the facility to encrypt the outbound message body.
The token reference type attribute indicates how the encrypted certificate will be
included in the message header.

IssuerAndSerial The token’s X.509 Issuer and Serial Number
SubjectKeyIdentifier The token’s X.509 Subject Key Identifier
Example:
<Encryption
TokenReferenceType=”Direct”/>
Encryption Algorithm
This setting specifies the algorithm to use for encrypting the message. The following table
lists the available algorithms.
Algorithm Name Algorithm ID

tripledes http://www.w3.org/2001/04/xmlenc#tripledes-cbc
aes128 http://www.w3.org/2001/04/xmlenc#aes128-cbc
Example:
<Encryption
EncryptionAlgorithm=”aes256”/>

Key Wrapping Algorithm

This setting specifies the algorithm to use for encrypting keys passed in a message. The
following table lists the available algorithms.
Algorithm Name Algorithm ID

rsa15 http://www.w3.org/2001/04/xmlenc#rsa-1_5
rsaoaep http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
Example:
<Encryption
KeyWrappingAlgorithm=”rsa15”/>
Inbound Messages
These settings indicate how to process encrypted information contained in the message
header.
Require Encrypted Body
When set to “True,” requires that the body of the SOAP message body be encrypted or an
exception is generated. The data is still decrypted when this attribute is set to “False”;
however, if the SOAP message body is not encrypted, no exception is generated.
Default: True
Example:
<Encryption
RequireSignedBody=”False”/>
X509 Authentication Element

Outbound Messages
Inclusion of this element causes the facility to include a WS-Security X.509 token
reference in the message header (without using the token to sign any part of the
message).
The token reference type attribute indicates how the signing certificate will be included
in the header:

IssuerAndSerial The token’s X.509 Issuer and Serial Number


SubjectKeyIdentifier The token’s X.509 Subject Key Identifier
Example:
<X509Authentication
TokenReferenceType=”Thumbprint”/>
Include Certificate Path

This setting controls whether to send the signing certificate as a single certificate or as a
certificate path (specified as “True” or “False”).
Default: The default value of “False” (meaning, send the signing certificate as a single
certificate) applies only when the TokenReferenceType is set to “Direct.”
Example:
<X509Authentication
TokenReferenceType=”Direct”
IncludeCertPath=”True”/>
Inbound Messages
These settings indicate how to process messages with a WS-Security X.509 token
reference in the message header.
Allow Expired Certificates
If this attribute is set to “False,” an exception is throw whenever a certificate is
encountered that is either expired or not yet currently valid. If this attribute is set to
“True,” the certificate’s expiration date is ignored.
Default: False
Example:
<X509Authentication
AllowExpiredCerts=”True”/>
Validate Certificates
Ensures that the X.509 certificate is signed by a trusted authority.
Default: False
Example:
<X509Authentication
ValidateCerts=”True”/>

Sample Policy File

The following figure shows the contents of a sample WS-Security policy file for a Web
service consumer. The example outlines the incoming and outgoing message blocks of
the policy file, and highlights several sections of code to illustrate policy file set-up and
the XML code specifying security components.
 The policy ID attribute highlighted in line 1 is required for every policy you use.
 The policy specifies use of a WS-Security Username token. This means that a token
containing the user name and password for the Web service is included in the SOAP
header of an outbound message to identify the requesting service. The only available
attribute for the Username token is text, which means that the password will be sent
in plain text (digested passwords are not supported).
 The policy specifies the use of a digital signature.
 The settings for the <Signature> component in the outbound message section
indicate that the certificate to use for authentication is specified by a path location
contained in the message header (TokenReferenceType = “Direct”, and
IncludeCertPath=”True”).
 The settings for the inbound message section indicate that a digital signature is
required on the body of incoming messages, that messages signed by an expired
certificate will not be accepted by this Web service, and that signatures will be
validated to make sure that they were signed by a trusted authority or CA.

 The policy also includes a security timestamp component indicating that message
expiration will be enforced on incoming messages, and specifying that the expiration
time of outgoing message expiration is 300 ms. After 300 ms, messages sent from this
consumer can be invalidated by the recipient.
List of Supplied WS-Security Policy Files

This section lists and describes the supplied policy files located in the
Software AG_directory\IntegrationServer\config\policy directory. There are three sets
of policy files:
 Consumer policy files. Policies that should be used at the consumer Web service
descriptor.
 Provider policy files. Policies that should be used at the provider Web service descriptor.
 Consumer and provider policy files. Policies that you can use for consumers and
providers. The inbound and outbound requirements are the same, therefore, you can
use the policies for either direction.
Important! When using a supplied policy file or customizing a copy of a supplied

policy file, make sure to specify a unique identifier in the Policy element’s ID
attribute.
Consumer Policy Files
Policy Name File Name (XML) Description
Consumer policy Username_for_ Use at the consumer Web service

for username consumer descriptor for enabling basic
authentication.
Consumer policy Username_Sign_for_ Use at the consumer Web service
for username, consumer descriptor for enabling basic
signature authentication with digital
signature.
Consumer policy Username_Sign_ Use at the consumer Web service
for username, Encrypt_for_consumer descriptor for enabling basic
signature, authentication with digital signature
encryption and encryption.

Consumer policy Sign_Auth_for_ Use at the consumer Web service

for signature, consumer descriptor for enabling signature-
authentication based authentication.
Consumer policy Sign_Auth_Encrypt_ Use at the consumer Web service
for signature, for_consumer descriptor for enabling signature-
authentication, based authentication and
encryption encryption.
Provider Policy Files
Provider policy Username_for_provider Use at the provider Web service

for username descriptor for enabling basic
authentication.
Provider policy Username_Sign_for_ Use at the provider Web service
for username, provider descriptor for enabling basic
signature authentication with digital
signature.
Provider policy Username_Sign_Encrypt_ Use at the provider Web service
for username, for_provider descriptor for enabling basic
signature, authentication with digital
encryption signature and encryption.
Provider policy Sign_Auth_for_provider Use at the provider Web service

for signature, descriptor for enabling signature-
authentication based authentication.
Provider policy Sign_Auth_Encrypt_for_ Use at the provider Web service
for signature, provider descriptor for enabling signature-
authentication, based authentication and
Consumer and Provider Policy Files
Digital signature Sign Use to enable a digital signature.

Digital signature, Sign_Encrypt Use to enable a digital signature and

C WS-Security: Detailed Usage and Resolution Order for
Certificates and Keys
 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
 Web Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
 Web Service Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

C WS-Security: Detailed Usage and Resolution Order for Certificates and Keys
Introduction
This appendix describes the WS-Security facility’s certificate and key usage resolution
order for policy assertions, attributes, and settings.
Note: The sections in this appendix refer to keystore and key aliases for the Signing
Key, the Decryption Key, and the SSL Key. You can configure these keystore and key
aliases on the Security > Certificates screen of the Integration Server Administrator.
Web Service Provider

The following tables are organized according to whether the message is a request
(inbound security) or response (outbound security). The usage order applies to all
attributes of a policy assertion except where otherwise specified. If a policy assertion is
not specified, then certificate and key resolution order is not applicable.
Response (Outbound Security)
Policy Assertion Attribute Value Usage/Resolution Order

Signature 1 Endpoint Alias
(Sign) WS Security Properties/Keystore Alias
WS Security Properties/Key Alias
2 Listener (Port) Settings
Listener Specific Credentials/Keystore
Alias
Listener Specific Credentials/Key Alias
3 Server Settings
Signing Key/Keystore Alias
Signing Key/Key Alias
4 Server Settings
SSL Key/Keystore Alias
SSL Key/Key Alias


IncludeCertPath True 1 Endpoint Alias
Entire certificate chain associated with the
specified Key Alias is used
3 Server Settings
Key Alias specified for Signing is used
4 Server Settings
Key Alias specified for SSL is used
IncludeCertPath False 1 Endpoint Alias
Only the server’s certificate (first certificate
in the chain) associated with the specified
Key Alias is used
in the chain) associated with the specified
Key Alias is used
3 Server Settings
in the chain) associated with the Key Alias
specified for Signing is used
4 Server Settings
Only server’s certificate (1st certificate in
chain) associated with the Key Alias
specified for SSL is used
Encryption 1 WS Security Header
(Encrypt) Public key included in the request header
2 Certificate Mapping
Public key (certificate) associated with
resolved user and Usage (in the order
specified below) for one of:
 Encrypt
 VerifyAndEncrypt
 SSL

Request (Inbound Security)

UsernameToken  WS Security Header
User Name and Password
Signature 1 WS Security Header
(Verify) Public key included in the header
2 Certificate Mapping
Public key (certificate) associated with
resolved user and Usage (in the order
specified below) for one of:
 Verify
 SSL
ValidateSigningCert True 1 Endpoint Alias
WS Security Properties/Truststore
Listener Specific Credentials/Truststore
Alias
3 Server Settings
Truststore/Truststore Alias
AuthenticateWith True  Certificate Mapping
SigningCert User associated with signed certificate
(public key) and Usage of one of the
following:
 MessageAuth
 Verify
 SSL


Encryption 1 Endpoint Alias
(Decrypt) WS Security Properties/Keystore Alias
Listener Specific Credentials/Keystore
Alias
Listener Specific Credentials/Key Alias
3 Server Settings
Decryption Key/Keystore Alias
Decryption Key/Key Alias
4 Server Settings
SSL Key/Key Alias
X.509  Certificate Mapping
Authentication User associated with signed certificate
(public key) and Usage of one of the
following:
 MessageAuth
 Verify
 SSL
ValidateCerts True 1 Endpoint Alias
Listener Specific Credentials/Truststore
Alias
3 Server Settings
Web Service Consumer

The following tables are organized according to whether the message is a request
(outbound security) or response (inbound security). The usage order applies to all
attributes of a policy assertion except where otherwise specified. If a policy assertion is
not specified, then certificate and key resolution order is not applicable.

Response (Inbound Security)

Signature 1 Passed In (Generated WSC)
(Verify) auth/message/partnerCert
2 Endpoint Alias
WS Security Properties/Partner’s Certificate
3 WS Security Header
Public key included in header
ValidateSigningCert True 1 Endpoint Alias
2 Server Settings
Encryption 1 Passed In (Generated WSC)
(Decrypt) auth/message/serverCerts/keyStoreAlias
auth/message/serverCerts/keyAlias
2 Endpoint Alias
WS Security Properties/Keystore Alias
3 Server Settings
Decryption Key/Keystore Alias
Decryption Key/Key Alias
4 Server Settings
SSL Key/Key Alias

Request (Outbound Security)

UsernameToken 1 Passed In (Generated WSC)
auth/message/user
auth/message/pass
2 Endpoint Alias
WS Security Properties/User Name
WS Security Properties/Password
Signature 1 Passed In (Generated WSC)
(Sign) auth/message/serverCerts/keyStoreAlias
2 Endpoint Alias
3 Server Settings
4 Server Settings
SSL Key/Key Alias
IncludeCertPath True 1 Passed In (Generated WSC)
Entire certificate chain used with the specified
value for auth/message/serverCerts/keyAlias
2 Endpoint Alias
3 Server Settings
Entire certificate chain associated with the Key
Alias specified for Signing is used
4 Server Settings
Alias specified for SSL is used


IncludeCertPath False 1 Passed In (Generated WSC)
Only the server’s certificate (first certificate in
the chain) with the specified value for
auth/message/serverCerts/keyAlias is used
2 Endpoint Alias
the chain) associated with the specified Key
Alias is used
3 Server Settings
the chain) associated with the Key Alias
4 Server Settings
Encryption 1 Passed In (Generated WSC)
(Encrypt) auth/message/partnerCert
2 Endpoint Alias
WS Security Properties/Partner’s Certificate
X.509 1 Passed In (Generated WSC)
Authentication auth/message/serverCerts/keyStoreAlias
2 Endpoint Alias
3 Server Settings
4 Server Settings
SSL Key/Key Alias


IncludeCertPath True 1 Passed In (Generated WSC)
Entire certificate chain used with the specified
value for auth/message/serverCerts/keyAlias
2 Endpoint Alias
3 Server Settings
Alias specified for Signing is used
4 Server Settings
Alias specified for SSL is used
IncludeCertPath False 1 Passed In (Generated WSC)
the chain) with the specified value for
auth/message/serverCerts/keyAlias is used
2 Endpoint Alias
the chain) associated with the specified Key
Alias is used
3 Server Settings
4 Server Settings


D JAX-RPC Handlers
 Writing JAX-RPC Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

D JAX-RPC Handlers
Writing JAX-RPC Handlers

Important! The public services used to register Java JAX-RPC handlers with custom
code remain available, but were deprecated in webMethods Integration Server 7.1.2.
Software AG strongly recommends converting your JAX-RPC handlers to service
handlers, to ensure their compatibility and maintainability with current webMethods
products. For more information about service handlers, see Chapter 8, “Working with
Handlers”
Custom handlers can implement the JAX-RPC handler interface

(javax.xml.rpc.handler.Handler), which includes the following methods:
 init(HandlerInfo) - This method is called on running the registerProvider or
registerConsumer services.
 destroy() - This method is called on running the unregisterProvider or
unregisterConsumer services.
 getHeaders() - Returns the QName of the headers that the handler acts upon.
 handleRequest(MessageContext) - processes the request SOAP message.
 handleResponse(MessageContext) - processes the response SOAP message.
 handleFault(MessageContext) - processes the SOAP fault message.
Note: It is recommended that you copy the files

<Software AG_directory>\common\lib\ext\saaj-api.jar,
<Software AG_directory>\common\lib\ext\jaxrpc-api.jar, and handler classes to
the classpath of webMethods Developer to display the handlerInfo object and resolve
the ClassNotFoundException for handler class.
Keep the following points in mind when using the JAX-RPC handler interface to write a
custom handler:
 When a Web service descriptor is configured and multiple handlers are added, the
order of the execution of the handlers is the order they are defined in the Web service
descriptor. By default, this is the order in which they are added, but that order can be
modified when editing the Web service descriptor. Therefore, the order of the
handlers is very important.
 If headers are defined within a WSDL file used to generate a Web service descriptor,
they are automatically added to the Web service descriptor and assigned to the
handler used to process the header to that Web service descriptor. If the WSDL used
to create the Web service descriptor does not contain header definitions, or if a
provider Web service descriptor is being created from exiting IS services instead of
WSDL, you must manually add headers after the Web service descriptor is created.

E Web Service-Related Errors and Warnings
 Message Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

 ISC (IS Core) Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
 ISS (IS Server) Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
 ITD (Developer) Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Message Display
When you create or execute a Web service descriptor, Developer displays a message that
indicates whether the process completed successfully.
If the process completed successfully but warnings occurred, Developer displays a
message to that effect. If the process did not complete successfully, Developer displays a
message that says errors occurred.
When you click Details on the message dialog box, Developer provides information
similar to the information in the message dialog box shown below.
Name and location of WSDL document

in which the error or warning occurred.
Location of the error or

warning in the WSDL
document.
Message code.
WSDL elements
that caused the
error or warning.
Note: When generating a Web service descriptor, Developer might generate some of
the flow steps in the Web service descriptor or some of the supporting IS elements
(Web service connectors, IS document types, folders, or IS schemas) before it
encounters errors or warnings. The generated elements appear in the Navigation
panel.
Following are the error messages and warning messages that can occur when Developer,
Designer, or Integration Server creates or executes a consumer Web service descriptor, a
Web service connector, or a provider Web service descriptor.
ISC (IS Core) Errors and Warnings
[ISC.0077.9014] Document to XSD error: Field fieldName cannot be represented in XML Schema. The
field name does not conform to the XML NCName definition.
Cause: The Developer determined that the IS document type you are using to generate a
WSDL document contains field names that do not conform to the XML NCName
definition.

Response: To resolve this error, rename the fields to conform to the QName lexical rules
specified in http://www.w3.org/TR/REC-xml-names/#NT-QName and the XML
namespace and local naming conventions specified in http://www.w3.org/TR/REC-xml-
names/#NT-NCName.
ISC.0088.0028E Service handler <serviceHandler> could not be registered. A service handler by that
name already exists.
Cause: A service handler with the provided name already exists.
Response: Specify a unique name for the service handler.
ISC.0088.0029E Error initializing handler <headerHandler>. Error <errorMessage>

Cause: An error occurred while initializing the JAX-RPC header handler.
Response: The init() method of the JAX-RPC handler threw an error. Correct the error in
init() method.
ISC.0088.0030E Error destroying service handler <serviceHandlerName>. Error: <errorMessage>

Cause: An error occurred while destroying the JAX-RPC handler.
Response: The destroy() method of the JAX-RPC Handler has thrown an error. Correct the
error in destroy() method.
ISC.0088.0031E Service handler <serviceHandler> could not be registered. Missing required

parameter <parameter>
Cause: A parameter required to register the service handler was not provided.
Response: Provide the missing parameter.
ISC.0088.0032E Service handler <serviceHandler> could not be unregistered. A service handler by

that name is not registered.
Cause: The specified service handler is not registered.
Response: Provide the name of a registered service handler.
ISC.0088.0033E Service handler <serviceHandler> could not be unregistered. Missing required

parameter <parameter>
Cause: The service handler could not be unregistered because a required parameter is
missing.
Response: Provide the missing parameter.

ISC.0088.0034E Registered service handlers could not be listed. Missing required parameter
<parameter>
Cause: The list of registered service handlers could not be created because a required
input parameter was not provided.
Response: Provide the missing input parameter.
ISC.0088.0035E Service handler <serviceHandler> could not be found. Missing required parameter
<parameter>
Cause: Service handler could not be found because a required input parameter was not
provided.
Response: Provide the missing input parameter.
ISC.0088.0036E Service handler <serviceHandler> could not be found. Service handler is not
registered.
Cause: A service handler with the provided name does not exist.
Response: Register a service handler with the provided name or specify the name of an
existing registered service handler.
ISC.0088.0037E Could not find service handler for header <QName>

Cause: The universal name (QName) of the header does not correspond to a registered
service handler.
Response: Verify that the universal name of the header corresponds to a registered service
handler or register a service handler for the provided universal name.
ISC.0088.9320 MTOM Attachments Processing Failed: Cannot convert SOAP Message to XOP
Package; “null” value for Web service descriptor
Cause: The Web service descriptor identified by the part of request URL (for provider) or
passed Web service descriptor name (for consumer) as parameter, does not exist.
Response: Correct the URL or correct the passed Web service descriptor name or create a
proper Web service descriptor.
ISC.0088.9321 MTOM Attachments Processing Failed: Cannot convert SOAP Message to XOP
Package; base64Binary encoded data is not in the Canonical Lexical form
Cause: Base64Binary encoded data is not in Canonical Lexical form; it contains line break
characters or tabs.
Response: Convert the Base64Binary data into Canonical Lexical form.

[ISC.0124.9001] Document to XSD warning: For interoperability reasons, the <any> type is not used in
SOAP RPC WSDL. Document {0} will be defined as closed in the XSD.
Cause: The IS document type you are using to generate a WSDL document contains
variables of type Document or Document list. These variables are open (that is, their Allow
unspecified fields property is set to True).
Response: To resolve this warning, set the Allow unspecified fields property in the Constraints
category of the Properties panel to False. Then, regenerate the WSDL document.
[ISC.0124.9002] Document to XSD error: Document {0} cannot be represented in XML Schema. This
document contains a *body field constrained by a simple type and fields that would be represented
as elements in the XSD. XSD could describe this document if the simple type constraint was removed
or the non-attribute fields were deleted.
Cause: The IS document type you are using to generate a WSDL document contains a
field named *body that is constrained by a simple type. The IS document type also
contains fields that are mapped as elements (not attributes) in the XSD. This combination
cannot be mapped in an XSD.
In a mixed content environment, the Integration Server can only map complex type
definitions of simple content (that is, an IS document type containing attributes and a
*body variable with or without a simple type constraint) or complex type definitions of
complex content (that is, an IS document type containing attributes and/or elements and
a *body variable that is not constrained).
Response: To resolve this error, do one of the following:
 Remove the non-attribute fields.
 Remove the *body variable’s simple type constraint. First, click the browse button next
to the Content type property on the variable’s Properties panel. Then, select No
Constraints Specified from the Content Type list on the resulting Properties dialog box.
[ISC.0124.9003] Document to XSD error: Referenced document type {0} does not exist.
reference to a nonexistent document type.
Response: To resolve this error, restore the nonexistent document type or remove the
reference to it.
[ISC.0124.9004] Document to XSD error: Field {0} is a String table. String tables cannot be
represented in XML Schema.
Cause: The IS document type you are using to generate a WSDL document contains String
table fields. XML Schema does not support multi-dimensional arrays.
Response: To resolve this error, remove the String table field from the IS document type or
select a different IS document type.

[ISC.0124.9005] Document to XSD error: Field {0} cannot be represented in XML Schema. The field
name contains a prefix but an XML Namespace property is not assigned to the field.
Cause: The IS document type you are using to generate a WSDL document contains a top-
level field whose name includes a prefix (that is, the name is in the format
prefix:localName). However, this field is not associated with an XML namespace.
 Associate the field with an XML namespace. First, select the variable in Developer.
Then, type the namespace for the variable in the XML Namespace property in the
General category of the variable’s Properties panel.
 Remove the prefix.
Important! Some protocols require the use of a prefix. Before removing the prefix,
check the service signature’s input and output requirements as documented for
each protocol in this guide.
[ISC.0124.9006] Document to XSD error: Field {0} cannot be represented in XML Schema. The field
name does not conform to the XML NCName definition.
Cause: The IS document type you are using to generate a WSDL document contains field
names that do not conform to the XML NCName definition.
Response: To resolve this error, rename the fields to conform to the QName lexical rules
specified in http://www.w3.org/TR/REC-xml-names/#NT-QName and the XML
namespace and local naming conventions specified in http://www.w3.org/TR/REC-xml-
names/#NT-NCName.
[ISC.0124.9007] Document to XSD error: Document {0} cannot be represented in XML Schema. The
document contains multiple *body fields.
Cause: The IS document type or XML Schema element declaration you are using to
generate a WSDL document contains more than one field named *body at the same level.
Response: To resolve this error, remove or rename the duplicate *body fields.
[ISC.0124.9008] Document to XSD error: Document {0} cannot be represented in XML Schema. The
document contains multiple attributes of the same name at the same level.
generate a WSDL document contains attributes at the same level with the same name.
Response: To resolve this error, remove or rename the duplicate attributes.

[ISC.0124.9009] Document to XSD error: Field <fieldName> cannot be represented in XML Schema.
Attributes cannot have dimension greater than 0.
generate a WSDL document contains array or table type attributes. XML Schema does
not support multi-dimensional attributes.
Response: To resolve this error, remove the attribute from the IS document type or
redefine its type to String.
[ISC.0124.9011] Document to XSD error: Simple type <simpleTypeName> does not exist.
reference to a nonexistent simple type that has been applied to a variable as a content
type constraint.
 Restore the nonexistent simple type by generating a schema on the server that defines
the missing type. To do so, you can either create a schema from an XSD or enable or
import a package that contains a schema with the missing type.
 Remove the reference to the missing type. First, click the browse button next to the
Content type property on the variable’s Properties panel. Then, select No Constraints
Specified from the Content Type list on the resulting Properties dialog box.
ISS (IS Server) Errors and Warnings
[ISS.0085.9262] No registered handler found for Header QName: <QName>

Cause: The WSDL you are using to create the Web service connector has a header defined,
but a matching header handler is not registered in Integration Server.
Response: Add a header handler with a QNAME matching the Document Universal
Name to Integration Server, then create the Web service connector. If you do not have the
appropriate header handler, you can continue the process and Developer will create the
Web service connector without the header information.
[[ISS.0085.9282] Unknown extensible element “{0}" found in SOAP binding “{1}"

Cause: The WSDL you are using to create the Web service descriptor contains a <binding>
element with a child other than SOAP 1.1 or SOAP 1.2. Developer does not support
extensions to SOAP, such as sdk:binding (Microsoft SOAP-Toolkit extensions).
Developer will process the valid portions of the SOAP 1.1 or SOAP 1.2 binding, but will
skip processing of the unsupported extension.
Response: Verify that the WSDL contains a valid SOAP 1.1 or SOAP 1.2 binding, and is
usable without the extension.

ISS.0085.9291 Binding with style="rpc" and use="encoded" is not supported for SOAP version 1.2.
Binding <binding> ignored.
Cause: Integration Server does not support RPC/Encoded for SOAP version 1.2.
Integration Server ignores bindings that specify this style/use.
Response: No action is required.
ISS.0086.9284 Folder <folder> is not empty.

Cause: The specified folder must be empty.
Response: Delete the contents of the specified folder or specify an empty folder.
ISS.0086.9285 Invalid folder name <folder>. Error: <errorMessage>

Cause: The specified folder name is invalid.
Response: Specify a valid folder name.
ISS.0088.9133 Error while encoding RPC output

Cause: Fault handler service failed with a status code of 3.
ISS.0088.9144 This SOAPEnvelope object already contains a valid SOAPHeader object

Cause: An attempt was made to add a SOAPHeader object to the SOAPEnvelope of a
SOAPMessage that already contains a SOAPHeader object.
Response: The SOAPEnvelope object may contain a maximum of one SOAP Header.
ISS.0088.9145 This SOAPEnvelope object does not contain a valid SOAPHeader object
Cause: An attempt was made to access the SOAPHeader object, but the SOAPEnvelope of
the SOAPMessage does not contain a SOAPHeader object.
Response: Add a SOAPHeader object to the SOAPEnvelope before accessing it.
ISS.0088.9146 This SOAPEnvelope object already contains a valid SOAPBody object

Cause: An attempt was made to add a SOAPBody object to the SOAPEnvelope of a
SOAPMessage that already contains a SOAPBody object.
Response: The SOAPEnvelope object must contain exactly one SOAPBody object.
ISS.0088.9147 This SOAPEnvelope object does not contain a valid SOAPBody object
Cause: An attempt was made to access the SOAPBody object, but the SOAPEnvelope of
the SOAPMessage does not contain a SOAPBody object.
Response: Add a SOAPBody object to the SOAPEnvelope before accessing it.

ISS.0088.9148 Exception occurred while retrieving SOAPHeader object

Cause: The specified exception occurred while attempting to access the SOAPHeader
object.
Response: Correct the error and retry.
ISS.0088.9149 Exception occurred while retrieving SOAPBody object

Cause: The specified exception occurred while attempting to access the SOAPBody object.
ISS.0088.9150 Exception occurred while retrieving SOAPHeaderElement objects

Cause: The specified exception occurred while attempting to access the
SOAPHeaderElement object.
ISS.0088.9151 Exception occurred while retrieving SOAPBodyElement objects

Cause: The specified exception occurred while attempting to access the
SOAPBodyElement object.
ISS.0088.9152 The property <property> is unknown

Cause: An attempt was made to either get or set a property of the specified
SOAPMessage, but the property name is unknown. The only valid SOAPMessage
property names are java.xml.soap.WRITE_XML_DECLARATION and
javax.xml.soap.CHARACTER_SET_ENCODING.
Response: Correct the name of the property to use one of the valid property names.
ISS.0088.9153 This SOAPMessage object already contains a valid Detail object

Cause: An attempt was made to add a Detail object to the SOAPBody of this
SOAPMessage, but the SOAPBody already contains a Detail object. The SOAPBody can
contain one and only one Detail object.
Response: Remove the existing Detail object before adding the new one.
ISS.0088.9154 This SOAPMessage object already contains a valid Fault object

Cause: An attempt was made to add a Fault object to the SOAPBody of this
SOAPMessage, but the SOAPBody already contains a Fault object. The SOAPBody can
contain one and only one Fault object.
Response: Remove the existing Fault object before adding the new one.

ISS.0088.9155 This SOAPMessage does not contain a valid Envelope object

Cause: The specified SOAPMessage does not contain a valid SOAPEnvelope object.
Response: Create a new SOAPMessage that contains a valid SOAPEnvelope object.
ISS.0088.9156 JAX Handler <handler> already registered

Cause: An attempt was made to register the JAX-RPC handler, but the handler is already
registered.
ISS.0088.9157 Error initializing JAX Handler <handler>:<errorMessage>

Cause: An error occurred while initializing the JAX-RPC handler. The error message is
specified following the colon.
Response: Correct the error indicated by the error message and retry.
ISS.0088.9158 Error destroying JAX Handler <handler>:<errorMessage>

Cause: An error occurred while destroying the JAX-RPC handler. The error message is
specified following the colon.
Response: Correct the error indicated by the error message and retry.
ISS.0088.9159 Failed to register JAX Handler <handler>

Cause: An attempt to register the JAX-RPC handler failed.
Response: Search the webMethods Integration Server log for errors indicating why the
JAX-RPC handler could not be registered. Correct any errors and retry.
ISS.0088.9160 Failed to unregister JAX Handler <handler> - Not Registered

Cause: An attempt to unregister the JAX-RPC handler failed. The handler was not
registered.
ISS.0088.9161 Failed to find JAX Handler <handler> - Not Registered

Cause: The specified JAX-RPC handler could not be located because it is not registered.
Response: Register the specified JAX-RPC handler and retry.
ISS.0088.9162 Failed to find JAX Handler for header <header>

Cause: The JAX-RPC handler for the specified header was not found.
Response: Correct the name of the JAX-RPC handler and retry.

ISS.0088.9163 Could not retrieve WSDL for service <service>; WSD not found
Cause: An attempt to retrieve the WSDL for the specified service failed because the Web
service descriptor does not exist.
Response: Correct the name of the JAX-RPC handler and retry.
ISS.0088.9164 Access to Web service descriptor <Web service descriptor> denied.

Cause: The user is not authorized to access the specified Web service descriptor.
Response: Specify a username that is authorized to access the specified Web service
descriptor.
ISS.0088.9166 Binder not found for soapAction = null

Cause: The Web service descriptor has more than one binder, with the same operation
name. Developer cannot calculate a default soapAction attribute to identify the correct
operation.
Response: Include a unique soapAction attribute in the SOAPAction HTTP Header for
every request, as described in “Modifying the SOAP Action for an Operation in a Binder”
on page 66.
ISS.0088.9251 JAX-RPC Handler failed to process the message

Cause: The JAX-RPC handler was invoked to process the message. Either the
handleRequest() or handleResponse() method returns false, indicating a failure.
Response: Check the webMethods Integration Server log for error messages generated by
the JAX-RPC handler.
ISS.0088.9252 An exception has been caught: <errorMessage>

Cause: An exception was caught while attempting to process a SOAP message.
Response: Correct the problem indicated by the error message.
ISS.0088.9253 Could not add “Text” element to “Reason” element, locale is null
Cause: An attempt to add a Text element to the existing Reason element failed because the
locale was not specified.
Response: Specify the locale when adding the Text element.
ISS.0088.9254 The System property, javax.xml.soap.MetaFactory, must be set to

“com.wm.app.b2b.server.saaj.SAAJMetaFactory”
Cause: The javax.xml.soap.MetaFactory is not set properly.
Response: Set the javax.xml.soap.MetaFactory property to
“com.wm.app.b2b.server.saaj.SAAJMetaFactory”.

ISS.0088.9255 The element’s QName cannot be changed

Cause: An attempt to change the QName of a SOAPEnvelope, SOAPBody, or
SOAPHeader failed, because it cannot be changed.
ISS.0088.9322 MTOM Attachments Processing Failed: Cannot convert SOAP Message to XOP
Package; invalid SOAP Message
Cause: The SOAP Message is invalid; either it is not well formed or it does not contain
valid namespace declarations.
Response: Check the structure and content of the SOAP message.
ISS.0088.9323 MTOM Attachments Processing Failed: Cannot convert SOAP Message to XOP
Package; I/O Error occurred
Cause: Converting SOAP Message to XOP Package has been interrupted by another
thread.
Response: Retry the action that caused it.
ISS.0088.9324 MTOM Attachments Processing Failed: Cannot convert XOP Package to SOAP
Message; “Content-Id” header field is missing in some of the attachments
Cause: One or more attachments does not contain the “Content-Id” field. This field is
required to put the content of the attachment back into the SOAP message.
Response: Verify that the serialization of XOP Package to MIME stream had “Content-Id”
present in the corresponding MIME part.
ISS.0088.9325 MTOM Attachments Processing Failed: Cannot serialize the XOP Message; unable to
retrieve bytes from SOAP String using the SOAP Message Content Encoding
Cause: The conversion of SOAP String to byte array using the encoding specified for
SOAP message has failed.
Response: Correct the content encoding specified for the SOAP message.
ISS.0088.9326 MTOM Attachments Processing Failed: Cannot serialize the XOP Message; MIME
serialization has failed
Cause: Serialization of XOP Package to MIME Stream has failed.
Response: Verify the structure of SOAP Message is correct. Particularly the elements
which contains base64Binary data.

ISS.0088.9327 MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream;
value of the “Content-Type” header of the MIME message is not equal to “multipart/related”
Cause: Value for the “Content-Type” header field of the MIME message is not equal to
“multipart/related”.
Response: Verify that you have passed the correct value for “Content-Type” while
serializing the MIME message.
value of the “type” parameter of the “Content-Type” header of the MIME message is not equal to
“application/xop+xml”
Cause: Value for the “type parameter” of the “Content-type” header field of the MIME
message is not equal to “application+xop+xml”.
Response: Verify that you have passed the correct value for “type” parameter while
serializing the MIME message.
value of the “start-info” parameter of the “Content-type” header of the MIME message is not equal to
“application/soap+xml”
Cause: Value for the “start-info” parameter of the “Content-Type” header field of the
MIME message is not equal to “application/soap+xml”
Response: Check if you have passed the correct value for “start-info” parameter while
serializing the MIME message otherwise pass the correct value for it.
“Content-Type” header of the Root MIME Part is invalid
Cause: Invalid content type for Root MIME part.
Response: Verify that you have passed the correct value for “Content-Type” header field
of the Root MIME Part while serializing the MIME message.
“Content-type” header of the Root MIME Part does not match with the “type” parameter of the MIME
message
Cause: The value of the “Content-Type” header of the Root MIME Part is not equal to the
value of the “type” parameter of the “Content-Type” header of the MIME message.
Response: Verify that you have passed the correct value for these field(s)/parameter(s)
while serializing the MIME message.

value of “type” parameter of the “Content-Type” header of the Root MIME Part does not match with
the value of the “start-info” parameter of the MIME message
Cause: The value of the “type” parameter of the “Content-Type” header of the Root
MIME Part is not equal to the value of the “start-info” parameter of the “Content-Type”
header of the MIME Message.
Response: Verify that you have passed the correct value for these field(s)/parameter(s)
while serializing the MIME.
SOAP Message in the Root MIME psrt is not of version 1.2
Cause: The version of the SOAP Message not equal to 1.2.
Response: Send the SOAP 1.2 message.
Root MIME Part contains invalid SOAP Message
Cause: The SOAP Message in the Root MIME Part is invalid; either it is not well formed or
it does not contain valid namespace declarations.
Response: Check the structure and content of the SOAP message in the Root MIME Part.
input stream is not a valid MIME stream
Cause: MIME Stream does not contain the valid data as per the MIME specifications.
Response: Verify that the MIME stream contains a valid MIME message.
ISS.0088.9356 One or more required Headers {0} are not present in the SOAP request
Cause: The SOAP request received by the provider does not contain one or more required
headers.
Response: Verify that the SOAP request contains valid versions of the required headers.
ISS.0088.9420 Required parameter {0} is missing.

Cause: A required input parameter was not provided.
Response: Provide the required input parameter.
ISS.0088.9421 The service {0} does not exist.

Cause: The specified service does not exist.
Response: Specify an existing service.

ISS.0088.9422 Either parameter {0} or {1} must be provided.

Cause: The service requires either one of the specified parameters, but neither was
provided.
Response: Provide one of the required parameters.
ISS.0088.9423 Service handler {0} is already registered.

Cause: A service handler with that name is already registered.
Response: Specify a different name when registering the service handler.
ISS.0088.9424 Error initializing service handler {0}. Error: {1}

Cause: An error occurred while initializing the JAX-RPC header handler.
Response: The init() method of JAX-RPC handler threw an error. Correct the error in init()
method.
ISS.0088.9425 Error destroying service handler {0}. Error:{1}

Cause: An error occurred while destroying the JAX-RPC handler.
Response: The destroy() method of the JAX-RPC Handler has thrown an error, Correct the
error in destroy() method.
ISS.0088.9427 Service handler {0} could not be unregistered. A service handler by that name is not
registered.
Cause: A service handler with the provided name is not registered.
Response: Specify the name of a registered service handler.
ISS.0088.9428 Service handler {0} could not be found. A service handler by that name is not
registered.
Cause: The specified service handler could not be found because it is not registered.
Response: Provide the name of a registered service handler.
ISS.0088.9429 Could not find service handler for header {0}:{1}

Cause: The header universal name (QName) does not correspond to a registered service
handler.
Response: Verify that the universal name of the header corresponds to a registered service
handler or register a service handler for the provided universal name.
ISS.0088.9430 Handler processing failed on the <provider or consumer>.

Cause: A handler service failed on the provider or consumer.

Response: Examine the handler services for errors and correct any errors that are found.
ISS.0088.9431 Handler processing failed on the consumer.

Cause: A handler service failed on the consumer.
Response: Examine the handler services for errors and correct any errors that are found.
[ISS.0092.9001] Server Error: {0}

Cause: A server error occurred while Developer was generating the Web service
connector.
Response: Click Details on the message dialog box to view the errors.
[ISS.0092.9002] Warning: Document does not contain service element, no ports were generated for
any Web service connector.
Cause: The WSDL document does not contain a <service> element, and therefore does
not contain any <port> elements. (A <service> element is a collection of <port> elements.)
Developer generates the Web service connector, but the Web service connector will not
specify any flow MAP steps for setting the port information. In the Web service
connector, the BRANCH on '/_port' step contains a child port MAP step for each unique
<port> associated with the <operation>. The BRANCH on '/_port' step will not contain
child port MAP steps. The Web service connector cannot execute successfully without
port information because the port information specifies the network address for invoking
the Web service.
[ISS.0092.9003] Error: SOAP binding does not contain extended element

http://schemas.xmlsoap.org/wsdl/soap/binding, binding was not created.
Cause: The <binding> element is missing the <soap:binding> element. If the WSDL
document specifies SOAP as a protocol, the <binding> element must contain
<soap:binding> as the first child element.
Developer generates the Web service connector, but the Web service connector does not
contain a SEQUENCE step that corresponds to this binding. (In the Web service
connector, the BRANCH on '/binding' step contains a child SEQUENCE step for each
unique <binding> associated with an <operation>.)
[ISS.0092.9004] Error: SOAP binding does not contain transport value, binding was not created.
Cause: In the WSDL document, the <soap:binding> element contains a transport attribute
but no value is specified for it. The transport value indicates which transport of SOAP
the binding uses. It is required for a SOAP binding and its value must be
http://schemas.xmlsoap.org/soap/http.

contain a SEQUENCE step that corresponds to this binding. In the Web service
unique <binding> associated with an <operation>.
[ISS.0092.9005] Error: SOAP binding has an unsupported transport value, binding was not created.
Cause: In the WSDL document, the transport attribute in the <soap:binding> element
specifies an unsupported SOAP transport. Developer can generate a binding for a SOAP
binding only if the transport value is http://schemas.xmlsoap.org/soap/http.
webMethods Developer generates the Web service connector, but the Web service
connector does not contain a SEQUENCE step that corresponds to this binding. In the
Web service connector, the BRANCH on '/binding' step contains a child SEQUENCE step
for each unique <binding> associated with an <operation>.
[ISS.0092.9006] Error: SOAP binding does not contain a transport attribute, binding was not created.
Cause: In the WSDL document, the <soap:binding> element does not contain a transport
attribute. The transport value indicates which transport of SOAP the binding uses. It is
required for a SOAP binding. The transport attribute value must be
http://schemas.xmlsoap.org/soap/http.
[ISS.0092.9007] Error: SOAP binding has an unrecognized style value, binding was not created.
Cause: In the WSDL document, the <soap:binding> element specifies a value other than
rpc or document for the style attribute.
[ISS.0092.9011] Error: Mime binding style is unsupported, binding was not created.
Cause: The WSDL document specifies a MIME binding style for the entire <binding>.
webMethods Developer only supports the MIME binding style to describe the inputs and
outputs of an HTTP binding. webMethods Developer cannot generate a binding when
the MIME binding style is specified outside of the HTTP binding context.
unique <binding> associated with an <operation>.)

[ISS.0092.9013] Warning: The operation's binding does not have any ports, no ports were generated
for the Web service connector.
Cause: Developer cannot find a <port> element that corresponds to a particular <binding>
element. A <port> element specifies a network address or endpoint for a binding.
Developer generates the Web service connector, but does not generate any MAP steps for
setting the binding and address information. In a Web service connector, the BRANCH
on '/_port' step contains a child portName MAP step for each <port> associated with the
<operation>. When this warning occurs, the BRANCH on '/_port' step contains no child
portName MAP steps.
[ISS.0092.9014] Warning: The operation does not have any valid ports, no ports were generated for
the Web service connector.
Cause: The WSDL document does not contain any valid <port> elements for an
<operation>. The WSDL document might not contain any <port> elements or a <port>
element might reference a non-existent <binding> element. (A <binding> element
associates a protocol with an <operation>.)
Developer generates the Web service connector, but does not generate any portName
MAP steps for setting the binding and address information. In a Web service connector,
the BRANCH on '/_port' step contains a child portName MAP step for each <port>
associated with the <operation>. When this warning occurs, the BRANCH on '/_port' step
contains no child portName MAP steps.
[ISS.0092.9015] Warning: Port does not have a valid binding type, port was not generated.
Cause: The WSDL document contains a <port> element that does not contain the binding
attribute.
Developer generates the Web service connector, but does not generate a MAP step for
this port. In a Web service connector, the BRANCH on '/_port' step contains a child
portName MAP step for each <port> associated with the <operation>. The portName MAP
step sets the binding and address information for a port.
[ISS.0092.9016] Warning: Port does not have a location value, port was not generated.
Cause: Within the <port> element, the <address> element does not specify a value for the
location attribute. The location attribute specifies the network address or endpoint for
the service.
Developer generates a Web service connector, but without the network address,
webMethods Developer cannot generate a MAP step for this port. In a Web service
connector, the BRANCH on '/_port' step contains a child portName MAP step for each
<port> associated with the <operation>. The portName MAP step sets the binding and
address information for a port.

[ISS.0092.9017] Warning: Port does not have required address element, port was not generated.
Cause: The selected WSDL document does not contain an <address> element within the
specified <port> element. The <address> element carries an attribute that specifies the
location or network address for of the Web service.
Developer generates a Web service connector, but does not generate a MAP step for this
port. The portName MAP step sets the binding and address information for a port.
Without the <address> element, Developer cannot set the address information and
therefore cannot generate a MAP step.
[ISS.0092.9018] Warning: Port does not have required location attribute, port was not generated.
Cause: Within the <port> element, the <address> element does not carry the location
attribute. The location attribute specifies the network address for the service.
Developer generates a Web service connector, but does not generate a MAP step for this
port. The portName MAP step sets the binding and address information for a port.
Without the location attribute, Developer cannot set the address information, and
therefore cannot generate a MAP step.
[ISS.0092.9019] Warning: Port does not have a location value, port was not generated.
Cause: Within the <port> element, the <address> element does not specify a value for the
location attribute. The location attribute specifies the network address or endpoint for
the service.
Developer generates a Web service connector, but without the network address,
Developer cannot generate a MAP step for this port. The portName MAP step set the
binding and address information for a port. In a Web service connector, the BRANCH on
'/_port' step contains a child portName MAP step for each <port> associated with the
<operation>.
[ISS.0092.9020] Error: Operation is not referenced by any binding, Web service connector was not
created.
Cause: The WSDL document does not specify a <binding> element for the <operation>.
Each <operation> within a <portType> element needs to correspond to an <operation>
element within a <binding> element. Without a binding, the WSDL document does not
provide any information about how to invoke the Web service.
Developer does not generate a Web service connector for the <operation>.
[ISS.0092.9021] Error: Input and Output messages missing, invalid operation, Web service connector
was not created.
Cause: In the WSDL document, the <operation> element within a <portType> element
does not declare an input message or an output message. For Developer to generate a
Web service connector for the <operation>, the <operation> element must contain at least
one <input> element and at least one <output> element.

[ISS.0092.9022] Error: Input message missing, Notification operations not supported. Web service
connector was not created.
Cause: In the WSDL document, the <operation> element does not declare an input
message, but it does declare an output message. In other words, the <operation> element
does not contain a child <input> element, but does contain a child <output> element. This
structure corresponds to the grammar for a notification operation. Developer does not
generate Web service connectors for notification operations.
[ISS.0092.9023] Error: Output message precedes Input message, Solicit Response operations not
supported. Web service connector was not created.
Cause: In the WSDL document, the <operation> element declares an <output> element
(output message) before the <input> element (input message). This describes a solicit-
response operation. Developer does not generate Web service connectors for solicit-
response operations.
[ISS.0092.9024] Error: HTTP binding has mime multipart Input. Multipart Input is not supported.
Binding was not generated.
Cause: The <binding> element specifies a multi-part MIME binding for the operation.
webMethods Developer does not support this type of binding.
unique binding associated with an operation.
[ISS.0092.9025] Error: HTTP Binding input is of type http:urlReplacement. http:urlReplacement is not

supported. Binding was not generated.
Cause: The <binding> element specifies <http:urlReplacement> as the binding for the
operation input. Developer does not support this type of binding for the input message.
unique binding associated with an operation.
[ISS.0092.9027] Error: HTTP Binding output mime parts are missing. Binding was not generated
completely.
Cause: The <binding> element specifies MIME binding for the output message, but the
output binding does not specify a message part for the <mime:content> element or the
output binding is missing <mime:part> elements.

Developer generates the Web service connector and generates a SEQUENCE step that
corresponds to this binding. (In the Web service connector, the BRANCH on '/binding'
step contains a child SEQUENCE step for each unique binding associated with an
operation.) However, Developer does not generate a complete binding because the
output binding in the WSDL document does not provide the part name information that
Developer needs to link the service results to variables in the pipeline. Specifically, the
Web service connector does not contain the BRANCH on '/numParts' step for this
binding.
[ISS.0092.9028] Error: HTTP Binding output mime part is missing its type. Binding was not generated
completely.
Cause: The <binding> element specifies MIME binding for the output message, but the
<mime:content> element for the output binding does not specify a value for the type
attribute. The type attribute specifies the MIME type.
Developer generates the Web service connector and generates a SEQUENCE step that
corresponds to this binding. (In the Web service connector, the BRANCH on '/binding'
step contains a child SEQUENCE step for each unique binding associated with an
operation.) However, Developer does not generate a complete binding because the
output binding in the WSDL document does not provide the part name information that
Developer needs to link the service results to variables in the pipeline. Specifically, in the
Web service connector, the BRANCH on '/loopCount' step does not have a child
SEQUENCE step for linking the output message part to the pipeline.
[ISS.0092.9029] Warning: Generated Document Type, {IS document type name}, already exists in
namespace.
The IS document type that Developer generated for the input or output message already
exists in the server namespace. Developer will not generate a duplicate IS document type.
[ISS.0092.9030] Error: Input does not have a valid message reference, Web service connector was not
created.
Cause: Within the <operation> element, the message attribute for the <input> element does
not reference a <message> element within the WSDL. Developer cannot find the message
specified by the message attribute, or the message attribute does not have a value.
Note: The message attribute value must be a QName.
[ISS.0092.9031] Error: Output does not have a valid message reference, Web service connector was
not created.
Cause: Within the <operation> element, the message attribute for the <output> element
does not reference a <message> element within the WSDL. Developer cannot find the
message specified by the message attribute or the message attribute does not have a value.

Note: The message attribute value must be a QName.
[ISS.0092.9032] Error: Invalid schema definition for Input signature. Web service connector was not
created.
Cause: The XML Schema definition that contains element declarations or type definitions
for the <part> elements in the input message is invalid. Alternatively, the XML Schema
definition does not contain the element declarations or type definitions referenced by the
<part> elements. Developer does not generate a Web service connector for the
<operation>.
Note: This error message is usually accompanied by specific IS schema generation

errors. For more information about errors that occur when generating an IS schema
from an XML Schema, see Developing Integration Solutions: webMethods Developer
User’s Guide.
[ISS.0092.9033] Error: Invalid schema definition for Output signature. Web service connector was not
created.
Cause: The XML Schema definition that contains element declarations or type definitions
for the <part> elements in the output message is invalid. Alternatively, the XML Schema
definition does not contain the element declarations or type definitions referenced by the
<part> elements. Developer does not generate a Web service connector for the
<operation>.
Note: This error message is usually accompanied by specific IS schema generation

errors. For more information about errors that occur when generating an IS schema
from an XML Schema, see Developing Integration Solutions: webMethods Developer
User’s Guide.
[ISS.0092.9034] Warning: Found port with an invalid binding reference, the port was not generated.
Cause: In the WSDL document, a <port> element contains a binding attribute that
references a <binding> that does not exist within the WSDL document. Developer cannot
find the <binding> element specified by the binding attribute.
Developer generates the Web service connector, but does not generate a MAP step for
this port. The portName MAP steps set the binding and address information for a port. In
a Web service connector, the BRANCH on '/_port' step contains a child portName MAP
step for each <port> associated with the <operation>.
Note: The binding attribute value must be a QName.

[ISS.0092.9035] Warning: Found service with no ports.

Cause: In the WSDL document, a <service> element contains no <port> elements.
Developer generates a Web service connector, but if the WSDL document does not
contain any <service> elements that provide port and address information for an
operation, the Web service connector will be incomplete.
[ISS.0092.9036] Error: Could not process document. Found binding with an invalid PortType
reference, no Web service connectors were created.
Cause: In a <binding> element, the type attribute specifies a <portType> that does not exist
in the WSDL document. Developer does not generate a Web service connector.
Note: The type attribute value must be a QName.
[ISS.0092.9037] Error: HTTP Binding input type could not be found. Binding was not generated.
Cause: Developer cannot determine the input MIME type for the HTTP binding.
unique binding associated with an operation.)
[ISS.0092.9038] Error: Unknown binding style was found, binding was not created.
Cause: The <binding> element specifies a protocol other than SOAP, HTTP, or MIME.
unique binding associated with an operation.)
[ISS.0092.9040] Error: PortType name is zero length, Web service connector was not created.
Cause: In the WSDL document, the <portType> element carries the name attribute, but the
name attribute does not have a value. Developer does not generate a Web service
connector.
[ISS.0092.9041] Error: Operation name is zero length, Web service connector was not created.
Cause: In the WSDL document, the <operation> element carries the name attribute, but
the name attribute does not have a value. Developer does not generate a Web service
connector.

[ISS.0092.9043] Error: Schema Error: error text

Cause: The XML Schema definition that defines the types and elements for the input
and/or output message parts is invalid. The schema errors are listed. For information
about errors that occur when Integration Server processes an XML Schema definition, see
Developing Integration Solutions: webMethods Developer User’s Guide.
[ISS.0092.9044] Error: Document does not contain any operations, no Web service descriptors were
created.
Cause: In the WSDL document, the <portType> element does not include an <operation>
element. For Developer to generate a consumer or provider Web service descriptor, the
WSDL must contain at least one <portType> element with a valid <operation> element.
For example, any bindings other than SOAP 1.1 or SOAP 1.2 (such as those containing
HTTP-POST and HTTP-GET protocols) are not supported and result in an invalid
operation.
[ISS.0092.9102] fileName: Not a valid web service description document.

Cause: The file you selected to generate the Web service connector is not a .wsdl or .wsd
file. You can only generate Web service connectors from files with a .wsdl or .wsd file
name extension.
ITD (Developer) Errors and Warnings
[ITD.0012.0011] Web service connector created successfully but with warnings.

Cause: Developer generated the Web service connector successfully; however, warnings
occurred.
Response: Click Details on the message dialog box to view the warnings.
[ITD.0012.0012] Error occurred while creating Web service connector.

Cause: Developer did not generate a Web service connector. Click Details on the message
dialog box to view the errors.
[ITD.0031.0001] Create Web service descriptor ''{0}'' failed.

Cause: When creating a Web service descriptor (from an IS service, WSDL or UDDI), any
exception thrown in the calls are made to Integration Server or Developer. Exceptions
such as FileNotFound, are displayed with this code. Details of the cause and response
will be found in the stack trace of the exception thrown.

[ITD.0031.0002] Exception occurred while adding a header element to the Web service descriptor.
Cause: An exception is thrown while validating a header added to the Web service
descriptor. Details of the cause and response will be found in the stack trace of the
exception thrown.
[ITD.0031.0003] Exception occurred while adding a fault element to the Web service descriptor.
Cause: An exception is thrown while validating a fault added to the Web service
exception thrown.
[ITD.0031.0004] Exception occurred while adding a new Operation to the Web service descriptor.
Cause: An exception is thrown while adding a new operation to the Web service
exception thrown.
[ITD.0031.0006] WS-I analysis for the Web service descriptor failed with an exception.
Cause: An exception is thrown while analyzing WS-I compliance for a Web service
descriptor. Possible causes are: an error in the WS-I analysis tool, an error in the browser,
or cannot launch the browser at all. Details of the cause and response will be found in the
stack trace of the exception thrown.
Response: Verify the default browser is working correctly.
[ITD.0031.0007] Web service descriptor is not WS-I compliant. Attempt to the save the Web service
descriptor ''{0}'' failed.
Cause: Developer attempted to save a Web service descriptor with WS-I compliance
turned on and the WSD fails the compliance test and Developer was unable to ask the
user to save it as a non- WS-I compliant Web service descriptor.
Response: Change the WS-I compliance property for the Web service descriptor to False, and
then save the Web service descriptor manually.
[ITD.0032.0001] Cannot open a new registry session. Please check the security URL, inquiry URL, and
credentials.
Response: Verify that the URLs and credentials are correct, and that the server is running.
[ITD.0032.0002] Attempt to disconnect the registry session failed with an exception.

Cause: This is a known issue with the CentraSite repository, where the session is
disconnected but the response cannot be parsed successfully.

[ITD.0032.0003] Attempt to refresh the registry session failed with an exception.

Response: Verify that the registry server is running and accessible; disconnect and retry.
[ITD.0032.0004] Attempt to apply the filter criteria for the registry failed with an exception.
Response: Verify that the Inquiry URL is correct, and that the registry server is running
and accessible.
[ITD.0032.0005] Attempt to publish the web service to the registry failed with an exception.
Response: Verify that the Publish URL is valid and that the registry service is running.
Contact your system administrator to verify that you have the appropriate permissions.
[ITD.0032.0006] Attempt to delete the web service from the registry failed with an exception.
Response: Verify that the Publish URL is correct, and that the registry server is running
and accessible. Refresh the current view to see if the Web service is present on the
registry.
[ITD.0032.0007] Exception thrown while accessing the registry business services.

Response: Verify that the Inquiry URL is correct, and that the registry server is running
and accessible.
[ITD.0032.0008] Exception thrown while retrieving the registry business entities. Please verify the
inquiry URL and the registry is accessible or reconnect if the auth token has expired.
Response: Verify that the inquiry URL is correct and that the registry server is running.
Refresh the UDDI Registry, then retry. Disconnect and re-connect to the registry server, if
necessary.

Index
A documentation
authentication of messages 89 conventions used 9
B E
binders 62 elements, in a WSDL document 126
associate with an endpoint alias 67 encrypting messages 92
multiple 62 encryption 90
binding element Encryption element, in WSDL document 126
adding to a Web service descriptor 62 endpoint alias
associate with a binder 67
C
certificates 92 F
mapping and usage settings 98 filtering
resolution order 97 removing filters from UDDI registry 119
usage resolution order 138 Web services in a UDDI registry 118
configuring flow services
security 93 invoking a Web service connector 37
connecting to a UDDI registry 111
connectors folder, for consumer Web service H
descriptor 34 header handlers
consumer Web service descriptor 15 deleting 82
connectors 16 headers
description 32 deleting a handler 82
included policy files 135
invoking a connector 37 I
receiving security information for the connector icons, representing Web services 114
95 inbound messages 87
refreshing connectors 36 InboundSecurity element, in WSDL document 126
supporting elements 34 invoking a Web service connector 37
conventions used in this document 9 IS namespace
creating definition of 25
WSDL documents 116 local name 25
namespace name 25
D
decrypting messages 92 K
disconnecting key resolution order
from a UDDI registry 112 Web services consumer 122
docType folder Web services provider 123
for consumer Web service descriptor 34 keys 92
document types resolution order 97
viewing 58 usage order 122
usage resolution order 138

Index
M S
message authentication 89 security
options 90 associate endpoint alias with a binder 67
message direction certificate requirements 92
consumers and providers 88 certificates
definition of 87 mapping and usage settings 98
messages related to Web services 150 usage resolution order 138
messages, signing and verifying 92 certificates and keys, resolution order 97
modifying configuring 93
signature type of an operation 53 decrypting messages 92
encrypting messages 92
O encryption options 90
operations keys
modifying the signature type of a provider Web public and private 92
service descriptor 53 requirements 92
viewing document types 58 usage order 122
outbound messages 87 usage resolution order 138
OutboundSecurity element, in WSDL document 126 message authentication 89
message consumers and providers 88
message direction 87
P
message level 87
Policy element, in WSDL document 126 pass information to a Web service connector 95
policy files 91 policy file elements 126
assign to Web service descriptor 94 policy file, assign to Web service descriptor 94
elements 126 policy file, sample 134
sample 134 policy file, specify 94
specify for WS-Security 94 policy files 91
supplied with Developer 135 policy files supplied with Developer 135
program code conventions in this document 9 signature options 90
provider Web service descriptor 15 signing and verifying messages 92
description 20, 28 Username tokens 91
included policy files 135 WS-Security facillity 86
modifying the signature type 53 X.509 Certificate tokens 91
publishing a Web service SecurityPolicy element, in WSDL document 126
requirements 110 shortcuts on the UDDI Registry tab 115
to a UDDI registry 116 Signature element, in WSDL document 126
signature security
R authentication 90
refreshing Web service connectors 36 timestamps 91
removing a Web service from a UDDI registry 117 signature type
reports modifying for a provider Web service descriptor
WS-I profile conformance 42 53
requests SOA (Services Oriented Architecture)
viewing document types 58 managing Web services in 110
requirements SOAP
for publishing a Web service 110 header handlers, deleting 82
responses message header 86
viewing document types 58 SOAP messages

Index
authentication 89 W
authentication options 90 Web service connector 15, 16
consumers and providers 88 creating 32
inbound 87 invoking 37
outbound 87 receive security information 95
SOAP protocols refreshing 36
specifying for a Web service descriptor 62 Web service descriptor 15
assign security policy 94
T binders 62
timestamp element, in WSDL document 126 consumer 15, 32
timestamp security element 91 supporting elements 34
typographical conventions in this document 9 deleting a header handler 82
generation errors and warnings 150
U provider 15, 20, 28
UDDI registry refreshing connectors 36
clearing a filter 119 reporting WS-I profile conformance 42
closing a session 112 SOAP protocols 62
connecting to 111 specifying transport and communication protocol
creating a filter 118 62
creating a WSDL document 116 viewing document types 58
definition of 110 WSDL binding element 62
disconnecting from 112 WS-I compliance 41
displaying Web services 113 Web services
filtering 118 connecting to a UDDI registry 111
finding Web services in 118 connectors 16, 32
invoking a service 37 consumers 88
publishing a Web service 116 definition of 14, 114
refreshing 112 descriptors 15, 20, 28
removing a service 117 displaying in the UDDI Registry tab 113
requirements 110 filtering in UDDI registry 118
toolbar 115 finding in a UDDI registry 118
viewing in Developer 113 icons 114
Web service icons 114 invoking a connector 37
Web service properties 115 local name 25
UDDI Registry tab 113 managing in a network 110
icons 114 message authentication 89
shortcuts 115 message authentication options 90
Username tokens 91 messages related to 150
UsernameToken element, in WSDL document 126 namespaces, IS 25
providers 88
publishing to a UDDI registry 116
V
refreshing connectors for consumer Web service
viewing descriptors 36
document types for an operation 58 removing from a UDDI registry 117
UDDI registry in Developer 113 removing UDDI registry filter 119
Web service properties 115 SOA (Services Oriented Architecture) 110
viewing properties in a UDDI registry 115
WS-I profile conformance 42

Index
Web Services Description Language. See WSDL policy file, specify 94

webMethods Servicenet. See UDDI registry policy files 91
WSDL documents policy files supplied with Developer 135
binding element 62 security timestamps 91
definition of 16 signature options 90
elements 126 signing and verifying messages 92
Encryption 126 SOAP message header 86
InboundSecurity 126 Username tokens 91
OutboundSecurity 126 using version 1.0 standards 86
Policy 126 SOAP Message Security 86
SecurityPolicy 126 Username Token Profile 86
Signature 126 X.509 Certificate Token Profile 86
Timestamp 126 X.509 Certificate tokens 91
UsernameToken 126 WS-Security policy
X509Authentication 126 example of 134
generation errors and warnings 150
WS-I compliance X
reporting for a Web service 42 X.509 Certificate tokens 91
Web service descriptor 41 X509Authentication element, in WSDL document
WS-Security 126
associate endpoint alias with a binder 67
certificates
mapping and usage settings 98
requirements 92
certificates and keys, resolution order 97
configuring 93
consumers and providers, defining 88
decrypting messages 92
encrypting messages 92
encryption options 90
implementation 86
key resolution order
Web services consumer 122
Web services provider 123
keys
public and private 92
requirements 92
usage order 122
message authenticaton 89
message direction 87
message level security 87
message security options 90
pass information to a Web service connector 95
policy file elements 126
policy file, assign to Web service descriptor 94
policy file, sample 134

Web Services Developer S Guide Software Ag Documentation Web PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Web Services Developer S Guide Software Ag Documentation Web PDF

Uploaded by

Copyright:

Available Formats

Title Page

Web Services Developer’s Guide

Document ID: DEV-WS-DG-80SP1-20091204

About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2. Working with Service First Provider Web Service Descriptors . . . . . . . . . . . . . . . . . . . 19

3. Working with WSDL First Provider Web Service Descriptors . . . . . . . . . . . . . . . . . . . . 27

4. Working with Consumer Web Service Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Web Services Developer’s Guide Version 8.0 3

5. Editing Web Service Descriptor Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

6. Working with Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

7. Working with Binders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

8. Working with Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

4 Web Services Developer’s Guide Version 8.0

About Fault Handler Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

10. Authentication and Authorization for Web Service Descriptors . . . . . . . . . . . . . . . . . . 101

Web Services Developer’s Guide Version 8.0 5

Authentication and Authorization for Provider Web Service Descriptors . . . . . . . . . . . . . . . 104

11. Publishing IS Services to a UDDI Registry as a Web Service . . . . . . . . . . . . . . . . . . . . 109

A. WS-Security Key Usage Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

B. WS-Security Policy Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

6 Web Services Developer’s Guide Version 8.0

Sample Policy File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

D. JAX-RPC Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

E. Web Service-Related Errors and Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Web Services Developer’s Guide Version 8.0 7

8 Web Services Developer’s Guide Version 8.0

Web Services Developer’s Guide Version 8.0 9

For webMethods... The documentation is downloaded to...

If you want to... Go to...

10 Web Services Developer’s Guide Version 8.0

If you want to... Go to...

Web Services Developer’s Guide Version 8.0 11

12 Web Services Developer’s Guide Version 8.0

 What Is a Web Service? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Web Services Developer’s Guide Version 8.0 13

What Is a Web Service?

Using webMethods Software to Create, Publish, and Invoke

Using webMethods Software to Create Web Services

14 Web Services Developer’s Guide Version 8.0

Integration Server’s service-oriented architecture

transports HTTP/S FTP SMTP

content handlers SOAP Doc- SOAP SOAP

webMethods invoke handler

example service types Flow Java COM C

Using webMethods Software to Publish Web Services to a UDDI

Using webMethods Software to Invoke Web Services

What Are Web Service Descriptors and Connectors?

Web Services Developer’s Guide Version 8.0 15

What Is a WSDL Document?

16 Web Services Developer’s Guide Version 8.0

Security for Web Services

Backward Compatibility for Existing Web Service Connectors

Web Services Developer’s Guide Version 8.0 17

18 Web Services Developer’s Guide Version 8.0

Web Services Developer’s Guide Version 8.0 19

Creating a Service First Provider WSD

20 Web Services Developer’s Guide Version 8.0

To create a service first provider WSD

1 On the File menu, click New.

In this field... Specify...

Web Services Developer’s Guide Version 8.0 21

In this field... Specify...

22 Web Services Developer’s Guide Version 8.0