WebMethods SOAP Developer's Guide - Software AG Documentation

Title
Page
Developer Version 7.1 SOAP Developer’s Guide

Copyright
& Docu‐
ment ID
Cerebra, Glue, Infravio X‐Broker, Infravio X‐Registry, Infravio, My webMethods Server, My webMethods, webMethods Access, webMethods Administrator,
webMethods Broker, webMethods Central Configuration, webMethods Dashboard, webMethods Designer, webMethods Developer, webMethods Fabric,
webMethods Glue, webMethods Infrastructure Data Collector, webMethods Infravio X‐Broker, webMethods Infravio X‐Registry, webMethods Installer,
webMethods Integration Server, webMethods logo, webMethods Mainframe, webMethods Manager, webMethods Modeler, webMethods Monitor,
webMethods Optimize for Infrastructure, webMethods Optimize for Process, webMethods Optimize, webMethods Portal, webMethods Process Engine,
webMethods Servicenet, webMethods Task Engine, webMethods Trading Networks, webMethods Workflow, and webMethods are either registered
trademarks or trademarks of webMethods, Inc.
Acrobat, Acrobat, and Reader are registered trademarks of Adobe Systems Incorporated. Amdocs and ClarifyCRM are registered trademarks of Amdocs.
Ariba is a registered trademark of Ariba, Inc. BEA, BEA WebLogic Server, Jolt, and Tuxedo are registered trademarks, and BEA WebLogic Platform is a
trademark of BEA Systems, Inc. Action Request System, BMC Software, PATROL, and Remedy are registered trademarks of BMC Software, Inc. BroadVision
is a registered trademark of BroadVision, Inc. Chem eStandards and CIDX are trademarks of CIDX, The Chemical Industry Data Exchange. SiteMinder and
Unicenter are registered trademarks of CA, Inc. PopChart is a registered trademark of CORDA Technologies, Inc. Kenan and Arbor are registered trademarks
of Alcatel‐Lucent. Data Connection and SNAP‐IX are registered trademarks of Data Connection Corporation. D&B and D‐U‐N‐S are registered trademarks of
Dun & Bradstreet Corporation. Eclipse is a trademark of Eclipse Foundation, Inc. Entrust is a registered trademark of Entrust, Inc. papiNet is a registered
trademark of the European Union and the United States. Financial Information eXchange, F.I.X, and F.I.X Protocol are trademarks of FIX Protocol Ltd.
UCCnet and eBusinessReady are registered trademarks, and 1SYNC and Transora are trademarks of GS1 US. Hewlett‐Packard, HP, HP‐UX, OpenView, PA‐
RISC, and SNAplus2 are trademarks of Hewlett‐Packard Company. i2 is a registered trademark of i2 Technologies, Inc. AIX, AS/400, CICS, ClearCase, DB2,
Domino, IBM, Informix, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390, OS/400, RACF, RS/6000, SQL/400, S/390, System/390, VTAM, and WebSphere, and
z/OS are registered trademarks; and Communications System for Windows NT, DB2 Universal Database, IMS, MVS, and SQL/DS are trademarks of IBM
Corporation. InnoDB is a trademark of Innobase Oy. Itanium is a registered trademark of Intel Corporation. Linux is a registered trademark of Linus
Torvalds. W3C is a registered trademark, and X Window System is a trademark of the Massachusetts Institute of Technology. MetaSolv is a registered
trademark of Metasolv Software, Inc. ActiveX, Microsoft, Outlook, Visual Basic, Visual SourceSafe, Windows, Windows NT, and Windows Server are
registered trademarks of Microsoft Corporation. Six Sigma is a registered trademark of Motorola, Inc. Firefox and Mozilla are registered trademarks of the
Mozilla Foundation. MySQL is a registered trademark of MySQL AB. nCipher is a trademark of nCipher Corporation Ltd. Eclipse is a trademark of Eclipse
Foundation, Inc. Entrust is a registered trademark of Entrust, Inc. papiNet is a registered trademark of the European Union and the United States. Financial
Information eXchange, F.I.X, and F.I.X Protocol are trademarks of FIX Protocol Ltd. UCCnet and eBusinessReady are registered trademarks, and 1SYNC and
Transora are trademarks of GS1 US. Hewlett‐Packard, HP, HP‐UX, OpenView, PA‐RISC, and SNAplus2 are trademarks of Hewlett‐Packard Company. i2 is a
registered trademark of i2 Technologies, Inc. AIX, AS/400, CICS, ClearCase, DB2, Domino, IBM, Informix, Infoprint, Lotus, Lotus Notes, MQSeries, OS/390,
OS/400, RACF, RS/6000, SQL/400, S/390, System/390, VTAM, and WebSphere, and z/OS are registered trademarks; and Communications System for Windows
NT, DB2 Universal Database, IMS, MVS, and SQL/DS are trademarks of IBM Corporation. InnoDB is a trademark of Innobase Oy. Itanium is a registered
trademark of Intel Corporation. Teradata is a registered trademark of NCR Corporation. Netscape is a registered trademark of Netscape Communications
Corporation. ServletExec is a registered trademark, and New Atlanta is a trademark of New Atlanta Communications, LLC. SUSE is a registered trademark
of Novell, Inc. Appia is a registered trademark and Javelin Technologies is a trademark of NYFIX, Inc. CORBA is a registered trademark of Object
Management Group, Inc. JD Edwards, OneWorld, Oracle, PeopleSoft, Siebel, and Vantive are registered trademarks; and Infranet, PeopleSoft Pure Internet
Architecture, Portal, and WorldSoftware are trademarks of Oracle Corporation. Perforce is a trademark of Perforce Software. JBoss and Red Hat are
registered trademarks of Red Hat, Inc. PIP and RosettaNet are trademarks of RosettaNet, a non‐profit organization. SAP and R/3 are registered trademarks
of SAP AG. PVCS is a registered trademark of Serena Software, Inc. SWIFT and SWIFTNet are registered trademarks of Society for Worldwide Interbank
Financial Telecommunication SCRL. SPARC and SPARCStation are registered trademarks of SPARC International, Inc. BAAN and SSA are registered
trademarks; and SSA Global is a trademark of SSA Global Technologies, Inc. EJB, Enterprise JavaBeans, Java, JavaServer, JDBC, JSP, J2EE, Solaris, Sun, and
Sun Microsystems are registered trademarks; and Java Naming and Directory Interface, JavaServer Pages, SOAP with Attachments API for Java, and SunSoft
are trademarks of Sun Microsystems, Inc. Sybase is a registered trademark of Sybase, Inc. VERITAS is a registered trademark, and VERITAS Cluster Server is
a trademark of Symantec Corporation. UNIX is a registered trademark of The Open Group. Unicode is a trademark of Unicode, Inc. VeriSign is a registered
trademark of Verisign, Inc.
Software AG and all Software AG product names are either trademarks or registered trademarks of Software AG.
Other product and company names mentioned herein may be the trademarks of their respective owners.
Copyright © 2007 webMethods, Inc. All rights reserved.
Copyright © 2007 Software AG and/or its suppliers, Uhlandstrasse 12, 64297 Darmstadt, Germany. All rights reserved.
Document ID: DEV-SOAP-DG-71-20070831

Contents
Contents
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 1. Overview of SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

What is SOAP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
What Does a SOAP Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
The Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
The SOAP Namespace Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
The Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
SOAP 1.1 Header Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
SOAP 1.2 Header Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
The Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
SOAP Fault Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Trailers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Chapter 2. SOAP Support on the webMethods Integration Server . . . . . . . . . . . . . . . . . . 21

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
SOAP Versions Supported by webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . 22
Receiving SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Sending SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Sending SOAP RPC Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Chapter 3. Building Solutions with SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Building Solutions that Receive SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
What is a SOAP Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
SOAP Processors Provided by the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Universal Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Implicit and Explicit Universal Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
The Universal Name Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Services You Use to Interact with the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Building Solutions that Send SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
SOAP Developer’s Guide Version 7.1 3

Contents
Chapter 4. Using the Default SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Accessing the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Behavior of the Default SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
How the Processor Selects the Target Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
What if the Requested Service Does Not Exist? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Processor Inputs and Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Building Target Services for the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
How to Create a Target Service for the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Example—Target Service for Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Chapter 5. Composing and Sending SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Composing a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
How to Compose a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Example—Composing a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Sending a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
How to Send a SOAP Message via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Example—Sending a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Chapter 6. Using the SOAP RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Using pub.client:soapRPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Example—Submitting a Remote Procedure Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
The Message Coder and the RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Encoding the Input Parameters for the Remote Procedure Call . . . . . . . . . . . . . . . . . . . . . . . . . 74
Encoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Encoding Multi-Referenced Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Decoding the Output Parameters from a Remote Procedure Call . . . . . . . . . . . . . . . . . . . . . . . 76
Decoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Decoding Multi-Referenced Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Appendix A. SOAP Faults Returned by the Integration Server . . . . . . . . . . . . . . . . . . . . . 79

Basic Structure of a SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Elements of a SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Example—Unknown SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Example—Exception While Processing Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
webMethods SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Contents
Appendix B. Encoding/Decoding Data-Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

XML-to-Java Mappings (Decoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Data types from http://schemas.xmlsoap.org/soap/encoding/ . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Data types from http://www.w3.org/1999/XMLSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Data types from http://www.w3.org/2000/10/XMLSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Data types from http://www.w3.org/2001/XMLSchema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Java-to-XML Mappings (Encoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
webMethods to XML Mappings (Encoding & Decoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Data types from http://www.webmethods.com/2001/10/soap/encoding . . . . . . . . . . . . . . . . . . . 112
Appendix C. SOAP-Related Server Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

SOAP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Appendix D. Using the SOAP RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

What is the RPC Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
What Does a SOAP RPC Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
QNames and Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
What Does a Results Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Behavior of the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Building Target Services for the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Example—Target Service for the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
The Message Coder and the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Encoding/Decoding Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Decoding the Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Transforming Input Parameters into a Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Parameters that are Not in the Input Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Decoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Decoding Multi-Referenced Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Decoding and Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Validating Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Encoding the Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Transforming Output Parameters to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Encoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Encoding Multi-Referenced Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Contents
Appendix E. Creating Custom SOAP Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

What is a Custom SOAP Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Accessing a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Building a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Inputs and Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
How to Create a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Returning Your Own SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Example—Custom Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Registering a SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
How to Register a SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Viewing the List of Registered SOAP Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Deactivating a Registered SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

About This Guide
About This Guide
Welcome to the SOAP Developer’s Guide. This guide describes how to use the webMethods
Integration Server to exchange SOAP messages over the Internet.
It is for solution developers who need to understand:
How to receive and process SOAP messages and SOAP remote procedure calls with
the webMethods Integration Server.
How to submit SOAP messages and SOAP remote procedure calls to other servers.
Document Conventions
Convention Description
Bold Identifies elements on a screen.
Italic Identifies variable information that you must supply or change
based on your specific situation or environment. Identifies terms the
first time they are defined in text. Also identifies service input and
output variables.
Narrow font Identifies storage locations for services on the webMethods
Integration Server using the convention folder.subfolder:service.
Typewriter Identifies characters and values that you must type exactly or
font messages that the system displays on the console.
UPPERCASE Identifies keyboard keys. Keys that you must press simultaneously
are joined with the “+” symbol.
\ Directory paths use the “\” directory delimiter unless the subject is
UNIX‐specific.
[ ] Optional keywords or values are enclosed in [ ]. Do not type the [ ]
symbols in your own code.
Additional Information
The webMethods Advantage Web site at http://advantage.webmethods.com provides you
with important sources of information about webMethods products:
Troubleshooting Information. The webMethods Knowledge Base provides
troubleshooting information for many webMethods products.

About This Guide
Documentation Feedback. To provide feedback on webMethods documentation, go to
the Documentation Feedback Form on the webMethods Bookshelf.
Additional Documentation. Starting with 7.0, you have the option of downloading the
documentation during product installation to a single directory called
“_documentation,” located by default under the webMethods installation directory. In
addition, you can find documentation for all webMethods products on the
webMethods Bookshelf.

Chapter 1. Overview of SOAP
What is SOAP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
What Does a SOAP Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

1. Overview of SOAP
What is SOAP?
The Simple Object Access Protocol (SOAP) is a standard, lightweight protocol for
exchanging messages across the Internet. It uses XML to define a basic message packet
that can be used to convey an arbitrary XML document or a remote procedure call (RPC).
What Does a SOAP Message Look Like?

A SOAP message uses XML to form a simple message packet. The packet consists of an
envelope that encloses two elements: an optional header and a mandatory body.
A simple SOAP message packet

SOAP
Envelope <SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/1999/XMLSchema"
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
SOAP Header
(optional) <SOAP-ENV:Header>
<MSG:priority xmlns:MSG="http://www.gsx.com/gl/">9</MSG:priority>
</SOAP-ENV:Header>
SOAP Body
<SOAP-ENV:Body>
<JournalEntry xmlns="http://www.gsx.com/gl/">
<entry>
<Id>2398</Id>
<amt>237.50</amt>
<acct>Cash</acct>
</entry>
</JournalEntry>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Note: Although not shown in the example above, SOAP 1.1 also allows additional,
implementation‐specific elements to follow the body of a SOAP message. In this book,
such elements are referred to as trailers. For more information about trailers, see “Trailers”
on page 18. Trailers are not supported with SOAP 1.2.

1. Overview of SOAP
The Envelope
The envelope is the top‐level element in a SOAP message. It is the “container” that holds
the entire message. The envelope must be the first (that is, the outermost) element in a
SOAP message. It has the name Envelope.
The envelope may contain a header element. When a SOAP message contains a
header, the header element must be the first child within the envelope. For additional
information about the header element, see “The Header” on page 12.
The envelope must contain a body element. The body carries the content of the
message. For more information about the body element see “The Body” on page 15.
The envelope must be associated with a SOAP namespace. The SOAP namespace
serves as the qualifier for the message’s SOAP‐related elements and attributes. It also
specifies the XML schema to which the message conforms. For additional information
about the SOAP namespace, see “The SOAP Namespace Declaration” below.
The envelope may include other implementation‐specific namespace declarations.
The envelope may contain the encodingStyle attribute, which specifies the way in which
the elements within the envelope are serialized and deserialized.
The envelope may contain additional implementation‐specific attributes, but if it
does, these attributes must be namespace qualified.
The envelope may contain additional implementation‐specific children besides the
header and body elements; however, if it does, the additional elements must be
namespace qualified and must follow the body element.
The SOAP Namespace Declaration

The primary purpose of the SOAP namespace is to distinguish SOAP‐related elements
and attributes from the application‐specific elements and attributes conveyed in the
message. The SOAP namespace also serves another purpose; it specifies the schema to
which the SOAP message conforms.
A SOAP 1.1 message uses the namespace http://schemas.xmlsoap.org/soap/envelope/ to qualify
the elements and attributes that make up the SOAP message packet. A SOAP 1.2 message
uses the namespace http://www.w3.org/2003/05/soap-envelope/. A SOAP message must declare
this namespace in the SOAP envelope. By convention, the prefix SOAP-ENV (for SOAP 1.1)
and env (for SOAP 1.2) is given to the SOAP namespace; however, a message may use any
prefix to represent the SOAP namespace.

1. Overview of SOAP
<SOAP-ENV:Envelope
The SOAP namespace
is declared in the
envelope element... xmlns:xsd="http://www.w3.org/1999/XMLSchema"
<SOAP-ENV:Header>
.
.
.
...and is used to qualify </SOAP-ENV:Header>
the elements and <SOAP-ENV:Body>
attributes that make up .
the SOAP packet. .
.
</SOAP-ENV:Body>
Messages that conform to the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May
2000 use the namespace http://schemas.xmlsoap.org/soap/envelope/ and those that conform to the
SOAP 1.2 W3C Recommendation 27 April 2007 specification use the namespace
http://www.w3.org/2003/05/soap-envelope/.
Messages whose envelopes declare a different namespace, or no namespace, are
considered invalid and are rejected by Integration Server.
Note: Unless otherwise noted, when the namespace prefix SOAP-ENV appears in this book,
it represents the namespace http://schemas.xmlsoap.org/soap/envelope/.
The Header
A SOAP message can include an optional header component to store additional
information. The header element provides a place where a sender can pass auxiliary,
implementation‐specific information such as authorization codes, routing information,
version numbers, or message IDs. For example, if your solution routes invoices through
one or more approval steps before passing it to an accounts‐payable processor, the header
could hold the document’s routing information.
When a header is included in a SOAP message, it must appear as the first child element
within the envelope and must have the name Header. A header may contain one or more
child elements. Each child is referred to as a header entry. All header entries must be
namespace qualified.

1. Overview of SOAP
Important! The inclusion of a header component and the information it stores are
implementation‐specific. The SOAP specification does not define any standard header
entries. It simply provides the header as a container that implementers can use as needed.
The parties exchanging SOAP messages are responsible for defining header entries for
processing them.
The following example shows a SOAP envelope containing a single header entry called
<MSG:priority>. Note that the entry is namespace qualified, which is a requirement of all
header entries in a SOAP message.
Soap 1.1 message with single header entry
<SOAP-ENV:Envelope
This message has a xmlns:xsd="http://www.w3.org/1999/XMLSchema"
header... xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
...containing one entry <SOAP-ENV:Header>
<MSG:priority xmlns:MSG="http://www.gsx.com/">9</MSG:priority>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
.
.
.
</SOAP-ENV:Body>
Soap 1.2 message with single header entry
<?xml version="1.0" encoding="UTF-8"?>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
> xmlns:xml="http://www.w3.org/XML/1998/namespace"
> xmlns:xsd="http://www.w3.org/2001/XMLSchema"
> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-envelope"
> xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-encoding">
> <MSG:priority xmlns:MSG="http://www.gsx.com/">9</MSG:priority>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
.
.
.
</SOAP-ENV:Body>

1. Overview of SOAP
SOAP 1.1 Header Attributes

The SOAP 1.1 specification defines the following optional attributes for a header entry.
These attributes allow an entry to specify its intended recipient and to indicate whether
the recipient is required to process the entry.
Attribute Description
actor Identifies the intended recipient of the header entry. This attribute
allows a sender to direct a header entry to a specific process.
mustUnderstand Indicates whether processing of the header entry is mandatory.
Recipients that do not recognize an entry whose mustUnderstand
attribute is set to 1 must reject the message and return a fault to the
client.
The following example shows a SOAP 1.1 header entry that uses both the actor and
mustUnderstand attributes.
Message that uses the “actor” and “mustUnderstand” attributes
.
.
.
<SOAP-ENV:Header>
<MSG:nextDest xmlns=MSG:"http://www.gsx.com/"
SOAP-ENV:actor="http://www.gsx.com/msgRouter"
SOAP-ENV:mustUnderstand="1"
SOAP-ENV:mustUnderstand="1">
rubicon:5555
</MSG:nextDest>
</SOAP-ENV:Header>
.
.
.
For more information about using the actor and mustUnderstand attributes, see the Simple
Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at
http://www.w3.org/TR/SOAP/#_Toc478383498.
SOAP 1.2 Header Attributes

The SOAP 1.2 specification defines the optional attributes for a header entry.

1. Overview of SOAP
Attribute Description
encodingStyle Identifies the usage of encoding rules to serialize parts of a SOAP
message.
role Identifies the SOAP node to which a particular SOAP header entry is
targeted.
mustUnderstand Identifies whether processing of the header entry is mandatory.
Recipients that do not recognize an entry whose mustUnderstand
attribute is set to 1 must reject the message and return a fault to the
client.
relay Identifies whether a header entry targeted at a SOAP receiver must be
relayed, if it is not processed.
The following example shows a SOAP 1.2 header entry that uses both the role and
mustUnderstand attributes.
Message that uses the “role” and “mustUnderstand” attributes
.
.
.
This header entry... <SOAP-ENV:Header>
<<MSG:nextDest> xmlns:hb1="http://example.org/hb1"
SOAP-ENV:actor="http://www.gsx.com/msgRouter"
SOAP-ENV:role="http://example.org/Qos"
SOAP-ENV:mustUnderstand="1">
...uses both the role rubicon:5555
and mustUnderstand
attributes </MSG:nextDest>
</SOAP-ENV:Header>
.
.
For more information about using the role and mustUnderstand attributes, see the SOAP 1.2
W3C Recommendation 27 April 2007 at http://www.w3.org/TR/2003/REC‐soap12‐part1.
The Body
When a SOAP message conveys an arbitrary XML document (sometimes referred to as
application data or the business payload), the document is carried in the body of the message.
When SOAP is used as an RPC protocol, the body specifies the method name that the
client is calling and carries the method’s input values.
A SOAP message must contain a body element. This element must be named Body. If a
SOAP message contains a header, the Body element must appear immediately after the
header. Otherwise, the body must be the first element in the SOAP envelope.
Each immediate child of the Body element is referred to as a body entry.

1. Overview of SOAP
A body containing one entry
.
.
.
<SOAP-ENV:Body>
<GL:JournalEntry xmlns:GL="http://www.gsx.com/gl/">
<transaction>
<entry>
<Id>2398</Id>
<amt>237.50</amt>
<acct>Cash</acct>
</entry>
<entry>
<Id>2398</Id>
<amt>-237.50</amt>
<acct>AR</acct>
</entry>
</transaction>
</GL:JournalEntry>
</SOAP-ENV:Body>
.
.
.
A body containing two body entries
.
.
.
<SOAP-ENV:Body>
<RQ:customer xmlns:RQ="http://www.gsx.com/rfq/">
<acctNo>AGT-432398</acctNo>
<name>GSX Sporting Goods</name>
<phone>218-376-2500</phone>
</RQ:customer>
<RQ:addr xmlns:RQ="http://www.gsx.com/rfq/">
<street1>1501 Bridger Hwy<street1>
<street2></street2>
<city>Laurel</city>
<state>MN</state>
</RQ:addr>
</SOAP-ENV:Body>
.
.
.
Note: Although a SOAP message must contain a body, the body does not have to contain
data. A message that has an empty Body element is a valid SOAP message.

1. Overview of SOAP
SOAP Fault Elements

The SOAP specification defines one body element, whose name is Fault. A recipient must
return the Fault element if it cannot process a SOAP message successfully. SOAP 1.2 faults
are structured differently than SOAP 1.1.
The SOAP 1.1 fault element contains the following child elements:
Element Value
<faultcode> A qualified name indicating the type of error that occurred. The
SOAP specification defines several standard error codes (for
example, SOAP-ENV:Server, SOAP-ENV:Client). See
http://www.w3.org/TR/2000/NOTE‐SOAP‐20000508/ for details.
<faultstring> A string describing the fault that occurred.
<faultactor> Optional. A URI indicating which process or application produced
the fault.
<detail> Optional. An element containing implementation‐specific details
about the error. This element must be present if the error occurs
while processing the body of the message. For a description of the
detail element returned by Integration Server, see Appendix A,
“SOAP Faults Returned by the Integration Server”.
The SOAP 1.2 fault element contains the following child elements:
Element Value
Code An element containing the child value <env:Value> with value of
Version Mismatch, mustUnderstand, dataEncodingUnknown,
Sender, Receiver, and the optional sub elements <env:Subcode> and
<env:Value>.
Reason An element intended to provide a human readable explanation of
the fault. The value is in the form of a string.
Node Optional. A URI for the SOAP node that generated the fault.
Role Optional. The role played by the node that generated the fault.
Detail Optional. An element containing implementation‐specific details
about the error. This element must be present if the error occurs
while processing the body of the message. For a description of the
detail element returned by the webMethods Integration Server, see
Appendix A, “SOAP Faults Returned by the Integration Server”.
Note: Faults must be namespace‐qualified with the namespace
http://www.w3.org/2003/05/soap‐envelope.

1. Overview of SOAP
The following shows an example of the SOAP 1.1 fault that the Integration Server returns
when a sender submits a message to a non‐existent SOAP processor.
A SOAP message returning a fault
<SOAP-ENV:Envelope
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
A fault is returned in the <SOAP-ENV:Body>
body of a message
<SOAP-ENV:Fault>
<faultcode>
SOAP-ENV:Server
</faultcode>
<faultstring>
[ISS.0088.9123] Requested SOAP processor
mySoapProc is not registered on this server
</faultstring>
<faultactor>
http://localhost:5555/soap/mySoapProc
</faultactor>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
When you write clients that submit SOAP messages to the Integration Server, your client
code should test for the presence of a fault code and process the response appropriately.
For information about when and how the Integration Server returns a SOAP fault, see
Appendix A, “SOAP Faults Returned by the Integration Server”.
Trailers
The SOAP 1.1 specification permits additional implementation‐specific elements
(elements besides a header and a body) to reside in a SOAP envelope. The Integration
Server refers to these elements as trailers. If a SOAP envelope carries trailers, they must
appear after the body and they must be namespace qualified.
Important! SOAP 1.2 does not support trailers. If you are designing a new solution,
Software AG recommends against the use of trailers. However, if you exchange SOAP
messages with older systems that use trailers, Integration Server provides services that
allow them to work.

1. Overview of SOAP
A SOAP 1.1 message containing two trailers
<SOAP-ENV:Envelope
<SOAP-ENV:Header xmlns:MSG="http://www.gsx.com/">
<MSG:priority>9</MSG:priority>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<GL:JournalEntry xmlns:GL="http://www.gsg.com/gl/">
<transaction>
<entry>
<amt>237.50</amt>
<acct>Cash</acct>
</entry>
</transaction>
</GL:JournalEntry>
trailer </SOAP-ENV:Body>
<AUDIT:TransInfo xmlns:AUDIT="http://www.etrans.com/monitor/>
<server>14.226.151.96</server>
<port>5540</port>
<time>2001-06-13 16:00:00 5</time>
<node>http://www.gsx.com/clearInv</node>
trailer </AUDIT:TransInfo>
<AUDIT:TransInfo xmlns:AUDIT="http://www.etrans.com/monitor>
<server>20.117.70.33</server>
<port>8081</port>
<time>2001-06-13 16:00:04 5</time>
<node>http://www.gsx.com/updateCustAcct</node>
</AUDIT:TransInfo>
Trailers allow you to transmit information in a SOAP message without placing it in the
body or the header of the message. Although used infrequently, they are permitted by the
SOAP 1.1 specification and they provide a mechanism that you can use to deliver
information to a pre‐processor, a message handler or some other intermediate process
without trespassing on the message’s header or body.

1. Overview of SOAP

Chapter 2. SOAP Support on the webMethods Integration
Server
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Receiving SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Sending SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Sending SOAP RPC Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

2. SOAP Support on the webMethods Integration Server
Overview
Support for SOAP is delivered by a SOAP message handler and a set of built‐in services.
These facilities allow you to:
Receive and process SOAP messages via HTTP or HTTPS.
Submit SOAP messages to other servers via HTTP or HTTPS.
Compose and decompose SOAP messages using a set of built‐in services.
Use RPC‐Encoded, RPC‐Literal or Document‐Literal messaging for SOAP 1.1 requests
and Document‐Literal messaging for SOAP 1.2 requests.
Make Integration Server services available to clients via RPC‐Encoded or Document‐
Literal bindings. For more information about bindings, see the Web Services
Developerʹs Guide.
SOAP Versions Supported by webMethods Integration Server

The webMethods Integration Server supports SOAP 1.1 as described in Simple Object
Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/ and
SOAP 1.2 as described in SOAP 1.2 W3C Recommendation 27 April 2007 at
http://www.w3c.org/TR/soap12‐part1/.
Receiving SOAP Messages with the Integration Server

The following diagram illustrates the process by which Integration Server receives and
processes SOAP messages.

Processing and receiving a SOAP request
webMethods Integration Server
SOAP Message Handler

1 2
HTTP HTTP
Client Listener-
Dispatcher
4
SOAP
Default
Processor
Service
Service
Service
Service
Service
Service
Service
Service
Service
Service
Service
Stage 1 The HTTP Client Posts a SOAP Document to the Integration Server
An HTTP client submits a SOAP message by posting it to the URL for a SOAP processor
on the Integration Server. A SOAP processor is a special service that operates on SOAP
messages.
The URL for a SOAP processor has the following format:
http://hostName:portNum/soap/[processDirective]
Where... Is...
hostName The numeric IP address or name of the webMethods Integration
Server.
portNum The number of a port on which hostName accepts HTTP or HTTPS
requests.
processDirective The process directive associated with the requested SOAP processor.
The process directive is a unique name that you assign to a SOAP
processor when you register it on the Integration Server. If
processDirective is omitted or set to “default,” the message is passed
to the default SOAP processor. The Web Services processor is the
default processor; provided with webMethods Integration Server.

Stage 2 The SOAP Message Handler Invokes the Appropriate SOAP Processor
When the Integration Server receives a message for a SOAP processor, it passes the
message to the SOAP message handler, which does the following:
Verifies that the requested SOAP processor is registered on the server. If the SOAP
processor does not exist or is not available, the message handler returns a SOAP fault
containing the ISS.0088.9123 or ISS.0088.9111 error. (For a description of these
error messages, see Appendix A, “SOAP Faults Returned by the Integration Server”.)
Verifies that the message declares the appropriate SOAP namespace. If the message
does not declare a namespace or declares a namespace other than
http://schemas.xmlsoap.org/soap/envelope/ (SOAP 1.1) or http://www.w3.org/2003/05/soap-
envelope/ (SOAP 1.2), the message handler returns a SOAP fault containing the
ISS.0088.9128 error.
Validates the structure of the message against the SOAP schema (if the SOAP
processor requests message validation). If the message violates the SOAP schema, the
message handler returns a SOAP fault containing the ISS.0088.91125 error.
During the validation step, the message handler validates the structure of the SOAP
envelope only. For example, it ensures that the message has at least one body element
and only one header element.
Important! Validating the application data that is carried inside the SOAP envelope is the
responsibility of the processor or application that consumes the SOAP message.
After the message handler establishes that the SOAP processor is available and has
received a valid SOAP message, the message handler does the following:
Transforms the message into a soapRequestData object. This object contains the entire
SOAP envelope in addition to other operational values that the Integration Server
uses to manage the message internally.
Creates an empty soapResponseData object. This object is used to compose the message
to be returned to the client.
Invokes the requested SOAP processor and passes the soapRequestData and
soapResponseData objects to it.

Stage 3 The SOAP Processor Performs Work and Generates a Response
The selected SOAP processor handles the message in soapRequestData (usually by calling
other services on the webMethods Integration Server) and composes a response message
in soapResponseData.
Note: For Integration Server 7.1, the RPC processor and the use of custom SOAP
processors is deprecated. Processors built with prior versions of Integration Server are still
supported.
Stage 4 The Message Handler Returns the Response to the Client
When the SOAP processor ends or exits, the message handler generates an HTTP
response from the message contained in soapResponseData and returns it to the client.
Note: If the SOAP processor or one of the services it calls throws an exception, the message
handler automatically returns a SOAP fault to the client.
Sending SOAP Messages with the Integration Server

Besides receiving and processing SOAP messages, the Integration Server can send SOAP
messages to remote servers via HTTP.
To send a SOAP message, execute pub.client:soapHTTP with the following input parameters:
Input Parameter Description
soapRequestData The soapRequestData object containing the message that you want to
send. You construct and populate this object using the server’s
message composition services (for example, createSoapData,
addHeaderEntry, addBodyEntry).
address The URL where the SOAP message is to be sent.
Example: http://servername:5555/soap/rpc
auth Optional. The user name and password that the Integration Server
must supply when it connects to the target server.

validateSOAP Optional. Indicates whether the response message will be validated
against the SOAP schema.
Set to ... To ...
true Validate the response message and throw an exception
if the response does not conform to the SOAP schema.
false Bypass the validation process (default).
SOAPAction Optional. Value to which you want to set the SOAPAction HTTP
header.
Note: The SOAPAction header was required by the initial SOAP
specification but has since been deprecated. The Integration Server
does not use the SOAPAction header and accepts SOAP messages
that omit it. If you are designing a completely new solution, we
recommend that you avoid using the SOAPAction header. However,
if you exchange SOAP messages with systems that require a
SOAPAction header, this parameter allows you to set it.
contentType Optional. Specifies the value of Content‐Type in the HTTP header.
loadAs Optional. Specifies the format of the soapResponseData. Default is
stream for an HTTP service and byteArrayStream for an HTTPS
service.
Set to... To...
stream Return the response body as a java.io.InputStream object.
Use this setting to invoke an HTTP Web service.
bytes Return the response body as a byte array. Use this setting
if the message body will be used as input to a service that
operates on entire HTML or XML documents.
byteArray Read the response stream fully and convert to a
Stream java.io.ByteArrayStream object. This setting prevents
data loss or a truncated SOAP response if the connection
closes prematurely. Use this setting to invoke an HTTPS
Web service.
timeout Optional. Time (in milliseconds) to wait for a response from the
remote server before timing out and terminating the request. The
default value is to wait forever.

This service returns a soapResponseData object that contains the response document
returned by the target server. You use the server’s data‐retrieval services (for example,
getHeaderEntries, getBody) to retrieve information from the message.
For more information about sending SOAP messages from the Integration Server, see
“Composing and Sending SOAP Messages” on page 51.
Sending SOAP RPC Messages with the Integration Server

The Integration Server supports SOAP RPC, which allows you to make remote procedure
calls to other servers with SOAP.
Note: SOAP RPC is supported only by SOAP 1.1.
To submit a remote procedure call, you execute pub.client:soapRPC with the following basic
set of parameters:
address A string specifying the HTTP address of the server on which the
remote procedure resides. (If you are submitting the request to a
webMethods Integration Server, remember to direct it to the
RPC processor as shown in the following example.)
reqParms A document (an IData object) whose elements represent the
input parameters that are to be passed to the remote procedure.
For example, if you were to pass three string parameters, acct,
amt, and org, containing the values, Cash, 150.00 and Sales,
reqParms would contain the following:
Key Value
acct Cash
amt 150.00
org Sales
At run time, the values in reqParms are XML‐encoded by the
message coder. For a description of this process, see “Encoding
the Input Parameters for the Remote Procedure Call” on page 74.

method A document (an IData object) specifying the QName of the
requested procedure, where:
Key Description
namespaceName A string specifying the namespace portion
of the procedure’s QName.
localName A string specifying the local portion of the
procedure’s QName.
auth A document (an IData object) specifying the user name and
password that are to be submitted to the server specified in
address, where:
Key Description
type A string specifying the type of
authentication that the server uses. Set type
to basic.
user A string specifying the user name that is to
be presented to the server.
pass A string specifying the password for the
user name specified in user.
targetInputSignature Optional. A string specifying the fully qualified name of the
document type that is to be used to validate and encode the
contents of reqParms. For a description of how the message coder
uses targetInputSignature, see “Encoding the Input Parameters for
the Remote Procedure Call” on page 74.
targetOutputSignature Optional. A string specifying the fully qualified name of the
document type that is to be used to validate and decode the
output value returned by the remote procedure. For a
description of how the message coder uses targetInputSignature,
see “Decoding the Output Parameters from a Remote Procedure
Call” on page 76.

SOAPAction Optional. A string specifying the value to which you want the
SOAPAction HTTP header set.
specification, but has since been deprecated. The Integration
Server does not use the SOAPAction header and accepts SOAP
messages that omit it.
If you are designing a completely new solution, we recommend
that you avoid using the SOAPAction header. However, if you
exchange SOAP messages with systems that require a
contentType Optional. A string that specifies the value of Content‐Type in the
HTTP header.
Set to... To...
text/xml; Default. Specify the content type as XML
charset=”utf-8” and the character encoding of the text as
UTF‐8.
text/xml Specify the content type as XML. Since the
charset parameter is not specified, the
character encoding of the text defaults to
US‐ASCII.
encoding Optional. Specifies the encoding method. Default value is UTF‐8.
loadAs Optional. Specifies the format of the soapResponseData. Default
value is stream for an HTTP service and byteArrayStream for an
HTTPS service.
Set to... To...
stream Return the response body as a
java.io.InputStream object. Use this option
to invoke an HTTP Web service.
byteArrayStream Read the response stream fully and convert
to a java.io.ByteArrayStream object. This
setting prevents data loss or a truncated
SOAP response if the connection closes
prematurely. Use this setting to invoke an
HTTPS Web service.

remote server before timing out and terminating the request. The
default value is to wait forever.
This service returns a document (an IData object) called respParms, which contains the
results from the remote procedure.
For information about submitting SOAP remote procedure calls from the Integration
Server, see “Using the SOAP RPC Client” on page 65.

Chapter 3. Building Solutions with SOAP
Building Solutions that Receive SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Building Solutions that Send SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

3. Building Solutions with SOAP
Building Solutions that Receive SOAP Messages

If you are building a solution that receives and processes SOAP messages, you will need
to do the following:
Understand the structure of the SOAP message that clients will submit to your
Integration Server.
Define the work that you want the Integration Server to perform when it receives the
SOAP message.
Determine whether the SOAP processor provided by the Integration Server will
satisfy the needs of your solution or whether you will need to build and register a
“custom” SOAP processor.
What is a SOAP Processor?

A SOAP processor is a service that acts upon SOAP messages that the Integration Server
receives. When the SOAP message handler receives a SOAP message, it invokes the SOAP
processor based on the process directive specified in the URL requested by the client.
The process directive is the last segment of the URL for the SOAP message handler on a
webMethods Integration Server. For example, if a client submits a SOAP request to the
following URL, the SOAP message handler would invoke the SOAP processor registered
as “genLedger.”
The process directive determines the SOAP

http://rubicon:5555/soap/genLedger processor to which the message is passed
Note: The SOAP processors that were provided with previous versions of Integration
Server are deprecated, but are still supported. Custom SOAP processors created for
previous versions of Integration Server are also deprecated.

SOAP Processors Provided by the Integration Server

The Integration Server is installed with the following SOAP processors:
SOAP Processor Description
default This is a basic processor that invokes a service based on the QName.
This processor passes the entire envelope to the services that it
invokes. The Web Services processor is the default processor
provided with Integration Server 7.1.
For information about the default processor, see “Using the Default
SOAP Processor” on page 39.
RPC This processor processes SOAP remote procedure calls (messages
that conform to the remote procedure call (RPC) section of the SOAP
specification).
For information about the RPC processor, see Appendix D, “Using
the SOAP RPC Processor”.
Note: The SOAP RPC Processor is deprecated for Integration Server
7.1. It is supported only for Web service connectors created in earlier
versions of Integration Server.
Universal Names
A universal name is a unique public identifier that external protocols use to reference a
service on a webMethods Integration Server. A QName is a qualified name, made up of a
namespace URI, a local part, and a prefix.
The SOAP processor routes messages to services based on a qualified name (QName). If
the SOAP message includes an HTTP header, the QName is derived from the SOAPAction
(SOAP 1.1) or ActionHTTP (SOAP 1.2) field of the header. If the SOAP message does not
include an HTTP header, the QName is derived from the first element in the SOAP body.
The structure of a universal name is the same as the structure of a QName in an XML
namespace and consists of two parts: a namespace name and a local name.
The namespace name is a qualifier that distinguishes a webMethods Integration Server
service from other resources on the Internet. For example, there might be many
resources with the name AcctInfo. A namespace name distinguishes one AcctInfo
resource from another by specifying the name of the collection to which it belongs
(similar to the way in which a state or province name serves to distinguish cities with
the same name—for example, Springfield, Illinois, versus Springfield, Ontario).
Like namespaces in XML, the namespace portion of a universal name is expressed as a
URI. This serves to assure uniqueness, because URIs are based on globally unique
domain names.

The namespace portion of the universal name can consist of any combination of
characters that form a valid absolute URI (relative URIs are not supported). For
example, the following are all valid namespace names:
http://www.gsx.com
http://www.gsx.com/gl/journals
http://www.ugmed.ch/résumè
For a complete description of what makes up a valid URI, see RFC 3986 Uniform
Resource Identifiers (URI): Generic Syntax at http://www.ietf.org/rfc/rfc3986.txt.
The local name uniquely identifies a service within a particular namespace. Many
webMethods users use a serviceʹs unqualified name as its local name. Under this
scheme, a service named gl.journals:closeGL would have a local name of closeGL.
Local names follow the same construction rules as NCNames in XML. Basically, a
local name can be composed of any combination of letters, digits, or the period (.),
dash (‐), and underscore (_) characters.
Additionally, it must begin with a letter or an underscore character (the _ character).
The following are examples of valid local names:
addCustOrder
authorize-Level1
générent
For specific rules relating to NCNames, see the “NCName” definition in the
Namespaces in XML specification at http://www.w3.org/TR/1999/REC‐xml‐
names‐19990114.
Note: The server normalizes Universal Names according to Unicode Normalization Form
C, as recommended by the Character Model, SOAP, and XML standards. This ensures that
names containing non‐ASCII characters (particularly those with accented or combining
characters) are represented in a standard way.
For information about normalization, see http://www.unicode.org/reports/tr15/ (Unicode
Standard Annex #15) and http://www.w3.org/TR/charmod/ (Character Model for the
World Wide Web).
Implicit and Explicit Universal Names

Every service that exists on a webMethods Integration Server has an explicit or an implicit
universal name.
An explicit universal name is a universal name that you specifically assign to a service
with Developer. When you assign an explicit universal name, you must specify both
the namespace name and the local name.

Specifying explicit universal names in Developer
You assign an
explicit universal
name on the
Properties panel in
Developer
An implicit universal name is automatically derived from the name of the service itself.

The implicit name acts as the universal name when a service does not have an explicit
universal name. The server derives an implicit name as follows:
The namespace name is the literal string http://localhost/ followed by the fully
qualified name of the folder in which the service resides on the Integration Server.
The local name is the unqualified name of the service.
The following table shows the implicit names for a variety of service names:
The service’s implicit universal name is...

Fully qualified service name Namespace name Local name
gl.journals:jrnlEntry http://localhost/gl.journals jrnlEntry

gl.journals.query:viewJournals http://localhost/gl.journals.query viewJournals
orders:postPO http://localhost/orders postPO
Important! To ensure interoperability with other vendor’s implementations of SOAP, we
recommend that you always assign explicit universal names to those services that you
want to make available to SOAP clients.
Note: Earlier versions of the webMethods SOAP implementation did not include the
http://localhost/ prefix as part of an implicit name. However, the server is backward
compatible. It will resolve QNames that clients submit in either the old form (without the
http prefix) or the new form (with the http prefix).
Note: It is possible for an implicit name to match the explicit name of another service.
When this condition exists, the explicit name takes precedence. That is, when a universal
name is requested, the Integration Server searches its registry of explicit names first. If it
does not find the requested name there, it looks for a matching implicit name.

To assign, edit, or view an explicit universal name
1 Start Developer and connect to the server on which the service resides.
2 From the Navigation panel, open the service whose universal name you want to
assign, edit, or view.
3 If you want to assign or edit the service’s universal name, specify the following in the
Universal name category of the service’s Properties panel:
In this field... Specify...
Namespace name The URI that will qualify the local name of this service. The

name can be composed of any sequence of characters except
leading and trailing white‐space characters
Local name A name that uniquely identifies the service within the
collection encompassed by Namespace name. The name can be
composed of any combination of letters, digits, or the period
(.), dash (‐), and underscore (_) characters. Additionally, it must
begin with a letter or the underscore character.
Note: Many webMethods users use the unqualified portion of
the service name as the local name.
4 On the File menu, click Save to save the new settings.
Important! When you assign an explicit universal name to a service, you must enter values
in both the Namespace name and Local name fields. If you specify one field but not the other,
you will receive an error message when you attempt to save the service. You will not be
permitted to save the service until you specify both parts of the universal name.
Note: If you move a service, or a folder containing a service, Developer retains the service’s
explicit universal name. If you copy a service or a folder containing a service, Developer
does not retain the service’s explicit universal name. You must restore the universal name
for the copied service by editing the service’s properties.
To delete an explicit universal name
1 Start Developer and connect to the server on which the service resides.
2 From the Navigation Panel, open the service whose universal name you want to
delete.

3 In the Universal name category of the service’s Properties panel, remove the current

settings from the Namespace name and Local name fields.
4 On the File menu, click Save to save the new settings.
The Universal Name Registry

The webMethods Integration Server maintains a registry, called the Universal Name
Registry, which maps explicit universal names to the services that they represent. The
registry is generated each time the Integration Server is started and is maintained in
memory while the server is running.
When you use the Developer to assign, modify, or delete a service’s universal name, you
update the Universal Name Registry. To view the contents of the registry, you can execute
the service pub.universalName:list in Developer and view the contents of the names variable
on the Results panel. (This service resides in the WmPublic package.)
Services You Use to Interact with the Registry

The following services can be used to display the Universal Name Registry or locate the
name of a service associated with an explicit universal name. For more information about
these services, see the webMethods Integration Server Built‐In Services Reference.
Service Description
pub.universalName:list Returns a document list containing the entries in the current
registry. Each document in the list represents an entry in the
registry and contains a service’s fully qualified webMethods
name and both parts of its explicit universal name.
pub.universalName:find Returns the fully qualified service name for a specified explicit
universal name.
Building Solutions that Send SOAP Messages

To build a solution that sends a SOAP message to a SOAP‐compliant server, you need to
do the following:
Define the structure of the SOAP message that you want to send.
Determine where the SOAP message will be submitted for processing (get the URL of
the server that will process the message).
Understand the structure of the SOAP message that the server will return in response
to the SOAP message that you send.
Build a service that composes the SOAP message, submits it via HTTP to the
appropriate server, and processes the response.

For information about building services that compose and send SOAP messages, see
“Composing and Sending SOAP Messages” on page 51.
For information about building a services that submit SOAP RPC messages to remote
servers, see “Using the SOAP RPC Client” on page 65.
Note: SOAP RPC messages are only supported by SOAP 1.1.

Chapter 4. Using the Default SOAP Processor
Accessing the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Behavior of the Default SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Building Target Services for the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

4. Using the Default SOAP Processor
Accessing the Default Processor

The Integration Server provides a default SOAP processor registered under the name Web
Services processor. The SOAP message handler invokes this SOAP processor when the
process directive is omitted or when the specified process directive is undefined in
Integration Server.
The following examples illustrate the two types of URLs that invoke the default processor:
You can specify the “ws”

http://rubicon:5555/soap/ws/example:calculator process directive...
—OR— ...or omit the process

directive
http://rubicon:5555/soap/
Behavior of the Default SOAP Processor

The default SOAP processor acts as a dispatcher that delegates messages to other services
on the Integration Server. It does this by invoking the service whose universal name
matches the qualified name (QName) of the message body’s first element or of the action
field in the message header. This service is referred to as the target service.
How the Processor Selects the Target Service

The default SOAP processor selects a target service by matching the fully expanded
QName to a universal name (implicit or explicit) of a service on the webMethods
Integration Server.
For example, if the default processor were to receive a SOAP message with the body
shown below, it would invoke the service whose universal name is made up of the
namespace name http://www/exprint.com/GL/ and the local name JournalEntry.
.
.
.
<SOAP-ENV:Body>
<GL:JournalEntry xmlns:GL="http://www.exprint.com/GL/">
<Id>2398</Id>
<date>03/15/2000</date>
<amt>237.50</amt>
<acct>Cash</acct>
</GL:JournalEntry>
</SOAP-ENV:Body>
.
.
.

If the default processor received a message with the body shown below, it would invoke
the service whose implicit universal name is made up of the namespace name
GL.journals.queries and the local name viewJournal. (Recall that an implicit name is derived by
combining a service’s fully qualified service name with the prefix string
http://localhost/.)
.
.
.
<SOAP-ENV:Body>
<GL:viewJournal xmlns:GL="http://localhost/GL.journals.queries">
<acct>Cash</acct>
<fromDate>01/01/2000</fromDate>
<toDate>03/31/2000</toDate>
</GL:viewJournal>
</SOAP-ENV:Body>
.
.
.
Note: The Integration Server expects the QName in the incoming SOAP message to be
normalized according to Unicode Normalization Form C. Normalization assures that
characters) are represented in a standard way. If the client has not normalized the QName,
the Integration Server might not be able to properly match it with a universal name in its
registry.
What if the Requested Service Does Not Exist?

If the default processor cannot locate the service whose universal name matches the
QName of the body’s first element or of the action field in the message header, it returns a
SOAP fault to the client with the following error: [ISS.0088.9122] Service
namespaceName:localName does not exist. See Appendix A, “SOAP Faults Returned
by the Integration Server” for information about this error.
Processor Inputs and Outputs

When the default SOAP processor calls a target service, it passes two input parameters to
the service:
soapRequestData, an object containing the entire SOAP message
soapResponseData, an object containing an empty SOAP message.
When the target service exits, the default SOAP processor returns soapResponseData to the
SOAP message handler. The message handler extracts the SOAP message from
soapResponseData and returns the message to the client.

Be aware that neither the default processor nor the SOAP message handler adds any
content to the response message in soapResponseData. It is the responsibility of the target
service to populate soapResponseData with message content.
Building Target Services for the Default Processor

To use the default SOAP processor, you must build target services that process incoming
SOAP messages. A target service can be any type of service: a flow service, a Java service,
a C/C++ service. However, it must accept a soapRequestData object and a soapResponseData
object as input. Additionally, the target service must produce a soapResponseData object
that is populated with the data that is to be returned to the client.
A target service can contain any sort of logic. A target service usually performs three basic
tasks:
It extracts the pertinent information from the incoming SOAP message.
It processes the information (usually by passing it to one or more services that
perform some type of business logic).
It composes the response SOAP message to be returned to the client.
How to Create a Target Service for the Default Processor

The following describes the general steps you take to create a target service for the default
processor.
1 Create a new service that has the following signature:
Inputs: soapRequestData (of type Object)
soapResponseData (of type Object)
Outputs: soapResponseData (of type Object)
You can use pub.soap.utils:requestResponseSpec to specify the inputs and outputs for the
service.
2 Use the SOAP data-retrieval utilities to extract information from the message. The data‐
retrieval utilities are services such as getBody and getHeaderEntries, which you use to
fetch elements from SOAP message objects. These services return the requested
element as an XML node (or an array of XML nodes). To extract data from the
returned node, you query it using the pub.xml:queryXMLNode service.

Important! Be aware that you cannot query a soapRequestData object directly. To extract
information from soapRequestData (or similar SOAP objects, such as soapData and
soapResponseData), you must use one of the data‐retrieval services to extract an
element of the message (for example, the header, the body, or the entire envelope) and
query the resulting XML node.
3 Invoke services to perform work on the extracted data. After extracting the data with which

you want to work, you can pass it to services that contain your business logic. (To
ensure that the data you have extracted is in the correct format, you might want to
validate it with pub.schema:validate or make sure that the service to which you pass the
data performs data validation on its input parameters.)
4 Use the SOAP message-composition utilities to populate soapResponseData. The message‐
composition utilities are services such as addHeaderEntry and addBodyEntry that you use
to add content to the empty message in soapResponseData.
The message‐composition services require an XML node representation of the header
entry, body entry, or trailer that you want to add to the message. You can generate an
XML node using the services pub.xml:documentToXMLString and pub.xml:xmlStringToXMLNode.
For an example of how to do this, see Step 3.1 in the sample code shown on page 45.
Note: By default, nodes that you add to a soapResponseData must be namespace
qualified. If you attempt to add a header entry or body entry that is not namespace
qualified, the server will throw an exception. For additional information, see the
pub.soap.utils:addHeaderEntry and pub.soap.utils:addBodyEntry entries in the webMethods
Integration Server Built‐In Services Reference.
5 Assign the appropriate universal name to the service. When you finish building a target

service, you must ensure that its universal name matches the QName that clients will
use to direct SOAP messages to it. In other words, the service’s universal name must
match the QName of the first element in the body or the action field in the header of
the client’s SOAP message. For information about setting a universal name, see “To
assign, edit, or view an explicit universal name” on page 36.
Note: As a best practice, we recommend that you always assign explicit universal names
to target services.
Error Handling
If a target service throws an exception while it is processing, the message handler
automatically returns a SOAP fault to the client. Depending on the type of error that
occurs, the SOAP fault may include a “detail” element, which provides specific
information about the exception. This element will include a stackTrace element if the
client is a member of the Developers or Administrators user group.

<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
When the target service throws <faultcode>
an exception, the message SOAP-ENV:Client
handler returns a SOAP fault... </faultcode>
<faultstring>
[ISS.088.9134] Exception occurred while processing body of the message
...containing an </faultstring>
error message... <faultactor>
http://hostName:portNum/soap/processorName
</faultactor>
<detail xmlns="http://www.webmethods.com/2001/10/soap/">
<exception>
<className>nameOfClassThatWasThrown</className>
...and details about <message xml:lang="en">detailedMessageIssuedbyException</message>
the error. <stackTrace xml:lang="en-US">textFromStackTrace</stackTrace>
</exception>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Note: The SOAP message returned to the client when an exception occurs contains only the
SOAP fault. It does not include any message content (for example, header entries, body
entries) that the target service may have inserted into soapResponseData before the
exception occurred.
For more information about SOAP faults, see Appendix A, “SOAP Faults Returned by the
Integration Server”.
Example—Target Service for Default Processor

The following is an example of a target service that takes a SOAP message, extracts
information from the body of the message, passes the information to a set of business
services, and composes a SOAP response containing the results of the services.
This example is located in sample.soap:targetSvc_defaultProc in the WmSamples package. You
can find the WmSamples package in the certified samples area of the Knowledge Base on
the Advantage Web Site. You may want to open this example with Developer to see how
the pipeline is mapped between steps.

Note: If you want to execute this service from Developer, enable the acquireSOAPMessage
step at the top of the flow. This service generates a test soapRequestData and
soapResponseData object, which simulates the pipeline that this service would receive from
the default SOAP processor. If you want to execute this service as a target of the default
processor, disable the acquireSOAPMessage step.
Target service that extracts data from a SOAP message and composes a response

# Description
Step 1 Extract data from SOAP Request Message. This sequence retrieves several specific

pieces of business data by extracting the body of the message from
soapRequestData and querying the result. This example expects a SOAP
message structured as follows:
<SOAP-ENV:Envelope
<SOAP-ENV:Header>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<RFQ:quoteReq xmlns:RFQ="http://www.exprint.com/orderSys">
<acct>1417-A199-0404-5POLY</acct>
<jobSpecs>
<copies>5000</copies>
<stock>30F-SIL</stock>
<ink>P440</ink>
</jobSpecs>
</RFQ:quoteReq>
</SOAP-ENV:Body>
To extract the business data from the message, this service executes the
following steps:
Step Description
1.1 getBody—This step retrieves the body of the message from
soapRequestData. It returns an XML node that represents the entire
Body element.
1.2 queryXMLNode—This step extracts the business data by executing the
following XQL queries against the XML node returned in Step 1.1.
Var Name XQL Query
acct /RFQ:quoteReq/acct/text()
stock /RFQ:quoteReq/jobSpecs/stock/text()
copies /RFQ:quoteReq/jobSpecs/copies/text()
ink /RFQ:quoteReq/jobSpecs/ink/text()

# Description
If you examine the queryXMLNode step with Developer, you will see
that it also executes the following query, which extracts the entire
Body node to a String:
Var Name XQL Query
wholeNode /source()
This query is included for debugging purposes. It allows you to
examine the raw XML associated with the Body node. If you were to
put this service into production, you would omit this query.
1.3 MAP—This step maps the results from Step 1.2 to a document that will
be processed by the business services in the next step. It also cleans up
the pipeline by dropping unneeded variables.
Step 2 Perform business logic. This sequence invokes business services that process
the data extracted by Step 1. In this example, the business services use the
data to calculate the cost of a printing job. They return the cost in a variable
named qCost.

# Description
Step 3 Compose SOAP response message. This sequence generates the response

message that carries the results back to the client. It produces a SOAP
message structured as follows:

<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
<SOAP-ENV:Header>
<AUDIT:msgInfo xmlns:AUDIT="http://www.accumon.com/msgTracker">
The service <msgType>quoteResp</msgType>
generates a <sender>http:www.exprint.com/RFQ</sender>
header entry
<docID>RFQ-0.41</docID>
called “msgInfo”..
<tStamp>20010731.155453.454</tStamp>
</AUDIT:msgInfo>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<RFQ:quoteResp xmlns:RFQ="http://www.exprint.com/orderSys">
...and a body <acct>1417-A199-0404-5POLY</acct>
entry called <jobSpecs>
“quoteResp” <stock>30F-SIL</stock>
<ink>P440</ink>
<copies>5000</copies>
</jobSpecs>
<qCost>2850</qCost>
</RFQ:quoteResp>
</SOAP-ENV:Body>
To produce this response message, the service executes the following steps:
Step Description
3.1 This sequence executes the following services to add a body entry to
soapResponseData.
Step Description
3.1.1 documentToXMLString—This service generates a
document called RFQ:quoteResp, which describes the
body entry to be inserted into soapResponseData. Then it
converts that document to XML. Note that the
document includes a field called @xmlns:RFQ, which
sets the namespace attribute in the resulting XML.

# Description
3.1.2 xmlStringToXMLNode—This step converts the XML String
to an XML node object. (Recall that to add a body entry
to soapResponseData, you must place the entry in the
pipeline as an XML node.)
3.1.3 addBodyEntry—This step adds the body entry to
soapResponseData.
3.2 This sequence executes the following services to add a header entry to
soapResponseData.
Step Description
3.2.1 documentToXMLString—This step creates a document
called AUDIT:msgInfo, which describes the header entry
to be inserted into soapResponseData and converts the
document to an XML String. Note that the document
contains a field called @xmlns:AUDIT, which sets the
namespace attribute in the resulting XML.
3.2.2 xmlStringToXMLNode—This step converts the XML String
to an XML node. (Recall that to add a header entry to
soapResponseData, you must place the entry in the
pipeline as an XML node.)
3.2.3 addHeaderEntry—This step adds the header entry to
soapResponseData.
3.3 FOR DEBUG ONLY. This step converts the contents of soapResponseData
to a String using the soapDataToString service. This allows you to
examine the finished message with Developer, which is useful during
testing and debugging. You would not include this step in a
production service.

# Description
If you examine the contents of finishedMessage on the Results panel,
you will see a SOAP message similar to the one below. If this service
were invoked through the default processor, the message handler
would send this message to the client.

Chapter 5. Composing and Sending SOAP Messages
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Composing a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Sending a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

5. Composing and Sending SOAP Messages
Overview
The Integration Server provides a set of services that allow you to generate SOAP
messages and send them across the network via HTTP.
Important! If you want to use SOAP to submit remote procedure calls, you compose those
messages with SOAP RPC client. For information about sending SOAP 1.1 RPC messages,
see “Using the SOAP RPC Client” on page 65.
Composing a SOAP Message

To compose a SOAP message, you first create an “empty” SOAP object with the
createSoapData service. Then you use the message‐composition services (for example,
addHeaderEntry and addBodyEntry) to add content to it.
Note: Although Integration Server supports incoming SOAP messages in any encoding,
SOAP messages sent from Integration Server always use the UTF‐8 character encoding.
How to Compose a SOAP Message

The following describes the general steps you take to code a service that composes a
SOAP message.
1 Create an empty SOAP object using pub.soap.utils:createSoapData. You must provide the
following input parameters. The result is an empty SOAP object named soapData in
the pipeline.
Name Description
encoding Optional. Specifies the encoding method. Default value is UTF‐8.
soapProtocol Optional. Indicates the SOAP protocol that the empty SOAP
object complies with. The default value is read from the
watt.server.SOAP.defaultProtocol property.
Set to... To...
SOAP 1.1 Indicate the SOAP object complies with SOAP 1.1.
protocol
SOAP 1.2 Indicate the SOAP object complies with SOAP 1.2.

2 Add content to soapData using any of the following message-composition services. You can
execute these services in any order.
Use this service... To...
pub.soap.utils:addHeaderEntry Add a single header entry to the message. If your
message includes multiple header entries, execute
addHeaderEntry once for each entry that you want to
add.
pub.soap.utils:addBodyEntry Add a single body entry to the message. If your
message includes multiple body entries, execute
addBodyEntry once for each entry that you want to add.
pub.soap.utils:addTrailer Add a trailer to the message. If your message includes
multiple trailers, execute addTrailer once for each trailer
that you want to add.
Note: This service is only available with SOAP 1.1.
The message‐composition services require two inputs: the soapData object to which you
are adding content and an XML node representation of the element that you want to add.
An XML node is an object that contains a parsed representation of an XML element. You
can generate an XML node, using the pub.xml:documentToXMLString and
pub.xml:xmlStringToXMLNode services. For an example of how to create an XML node, see
Step 2 and Step 3 in the sample shown on page 54.
Note: Because most SOAP implementations require namespace‐qualified header and body
entries, the addHeaderEntry and addBodyEntry services will, by default, throw exceptions if the
XML node you pass to them is not namespace qualified. This prevents you from
generating and transmitting SOAP messages that are likely to be rejected by their
recipients.
Earlier versions of the Integration Server did not enforce namespace checking. If you have
a solution that produces unqualified nodes, you can suppress the server’s default
namespace checking behavior. For information, see the
watt.server.SOAP.enforceMsgPartNS parameter description in Appendix C, “SOAP‐
Related Server Parameters”.
When you finish populating the soapData object, you use pub.client:soapHTTP to send the
SOAP message to a server via HTTP. For a detailed procedure, see “Sending a SOAP
Message” on page 57.
Example—Composing a SOAP Message

The following flow service generates a SOAP message that contains two header entries
and one body entry. This example is located in sample.soap:buildMsg_sendHTTP in the

WmSamples package. You can find the WmSamples package in the certified samples area
of the Knowledge Base on the Advantage Web Site. You may want to open this example
with Developer to see how the pipeline is mapped between steps.
Note: The following is a two‐part example. The first part illustrates how to compose a
SOAP message. This part is explained below. The second part illustrates how to send the
SOAP message. It is explained in “Sending a SOAP Message” on page 71.
Composing a SOAP message
# Description
Step 1 Create empty SOAP object. This step creates an empty SOAP object. You must

provide the following input parameters. The result is an empty SOAP object
named soapData in the pipeline.
Name Description
encoding Optional. Specifies the encoding method. Default value is
UTF‐8.
soapProtocol Optional. Indicates the SOAP protocol that the empty
SOAP object complies with. The default value is read from
the watt.server.SOAP.defaultProtocol property.
Set to... To...
SOAP 1.1 Indicate the SOAP object complies with
protocol SOAP 1.1.

# Description
SOAP 1.2 Indicate the SOAP object complies with
SOAP 1.2.
Step 2 Add header entries. This sequence builds the following header entries and
adds them to soapData:
<AUDIT:keyCode
xmlns:AUDIT="http://www.accumon.com/tracker">3</AUDIT:keyCode>
<EXP:postmark xmlns:EXP="http://www.exprint.com/inbox">
<docType>GL</docType>
<priority>09</priority>
<sender>http://www.exprint.com/acct/AP</sender>
<tStamp>20010716.0307340941</tStamp>
</EXP:postmark>
Note that both entries are namespace qualified, as required by the SOAP
specification.
Note: Instead of building header entries manually, you can use the
Integration Server’s enhanced Web service descriptor capabilities.
To accomplish this, the service executes the following steps:
Step Description
2.1 generateAuditHeader—This helper service converts a
document representation (an IData object) of the first
header entry to an XML node. (Recall that to add a header
entry to a soapData object, you must place the entry in the
pipeline as an XML node.) You can examine the helper
service to understand how this is accomplished.
2.2 addHeaderEntry—This step adds the first header entry to
soapData.
2.3 currentDate—This service generates a timestamp, which
will be inserted into the second header entry in the next
step.
2.4 generatePostmarkHeader—This helper service converts a
document representation of the second header entry to an
XML node. You can examine the helper service to
understand how this is accomplished.
2.5 addHeaderEntry—This step adds the second header entry to
soapData.

# Description
Step 3 Add body entry. This step generates the following body entry and adds it to

soapData:
<GL:journalEntry xmlns:GL="http://www.exprint.com/GL/">
<entry>
<ID>23209</ID>
<acct>cash</acct>
<amt>450.00</amt>
</entry>
<entry>
<ID>23209</ID>
<acct>AR</acct>
<amt>-450.00</amt>
</entry>
</GL:journalEntry>
To accomplish this, the service executes the following steps:
Step Description
3.1 generateBodyEntry_GL—This helper service converts a
document representation of the body entry to an XML
node. (Recall that to add a body entry to a soapData object,
you must place the entry in the pipeline as an XML node.)
You can examine the helper service to understand how this
is accomplished.
3.2 addBodyEntry—This step adds the body entry to soapData.
Step 4 FOR DEBUG ONLY. This step converts the contents of soapData to a String using
the soapDataToString service. This allows you to examine the finished SOAP
message with Developer, which is useful during testing and debugging. You
would not include this step in a production service.

# Description
If you examine the contents of string on the Results panel, you will see a
SOAP message similar to the following:
Sending a SOAP Message

To use the Integration Server to send a SOAP message to a remote server, you compose
the SOAP message in a soapData object as described in the previous section (“Composing
a SOAP Message” on page 52), and then you pass that object to pub.client:soapHTTP, which
submits it to a server that you specify.
SOAP messages that you send via soapHTTP elicit a response, which, if the target server is
SOAP compliant, will be a SOAP response document. Therefore, your service must also
include logic to process the response that the target server returns.
How to Send a SOAP Message via HTTP

The following describes the general steps you take to code a service that sends a SOAP
message to a remote server via HTTP.

1 Compose a SOAP message in a soapData object. For information about composing SOAP

messages, see “Composing a SOAP Message” on page 52.
2 Send the SOAP message to the server using pub.client:soapHTTP. This service takes the
SOAP message from the soapData object produced by step 1 and posts it to the URL
that you specify.
Note that the soapHTTP service expects to find the SOAP message in an object named
soapRequestData. If you are building a flow service, you will need to use the Pipeline tab
to map the soapData produced in step 1 to soapRequestData.)
Besides the soapData object from step 1, you must provide the following parameters to
soapHTTP:
Name Description
address A string specifying the HTTP address to which you want the
message posted.
password that the service will submit to the target server:
Name Description
type A string specifying the type of authentication that the
service will perform. Set type to basic.
user A string specifying the user name that this service
will use to access a protected resource.
password A string specifying the password that this service will
use to access a protected resource.
You may also provide the following optional parameters:
Name Description
validateSoap A string indicating whether or not you want the request and
response envelope to be validated against the SOAP schema.
Set to... To...
true Validate the SOAP envelope generated by
soapHTTP and the one received by soapHTTP.
When validateSoap is true, the service will
throw an exception if the request or
response does not conform to the SOAP
schema.

Name Description
false Bypass the validation process.
SOAPAction A string specifying the value of the SOAPAction HTTP header.
specification, but has since been deprecated. The Integration
Server does not use the SOAPAction header and accepts SOAP
messages that omit it.
If you are designing a completely new solution, we recommend
that you avoid using the SOAPAction header. However, if you
exchange SOAP messages with systems that require a
contentType A string specifying the value of Content‐Type in the HTTP
header.
Set to... To...
text/xml; Default. Specify the content type as XML
charset=”utf-8” and the character encoding of the message
text as UTF‐8.
text/xml Specify the content type as XML. Since the
charset parameter is not specified, the
character encoding of the message text
defaults to US‐ASCII.
server hosting the remote procedure before timing out and
terminating the request. The default value is to wait forever.
loadAs Optional. Specifies the format of the soapResponseData. Default is
stream for HTTP and byteArrayStream for HTTPS.
Set to... To...
java.io.InputStream object. Use this option
to invoke an HTTP Web service.

Name Description
bytes Return the response body as a byte array.
Use this setting if the message body will be
used as input to a service that operates on
entire HTML or XML documents.
byteArrayStream Read the response stream fully and convert
to a java.io.ByteArrayStream object. This
setting prevents data loss or a truncated
SOAP response if the connection closes
prematurely.
3 Use the data-retrieval services to fetch information from the response message. If the server
returns a SOAP message, soapHTTP returns the message in a SOAP object called
soapResponseData. To retrieve the data in soapResponseData, you use any of the
following data‐retrieval services.
Use this service... To...
pub.soap.utils:getBody Retrieve the body as a single XML node.
pub.soap.utils:getBodyEntries Retrieve the contents of the body as an array of XML
nodes, where each element in the array represents a
single body entry.
pub.soap.utils:getDocument Retrieve the SOAP envelope as an XML node.
pub.soap.utils:getHeader Retrieve the header as a single XML node.
pub.soap.utils:getHeaderEntries Retrieve the contents of the header as an array of
XML nodes, where each element in the array
represents a single header entry.
pub.soap.utils:getTrailers Retrieve the trailers as an array of XML nodes, where
each element in the array represents a single trailer.
The data‐retrieval services return an XML node (or an array of XML nodes) as output.
To extract information from an XML node, you can query it with the
pub.xml:queryXMLNode service. See Step 2 in the sample flow shown on page 62 for an
example of how to do this.
The soapHTTP service also returns a status parameter, which you can use to test the
results before processing them.

Output Parameter Description
soapStatus A string indicating whether the SOAP request message was
processed successfully, where:
A value of... Indicates that...
0 The remote server successfully processed the
SOAP request message and returned a SOAP
response message.
1 The remote server returned a SOAP fault,
indicating that the SOAP request message was
received, but was not processed successfully.
2 The server returned an error that was not a SOAP
fault. This indicates that some type of HTTP error
occurred (often, an HTTP 404). You can check the
status element in header to determine what type of
HTTP error occurred.
For an example of how to test these values, see Step 2 in the following example.
Example—Sending a SOAP Message

The following flow service composes a SOAP message and then sends it to a SOAP
processor at http://localhost:5555/soap/inbox.
If you want to execute this example from Developer, you must first execute
sample.soap:registerCustomProcessor to register the customProc_msgQueue service with the SOAP
message handler (it will be registered under the inbox process directive). If you are not
running the Integration Server on your local machine, modify the URL in the address
parameter in Step 1 to point to the machine where your server is running.
This example will prompt you for a user name and password when you execute it. To run
this sample successfully, you must provide a user name and password that belongs to the
Developers ACL on your Integration Server.
Note: The following example is broken into two parts. The first part illustrates how to
compose a SOAP message. This part is explained in “Composing a SOAP Message” on
page 52. The second part illustrates how to send the SOAP message. This part is explained
below.

Sending a SOAP message and processing the response
# Description
Step 1 Submit SOAP message to server via HTTP. This step sends the SOAP message to

the SOAP processor registered under the name inbox. Note that the soapData
object created in Part 1 is mapped to the soapRequestData that this step takes
as input. This step also sets the following input values:
Name Description
address This parameter is set to:
http://localhost:5555/soap/inbox
This URL assumes that the Integration Server is running on
your local machine and is listening for HTTP requests on
port 5555. If your server is running on a different machine
or port, modify the host name and port portions of this
URL.

# Description
auth This document specifies the user name and password that
this service will use to connect to the Integration Server.
These values are mapped from the userName and password
parameters that this service takes as input. (When you
execute this service from Developer, you are prompted for
these values.)
This example submits its message to the
customProc_MsgQueue processor, which is controlled by
the Developers ACL. To submit a message to this
processor, you must provide a user name and password
that belongs to the Developers ACL.
Step 2 Process response from server. This sequence processes the results from Step 1.
To determine whether the request was processed successfully, it checks the
state of the soapStatus variable:
If soapStatus is... The service...
2 Composes an error message and throws an exception. A
value of 2 indicates that an HTTP failure occurred.
1 Extracts error information from the returned message and
throws an exception. A value of 1 indicates that the remote
server returned a SOAP fault.
0 Processes the contents of soapResponseData. A value of 0
indicates that the remote server received and successfully
processed the SOAP message.
Step 3 FOR DEBUG ONLY. This step converts the contents of soapResponseData to a
String using soapDataToString. This allows you to examine the SOAP response
message with Developer, which is useful during testing and debugging. You
would not include it in a production service.

# Description
If you examine the contents of string on the Results panel, you will see a
SOAP message similar to the following:

Chapter 6. Using the SOAP RPC Client
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Using pub.client:soapRPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
The Message Coder and the RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

6. Using the SOAP RPC Client
Overview
The SOAP RPC client (pub.client:soapRPC) allows you to call procedures on remote, SOAP‐
enabled servers.
To use the SOAP RPC client successfully, you need to have the following information
about the procedure that you are calling:
The HTTP address of the server on which it resides.
The credentials (user name and password), if any, that are required to access it.
The qualified name (QName) associated with the procedure.
The names and data types of the parameters that the procedure expects as input and
returns as output.
Using pub.client:soapRPC
The following describes the general steps you take to submit a SOAP remote procedure
call from the webMethods Integration Server.
1 Invoke pub.client:soapRPC with the following input parameters:
address A string specifying the HTTP address of the server on which
the remote procedure resides. (If you are submitting the
request to a webMethods Integration Server, be sure to direct
it to the RPC processor as shown in the following example.)
Example: http://rubicon:5555/soap/rpc
reqParms A document (an IData object) whose elements represent the
input parameters that are to be passed to the remote
procedure.
For example, if you were to pass three string parameters, acct,
amt, and org, containing the values, Cash, 150.00 and Sales,
reqParms would contain the following:
Key Value
acct Cash
amt 150.00
org Sales

At run time, the values in reqParms are XML‐encoded by the
message coder. For a description of this process, see
“Encoding the Input Parameters for the Remote Procedure
Call” on page 74.
method A document (an IData object) specifying the QName of the
requested procedure, where:
Key Description
namespaceName A string specifying the namespace
portion of the procedure’s QName.
localName A string specifying the local portion of
the procedure’s QName.
password that are to be submitted to the server specified in
address, where:
Key Description
type A string specifying the type of
authentication that the server uses. Set
type to basic.
user A string specifying the user name that is
to be presented to the server.
pass A string specifying the password for the
user name specified in user.
targetInputSignature Optional. A string specifying the fully qualified name of the
document type that is to be used to validate and encode the
contents of reqParms. For a description of how the message
coder uses targetInputSignature, see “Encoding the Input
Parameters for the Remote Procedure Call” on page 74.
targetOutputSignature Optional. A string specifying the fully qualified name of the
document type that is to be used to validate and decode the
output value returned by the remote procedure. For a
description of how the message coder uses
targetInputSignature, see “Decoding the Output Parameters
from a Remote Procedure Call” on page 76.

SOAPAction Optional. A String specifying the value to which you want
the SOAPAction HTTP header set.
Note: The SOAPAction header was required by the initial
SOAP specification, but has since been deprecated. The
Integration Server does not use the SOAPAction header and
accepts SOAP messages that omit it.
If you are designing a completely new solution, we
recommend that you avoid using the SOAPAction header.
However, if you exchange SOAP messages with systems that
require a SOAPAction header, this parameter allows you to
set it.
contentType Optional. A string that specifies the value of Content‐Type in
the HTTP header.
Set to... To...
text/xml; Default. Specify the content type as
charset=”utf-8” XML and the character encoding of the
text as UTF‐8.
text/xml Specify the content type as XML. Since
the charset parameter is not specified,
the character encoding of the text
defaults to US‐ASCII.
encoding Optional. Specifies the encoding method. Default value is
UTF‐8.
loadAs Optional. Specifies the format of the soapResponseData.
Default value is stream for an HTTP service and
byteArrayStream for an HTTPS service.
Set to... To...
java.io.InputStream object. Use this
option to invoke an HTTP Web service.

byteArrayStream Read the response stream fully and
convert to a java.io.ByteArrayStream
object. This setting prevents data loss or
a truncated SOAP response if the
connection closes prematurely. Use this
setting to invoke an HTTPS Web
service.
timeout Optional. Time (in milliseconds) to wait for a response from
the server hosting the remote procedure before timing out
and terminating the request. The default value is to wait
forever.
2 Process the results returned by pub.client:soapRPC. If the remote procedure returns output

values, those values are decoded by the message coder and placed in an IData object
called respParms. For example, if the procedure returned two string parameters, status
and balance, whose values were closed and –4.95, respParms would contain the
following:
Key Value
status closed
balance -4.95
When decoding the results, the message coder uses the document type named in
targetOutputSignature (if one was specified) to validate the values in respParms. For a
description of the decoding process, see “Decoding the Output Parameters from a
Remote Procedure Call” on page 76.
Besides respParms, pub.client:soapRPC returns the following values, which you can use
to determine whether the request was processed successfully:
soapStatus A String indicating whether the remote procedure call was
processed successfully, where:
A value of... Indicates that...
0 The remote server successfully returned the
results of the remote procedure call.
1 The remote server returned a SOAP fault,
indicating that the remote procedure call was
received, but was not processed successfully.

2 The server returned an error that was not a
SOAP fault. This indicates that some type of
HTTP error occurred (often, an HTTP 404). You
can check the status element in header (below) to
determine what type of HTTP error occurred.
header A document (an IData object) containing information from the
HTTP header returned by the remote server. header contains the
following elements:
Key Value
lines A document (an IData object) in which each
entry represents a field (line) of the response
header. Key names represent the names of the
header fields and key values are Strings
containing the values of the header fields.
status A String containing the status code from the
HTTP response. For example, if the server
returns a HTTP 404 error, status will contain
404.
statusMessage A String containing the status message from the
HTTP response.
soapResponseData A SOAP object containing the entire SOAP response message.
You can extract data from this object using the data‐retrieval
services such as getBody and getHeaderEntries. (For a complete list
of data‐retrieval services, see page 60.)
Example—Submitting a Remote Procedure Call

The following flow service calls a remote procedure that takes three String parameters
(acct, amt, and loc) and returns one String parameter (authCode).
This example is located in sample.soap:buildRPC_SendHTTPSimple. You may want to examine
it with webMethods Developer to understand how its parameters are set.
The service calls a remote procedure whose QName is made up of the namespace name,
http://www.expt.com/AUTH/, and local name, getAuthCode. On a webMethods Integration
Server (version 4.6 or later) this name is registered to sample.soap:targetSvc_rpcProcSimple.
(This service resides in the WmSamples package and is described in “Example—Target
Service for the RPC Processor” on page 123. You can find this package in the certified
samples area of the Knowledge Base on the Advantage Web Site.)
To execute this example from Developer, modify the URL in the address parameter in
Step 1 to point to the machine where your Integration Server is running.

When you execute this example, you will be prompted for the following values:
For this input parameter... Enter...
acct Any string of characters.
amt A decimal value, such as 150.75 or 15.00. (Omit commas from
large values; otherwise, the value will fail validation.)
loc Any string of characters.
userName A user name that belongs to the Developers ACL.
password The password for the user name that you entered in
userName.
Example of a service that submits a remote procedure call and processes the response

# Description
Step 1 Submit remote procedure call. This step composes the remote procedure call and

submits it to the server specified in address. If you examine the pipeline, you will
see that its input parameters are set as follows:
Name Description
address This parameter is set to:
http://localhost:5555/soap/rpc
This directs the request to the RPC processor on a
webMethods Integration Server. This URL assumes that
the Integration Server is running on your local machine
and is listening for HTTP requests on port 5555. If your
server is running on a different machine or port, modify
the host name and port portions of this URL.
auth This document specifies the user name and password
that this service will use to connect to the webMethods
Integration Server. These values are mapped from the
userName and password parameters that this service
takes as input. (When you execute this service from
webMethods Developer, you are prompted for these
values.)
Note: When you submit a SOAP remote procedure call
to an Integration Server, your credentials are verified
against the ACL for the target service.
method This document specifies the QName of the remote
procedure. In this example, method is set as follows:
Key Value
namespaceName http://www.expt.com/AUTH/
localName getAuthCode
On the webMethods Integration Server, this QName
represents the universal name assigned to the service
sample.soap:targetSvc_rpcProcSimple.
reqParms This document contains the input parameters that are
to be passed to the remote procedure. Note that
authCodeReq, a document that is part of the input
signature for this example, is mapped to reqParms.

# Description
targetInputSignature This parameter is set to:
sample.soap.helpers.docTypes:docType_authCodeReq
which is the name of a document type. This parameter
tells the message coder to validate the contents of
reqParms (the input parameters for the remote
procedure) against this document type at run time. It
also instructs the message coder to encode the contents
of reqParms according to the data types specified in this
document type.
targetOutputSignature This parameter is set to:
sample.soap.helpers.docTypes:docType_authCodeResp
which is the name of a document type. This parameter
tells the message coder to validate the contents of
respParms (the results from the remote procedure)
against this document type at run time. It also instructs
the message coder to decode the contents of respParms
according to the data types specified in this document
type.
Step 2 Process response from server. This sequence processes the results from Step 1.
To determine whether the request was processed successfully, this step first
checks the state of the soapStatus parameter:
If soapStatus is... The service...
2 Composes an error message and throws an exception.
A value of 2 indicates that an HTTP failure occurred.
1 Extracts error information from the returned message
and throws an exception. A value of 1 indicates that the
remote server returned a SOAP fault.
0 Processes the contents of respParms. A value of 0
indicates that the remote server returned the results of
the requested procedure.
The Message Coder and the RPC Client

The SOAP RPC client engages the message coder to convert the input and output
parameters to and from XML.

Encoding the Input Parameters for the Remote Procedure

Call
At run time, the parameters in reqParms are converted to XML by the message coder. This
process is known as encoding. The way in which the message coder encodes the
parameters in reqParms depends on whether targetInputSignature is set.
If targetInputSignature is not set, the message coder encodes the elements in reqParms
according to their underlying Java classes. For example, if a parameter were of class
java.lang.Boolean, the message coder would encode it as xsi:type="xsd:boolean" in
the resulting XML. If the message coder does not recognize the underlying class, it
encodes the parameter as a string (it uses the object’s toString( ) method to produce
the parameter’s value).
The following table shows how the message coder would encode a parameter amt
(with a value of 500.00) depending on its Java class.
If the Java Class

were... The Message Coder would produce...
java.math.BigDecimal <amt xsi:type="xsd:decimal">500.00</amt>
java.lang.Float <amt xsi:type="xsd:float">500.00</amt>
myJavaClass <amt xsi:type="xsd:string">results of toString

method</amt>
For a list of recognized Java classes and the XML data types to which they are
converted, see Appendix B, “Encoding/Decoding Data‐Type Mapping”.
If targetInputSignature is set, the message coder first validates the contents of reqParms
against the document type specified in targetInputSignature. If the parameters in
reqParms violate the specified document type, (for example, if a required parameter is
missing or a value is not of the correct type), the message coder throws an exception.
If the parameters are valid, the message coder encodes them as follows:
If the parameter is a String, the value of the parameter is encoded according to its
Content type property. For example, if its Content type is nonNegativeInteger
{http://www.w3.org/2001/XMLSchema}, the value is encoded as an
xsi:type="xsd:nonNegativeInteger". If the Content type property is not
specified, the message coder encodes the value as a string (as though its Content
type were string {http://www.w3.org/2001/XMLSchema}).
The following table shows how the message coder would encode a String
parameter amt (with a value of 500.00) for different Content Type values.

If Content Type were... The Message Coder would produce...
decimal <amt xsi:type="xsd:decimal">

{http://www.w3.org/2001/XMLSchema} 500.00</amt>
float{http://www.w3.org/2001/ <amt xsi:type="xsd:float">

XMLSchema} 500.00</amt>
not specified <amt xsi:type="xsd:string">

500.00</amt>
If the parameter is an Object, the value of the parameter is encoded according to its

underlying Java class.
Encoding Complex Structures and Arrays

The message coder encodes documents (IData objects) as complex data types.
The message coder encodes Document Lists, String Lists, and Object Lists as SOAP arrays.
For more information about how the arrays are encoded in SOAP messages, see the
“Arrays” section in the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at
Encoding Multi-Referenced Elements

By default, the message coder generates references when encoding parameters that
reference the same underlying data in the pipeline. However, this behavior can be
modified with the watt.server.SOAP.useMultiReference parameter.
When watt.server.SOAP.useMultiReference is true, the message coder generates the
appropriate id and href attributes for parameters that reference the same underlying data.
For example, if the parameters cDate and oDate refer to the same object, the message coder
encodes them like this if watt.server.SOAP.useMultiReference=true (or is not set,
which is the server’s installed behavior):
.
.
.
<cDate id="id1">03/15/2000</cDate>
<amt id="id2">300</amt> The oDate parameter is encoded as a reference
<oDate href="#id1"></oDate>
<acct id=id4>cash</acct>
.
.
.

And encodes them like this if watt.server.SOAP.useMultiReference=false:
.
.
.
<cDate>03/15/2000</cDate>
<amt>300</amt> The oDate parameter is encoded as an independent element
<oDate>03/15/2000</oDate>
<acct>cash</acct>
.
.
.
For more information about watt.server.SOAP.useMultiReference and other SOAP‐
related server parameters, see Appendix C, “SOAP‐Related Server Parameters”. For more
information about setting server parameters, see the webMethods Integration Server
Administrator’s Guide.
Decoding the Output Parameters from a Remote Procedure

Call
When the results of a remote procedure call are returned to the SOAP RPC client, the
message coder converts them from XML and places them, as Java Objects, in respParms.
This process is known as decoding.
The way in which the message coder decodes the results depends on whether
targetOutputSignature is set.
If targetOutputSignature is not set, the output parameters are rendered according to
the data types declared in the XML. For example, it would convert a parameter whose
data type is xsi:type=xsd:decimal to a Java object of class java.math.BigDecimal. (For a
list of XML data types and the Java classes to which they are converted, see
Appendix B, “Encoding/Decoding Data‐Type Mapping”.) If an XML element does not
declare its type, the parameter is rendered as a String.
If targetOutputSignature is set, the message coder converts the output parameters
according to the document type specified in targetOutputSignature.
If targetOutputSignature declares a parameter as a String, the value is rendered as a
String object, regardless of the data type declared in the XML.
If targetOutputSignature declares a parameter as an Object, the value is rendered
according to the data type declared in the XML.
When targetOutputSignature is specified, the message coder also validates the contents
of respParms. If the parameters returned in respParms violate the document type
specified in targetOutputSignature, (for example, if a required parameter is missing or
a value is not of the correct type), the message coder throws an exception.

Decoding Complex Structures and Arrays

For complex data types (XML elements that contain child elements), the message coder
produces documents (IData objects) in the pipeline.
The message coder will create arrays of elements (that is, String Lists, Document Lists,
Object lists) for elements that are properly encoded as SOAP arrays. For more information
about how the arrays are encoded in a SOAP message, see the “Arrays” section in the
Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at
Decoding Multi-Referenced Parameters

The message coder can resolve parameters that are referenced through the href attribute as
long as the referenced value appears within the body of the SOAP message. The message
coder cannot resolve external references (references that point to resources outside of the
message) or references that point to elements outside the Body element.
Within the Body element, the href attribute may appear before or after the value that it
references. The message coder can successfully resolve either type.
.
In a backward reference, a .
referenced value appears
.
before the point where it is
referenced <cDate id="id1">03/15/2000</cDate>
<amt id="id2">300</amt>
.
.
.
.
.
.
<amt id="id2">300</amt?
In a forward reference, a <cDate id="id1">03/15/2000</cDate>
referenced value appears
.
after the point where it is
referenced .
.
For referenced elements, the message coder puts a single copy of the value in the pipeline
and generates references to it.
Note: If the message coder cannot resolve a reference, it generates a null object for that
parameter. It also reports the problem in the server log if the server is running at debug
level 5 or higher.


Appendix A. SOAP Faults Returned by the Integration Server
Basic Structure of a SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
webMethods SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

A. SOAP Faults Returned by the Integration Server
Basic Structure of a SOAP Fault

If the Integration Server is not able to process a SOAP message, it returns a SOAP fault. A
SOAP fault is a SOAP message with the following structure.
<SOAP-ENV:Envelope
xmlns:xsd="http://www.w3.org/1999/XMLSchema">
<SOAP-ENV:Body>
The body contains the Fault <SOAP-ENV:Fault>
element, which contains <faultcode>…</faultcode>
information about the failure <faultstring>…</faultstring>
<faultactor>…</faultactor>
<detail>…</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Elements of a SOAP Fault

The body of a SOAP fault contains the Fault element. When the Integration Server returns
a SOAP fault, it contains the following children:
Element Value
<faultcode> A QName indicating the class of error that occurred. The namespace
for the QName will be the same as that of the SOAP envelope and the
local name will be one of the following:
Local Name Indicates that...
Server The Integration Server was not able to process
the message because of a problem on the
server.
Client The Integration Server was not able to process
the message because it was formatted
improperly.
—OR—
Integration Server was not able to process the
message because the SOAP processor (or one
of the services it called) threw an exception.

Element Value
MustUnderstand The SOAP processor could not obey a header
element whose mustUnderstand attribute was
set to 1.
VersionMismatch The Integration Server does not support the
SOAP namespace specified in the SOAP
envelope.
<faultstring> A message describing the error. For a list of messages that might
appear in faultstring, see “webMethods SOAP Faults” on page 83.
<faultactor> A URI indicating which SOAP processor returned the error.
Example: http://rubicon:5555/soap/rpc
<detail> An element containing detailed information about the error. The
Integration Server returns this element when an exception occurs
while it is processing the message.
The <detail> element returned by the Integration Server is from the
following namespace:
http://www.webmethods.com/2001/10/soap
It contains an element called <exception>, which has the following
children and provides specific information about the exception:
Element Description
<classname> The name of the Java class that was thrown.
<message> The detailed error message from the
exception.
<stackTrace> A Java stack trace.
Important! This element is included only if the
client is a member of the Developers or
Administrators group on the webMethods
Integration Server.

Element Value
<serviceStackTrace> A service stack trace. This element is returned
if a service stack is available to the SOAP
message handler. It generally appears only
when an exception is thrown by one of the
webMethods SOAP processors or utilities.
Important! This element is included only if the
client is a member of the Developers or
Administrators group on the webMethods
Integration Server.
Example—Unknown SOAP Processor

The following is an example of the SOAP fault that the Integration Server returns when a
client directs a message to a processor that does not exist on the server.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>
[ISS.0088.9123] Requested SOAP processor inbox is not registered
on this server
</faultstring>
<faultactor>http://localhost:5555/soap/inbox</faultactor>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Note that this fault does not include the <detail> element.
Example—Exception While Processing Message

The following is an example of the SOAP fault that the Integration Server returns if an
exception is thrown while it is processing a SOAP message. Note that this fault includes
the detail element, which provides information about the exception.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>
[ISS.0088.9112] An Exception was thrown in the server
</faultstring>
<faultactor>http://localhost:5555/soap/inbox</faultactor>

<detail xmlns="http://www.webmethods.com/2001/10/soap">
<exception>
<className>com.wm.lang.flow.FlowException</className>
<message xml:lang="en-US">
[ISC.0049.9010] Failure invoking unknown service at
'unlabeledINVOKE'. The service may have been renamed, moved
or disabled.
</message>
<stackTrace xml:lang="en-US">
com.wm.lang.flow.FlowException: [ISC.0049.9010] Failure invoking unknown
service at 'unlabeledINVOKE'. The service may have been renamed, moved or
disabled. at
java.lang.Throwable.<init>(Throwable.java:84)at
java.lang.Exception.<init>(Exception.java:35)at
com.wm.util.LocalizedException.<init>(LocalizedException.java:83)at
com.wm.lang.flow.FlowException.<init>(FlowException.java:42)at
com.wm.lang.flow.FlowExit.getFailure(FlowExit.java:199)at
com.wm.lang.flow.FlowState.willExit(FlowState.java:195)at
com.wm.lang.flow.FlowSequence.invoke(FlowSequence.java:150)at
com.wm.lang.flow.FlowRoot.invoke(FlowRoot.java:199)at
com.wm.lang.flow.FlowState.invokeNode(FlowState.java:459) at
com.wm.lang.flow.FlowState.step(FlowState.java:341)at
com.wm.lang.flow.FlowState.invoke(FlowState.java:309)at
com.wm.app.b2b.server.FlowSvcImpl.baseInvoke(FlowSvcImpl.java:1334)at
com.wm.app.b2b.server.ServiceManager.invoke(ServiceManager.java:692)at
com.wm.app.b2b.server.ServiceManager.invoke(ServiceManager.java:478)at
com.wm.app.b2b.server.HTTPSOAPHandler.process(HTTPSOAPHandler.java:234)at
com.wm.app.b2b.server.HTTPDispatch.run(HTTPDispatch.java:255) at
com.wm.util.pool.PooledThread.run(PooledThread.java:103)at
java.lang.Thread.run(Thread.java:498) </stackTrace>
</exception>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
webMethods SOAP Faults

The following are SOAP‐related errors that are issued by the webMethods Integration
Server.
[ISC.0076.0013] SOAP Message Coder cannot encode output data; pipeline does not match output
signature.
Cause: The SOAP message coder could not XML‐encode the results of a SOAP remote
procedure call because a variable appeared in the pipeline more than once.
Response: On the Integration Server, examine the target service to determine why it is not
producing output values that match the output signature. Correct the serviceʹs signature
and/or logic after identifying the source of the problem.

[ISC.0076.0014] SOAP Message Coder failure; a Runtime Exception was thrown in the SOAP Coder
Cause: The message coder encountered a serious internal error.
Response: Contact Software AG Customer Care.
[ISC.0076.0015] SOAP Message Coder cannot encode variable varName; variable does not have a
valid XML name
Cause: The message coder could not XML‐encode the SOAP RPC request or response
because the pipeline contained the variable varName, whose name is not a valid name for
an XML element.
Response: This error often occurs because the variable name contains a colon. Change the
name of varName to one that is also valid as an XML element name (or map varName to a
new variable, and use that variable as your SOAP RPC input or output parameter).
[ISC.0076.0016] Soap Message Coder warning; unregistered coder for variable varName, using String
Cause: The message coder was not able to recognize the data type for varName so it treated
the variable as a String.
Note: This message is a warning that is written to the server log at debug level 5 and
higher.
Response: Check the incoming XML and verify that it declares the correct data type.
[ISC.0076.0017] SOAP Message Coder error; no coder is registered for encoding style styleName
[ISC.0076.0018] Soap Message Coder warning; unregistered coder for variable varName, using
BasicData
Cause: The message coder was not able to recognize the complex data type for varName so
it treated the variable as a document (an IData object).
higher.
Response: Check the incoming XML and verify that it declares the correct data type.

[ISC.0076.0019] SOAP Message Coder cannot decode message; encoding style styleName is not a
registered style
Cause: The message coder could not decode the submitted XML because it does not
support the specified encoding style.
Response: Check the incoming XML and verify that the encodingStyle attribute is specified
correctly and that it specifies a style that the Integration Server supports.
[ISC.0076.0020] Soap Message Coder warning; invalid HREF found reference

Cause: The message coder could not resolve the href pointing to reference. A null value was
produced instead.
higher.
Response: Examine the incoming XML and make sure that the specified reference points to
an element that exists in the body of the message.
[ISC.0076.0021] SOAP Message Coder cannot decode message; arrayType attribute value attValue is
malformed
Cause: The message coder could not decode an XML‐encoded array because it cannot
understand the value of the arrayType attribute.
Response: Check the incoming XML and make sure that the arrayType attribute is specified
correctly. For example, make sure that it is not missing a [ symbol.
[ISC.0076.0022] SOAP Message Coder cannot decode message; cannot determine type of element
elementName
Cause: The message coder could not decode the XML‐encoded parameters it has received,
because the simple element elementName has an unknown data type (for example,
xsi:type="myDataType").
Response: Check the incoming XML and make sure the data type has been specified
correctly. Also make sure that it is using the correct namespace.
[ISC.0076.0023] SOAP Message Coder cannot decode message; unable to create array for arrayType
attribute value attValue
Cause: The message coder could not decode an XML‐encoded array because it could not
allocate an array of the specified dimensions.
correctly. For example, make sure that it does not specify a negative dimension or an
invalid array size (for example, too many dimensions or dimensions that are

unrealistically large). If the array is unusually large or the server is extremely very low on
memory, the possibility also exists that this error was the result of an out‐of‐memory
condition.
[ISC.0076.9101] SOAP Encoding Registrar cannot register encoding style styleName; encoding style
already exists
Cause: The encoding registrar encountered a serious internal error.
[ISC.0076.9102] SOAP Encoding Registrar cannot register Java type typeName; Java type already
exists
Cause: The encoding registrar encountered a serious internal error.
[ISC.0076.9103] SOAP Encoding Registrar cannot register Schema type typeName; Schema type
already exists
Cause: The message code encountered a serious internal error.
[ISC.0076.9201] Null mime object received

Cause: The message coder could not decode the parameters in the SOAP message because
the message does not specify an encoding style.
Response: This error usually occurs because the SOAP encodingStyle attribute is missing,
misplaced or misspelled. Examine the RPC request that was submitted to the Integration
Server and ensure that the SOAP Envelope includes the encodingStyle attribute. Also check
that the encodingStyle attribute has the proper syntax and namespace.
[ISC.0076.9202] No data in buffer!

[ISC.0076.9203] SOAP Message Coder cannot decode message; Invalid number value
Cause: The message coder could not decode an XML‐encoded array because one of its
dimensions is set to a nonnumeric value.
Response: Check the incoming XML and make sure that the arrayType attribute specifies a
positive integer. For example, make sure it has not been inadvertently set to a nonnumeric
value such as “A”.

signature, duplicate variable varName in pipeline
Cause: The message coder could not XML‐encode the results of a SOAP remote procedure
call because the variable varName appeared in the pipeline more than once.
producing output values that match the output signature for varName. Correct the
service’s signature and/or logic after identifying the source of the problem.
[ISC.0076.9205] SOAP Message Coder cannot encode variable varName; variable does not have a
valid XML name
Cause: The message coder could not XML‐encode the SOAP RPC request or response
because the pipeline contained the variable varName, whose name is not a valid name for
an XML element.
Response: This error often occurs because the variable name contains a colon (:). Change
the name of varName to one that is also valid as an XML element name (or map varName to
a new variable, and use that variable as your SOAP RPC input or output parameter).
[ISC.0076.9206] SOAP Message Coder error; no coder is registered for encoding style styleName
[ISC.0076.9208] SOAP Message Coder cannot decode message; cannot determine type of element
elementName
Cause: The message coder could not decode the XML‐encoded parameters it has received,
because the simple element elementName has an unknown data type (for example,
xsi:type="myDataType").
Response: Check the incoming XML and make sure the data type has been specified
correctly. Also make sure that it is using the correct namespace.
[ISC.0076.9209] SOAP Message Coder cannot decode message; unable to create array for arrayType
attribute value attValue
Cause: The message coder could not decode an XML‐encoded array because it could not
allocate an array of the specified dimensions.
correctly. For example, make sure that it does not specify a negative dimension or an
invalid array size (e.g., too many dimensions or dimensions that are unrealistically large).
If the array is unusually large or the server is extremely very low on memory, the
possibility also exists that this error was the result of an out‐of‐memory condition.

[ISC.0076.9210] SOAP Message Coder cannot decode message; arrayType attribute value attValue is
malformed
Cause: The message coder could not decode an XML‐encoded array because it cannot
understand the value of the arrayType attribute.
Response: Check the incoming XML and make sure that the arrayType attribute is using the
correct syntax. For example, make sure that it is not missing a “[” symbol.
signature, required variable varName is missing
Cause: The message coder could not transform the results of a SOAP remote procedure
call because the required variable varName was not in the pipeline.
producing the required output variables. Correct the service’s signature and/or logic after
identifying the source of the problem.
signature, extra variable varName in pipeline
[ISS.0088.9102] ASSERTION: The directive directiveName in the URL urlName should be

directiveName
Cause: The SOAP message handler encountered a serious internal error.
[ISS.0088.9103] Error reading SOAP Message from HTTP stream -- appears to be empty
[ISS.0088.9105] Failed to register SOAP Handler directiveName

Cause: The Integration Server was not able to successfully add the specified SOAP
processor to the processor registry.
Response: Verify that the SOAP processor directive and fully qualified service name have
been specified correctly. This error usually occurs because the directive name or the
service name has not been specified.

[ISS.0088.9107] Failed to unregister SOAP Handler directiveName

Cause: The Integration Server was not able to successfully remove the specified processor
from the SOAP Processor registry.
Response: This error generally occurs because the registry does not contain a processor
registered to the specified directive. Verify that the process directive was specified
correctly. (Remember that directive names are case‐sensitive.) Also verify that the
specified directive is currently registered in the SOAP Processor registry. It may have
already been removed.
[ISS.0088.9108] SOAP Handler directiveName already registered

Cause: The Integration Server was not able to successfully register the SOAP processor,
because the registry already has a processor registered under the specified directive.
Response: Register the SOAP processor under a different directive. Or unregister the
processor that is currently registered to directiveName, and then register this SOAP
Processor.
[ISS.0088.9109] SOAP is only supported using HTTP POST protocol

Cause: The SOAP message handler was not able to accept the request because the SOAP
message was submitted to the Integration Server using the HTTP GET method. The SOAP
message handler only accepts requests via the POST method (per W3C specification).
Response: Modify the client to use HTTP POST to submit SOAP messages to the
Integration Server.
[ISS.0088.9110] Invalid BOOLEAN value value for variable varName; must be 0 or 1

Cause: The addHeaderEntry utility failed because the mustUnderstand attribute was not set
correctly.
Response: Check the logic in the process that failed to make sure that it sets the value of
varName to either 0 or 1. No other values are permitted when setting the mustUnderstand
attribute.
[ISS.0088.9111] Cannot load or execute the SOAP processor directiveName

Cause: The SOAP message handler cannot process the SOAP message because the
requested SOAP processor is non‐operational.
Response: On the server, check the status of the service that is registered to directiveName.
Make sure this service is loaded and operating successfully. (Frequently this error occurs
because the processor was modified and then did not recompile successfully.)

[ISS.0088.9112] An Exception was thrown in the server

Cause: The Integration Server, the SOAP processor, or one of the services processing the
message has thrown an exception.
Response: See the detail element in the SOAP fault to determine the exception that was
thrown and which process it was thrown by.
[ISS.0088.9113] The SOAP Envelope does not have a Body block

Cause: The SOAP client was given a soapRequestData that did not contain a body element.
Response: Examine the logic in the client to see whether it uses the stringToSoapData or
streamToSoapData service to generate their SOAP objects. If so, determine whether the
String or stream from which the SOAP object was generated represented a valid SOAP
message. Also check whether the SOAP processor or client used any of the data removal
utilities (such as removeHeaderEntry or removeBodyEntry) and might have inadvertently
removed the entire Body element.
[ISS.0088.9114] Missing SOAP directive in the URL url

[ISS.0088.9116] The server cannot execute the requested SOAP utility; required parameter
paramName is missing or invalid
Cause: The requested SOAP utility failed to execute because a required parameter was not
supplied.
Response: Check the logic in the SOAP processor or client to make sure that it passes the
correct parameters to each SOAP utility service that it invokes.
[ISS.0088.9117] One or more header entries were not understood by the SOAP processor
Cause: The SOAP processor has rejected the SOAP message because it cannot obey a
mandatory header entry (a header entry whose mustUnderstand attribute is enabled).
[ISS.0088.9118] Parameter paramName must be a valid soapData

Cause: The requested SOAP utility failed to execute because parameter paramName is not a
SOAP object.
Response: Examine the logic in the SOAP processor or client and make sure that it passes a
SOAP object in parameter paramName.

[ISS.0088.9119] SOAP Processor did NOT return a valid SOAP Response

Cause: The message handler did not receive a valid SOAP message from the SOAP
processor.
Response: Examine the logic in the SOAP processor to make sure that it composes the
SOAP response message correctly. For example, check to see whether it the processor uses
the stringToSoapData or streamToSoapData services to generate soapResponseData. If so,
determine whether the original String or stream represents a valid SOAP message. If the
SOAP processor logic seems correct, contact Software AG Customer Care. This would
indicate a serious internal error.
[ISS.0088.9120] Parameter paramName is not one of the valid data types: dataType
Cause: The requested SOAP utility failed to execute because parameter paramName did not
have the correct data type. The type in dataType is the data type that is expected.
Response: Examine the logic in the SOAP processor or client and make sure that it passes
to paramName an object of the data type specified in dataType.
[ISS.0088.9122] Service serviceName does not exist

Cause: The SOAP facility could not complete the requested operation because it could not
find the specified service. This error is issued by various SOAP processes (e.g., registering
a SOAP processor, invoking a SOAP processor, invoking a target service).
Response: Examine the process that failed and make sure that it specifies the name of the
requested service correctly. For example, if you receive this error when registering a SOAP
processor, check that you have specified the svcName parameter correctly. Remember that
service names are case‐sensitive.
[ISS.0088.9123] Requested SOAP processor directiveName is not registered on this server

Cause: The Integration Server could not process the SOAP message because it does not
have the SOAP processor requested by the client.
Response: On the client side, verify that the correct process directive is specified in the
URL (remember that the directive is case‐sensitive). If the client has specified the process
directive correctly, then use pub.soap.processor:list to verify that the requested processor is
registered on the Integration Server.
[ISS.0088.9124] SOAP Message does not conform to the SOAP message model
Cause: The SOAP message passed to the validateSoapData utility failed validation (for
example, it is missing the Body element or the Header element follows the body).
Response: Examine the logic that produced the message and see whether it uses the
stringToSoapData or streamToSoapData service to manually generate a SOAP object instead of
using the message composition services (e.g., createSoapData, addHeaderEntry, addBodyEntry). If

so, determine whether the String or stream from which the SOAP object is generated
represents a valid SOAP message.
Also check whether the SOAP processor or client used any of the data removal utilities
(such as removeHeaderEntry or removeBodyEntry) and might have inadvertently removed
required portions of the SOAP object (for example, the entire Body element).
[ISS.0088.9125] SOAP request does not conform to the SOAP message model
Cause: The SOAP message handler could not process the SOAP request because it violates
the SOAP message schema (for example, it is missing the Body element or the Header
element follows the body).
Response: On the client side, correct the logic that builds the message to ensure that it
produces a valid SOAP message.
[ISS.0088.9126] SOAP response does not conform to the SOAP message model
Cause: The SOAP message handler could not return the SOAP response generated by a
SOAP processor on the Integration Server because the message violates the SOAP
message schema.
Response: Examine the logic in the SOAP processor and see whether it uses the
stringToSoapData or streamToSoapData service to generate a SOAP object. If so, determine
whether the String or stream from which the SOAP object is generated represents a valid
SOAP message. Examine the logic that produced the message and see whether it uses the
stringToSoapData or streamToSoapData service to manually generate a SOAP object instead of
using the message composition services (e.g., createSoapData, addHeaderEntry, addBodyEntry). If
so, determine whether the String or stream from which the SOAP object is generated
represents a valid SOAP message. Also check whether the SOAP processor or client used
any of the data removal utilities (such as removeHeaderEntry or removeBodyEntry) and might
have inadvertently removed required portions of the SOAP object (for example, the entire
Body element).
[ISS.0088.9127] The server could not load the SOAP XML Validator
[ISS.0088.9128] Request is from namespace 'msgNamespace', server requires namespace

'svrNamespace'
Cause: The SOAP message handler could not process the message because the message is
not from a version of SOAP that the Integration Server supports. The Integration Server
supports the version indicated in svrNamespace.
Response: From the client side, resubmit the message using a version of SOAP that the
Integration Server supports.

[ISS.0088.9129] Comparison requires an rvalue

Cause: The requested SOAP utility (e.g., addHeaderEntry, addBodyEntry) failed to
execute because it received a node that does not represent an enclosed XML element.
Response: This error can occur if the node is missing opening and closing tags (e.g., the
node contains ʺ hello ʺ instead of ʺ <a>hello</a> ʺ). Examine the process that called the
failing utility and make sure that it passes a valid node object to the SOAP utility.
[ISS.0088.9130] Comparison righthand operand evaluates to more than one value

execute because it received a node that does not have a root element.
Response: This error can occur if the node contains an XML fragment that represents
uncontained elements (e.g., the node contains ʺ <b>hello</b> <c>world</c> ʺ instead of
ʺ <a> <b>hello</b> <c>world</c> </a> ʺ). Examine the logic that called the failing
utility and make sure that it passes a node containing only one top‐level XML element.
[ISS.0088.9131] Comparison operator is missing.

execute because it received a node that does not represent a well‐formed XML document.
Response: This error can occur if the node contains overlapping or missing tags (e.g., a
node that contains ʺ <b>hello ʺ or ʺ <a> <b>hello <c>world</b></c> </a> ʺ). Examine
the logic that called the failing utility and make sure that it passes a node containing well‐
formed XML.
[ISS.0088.9132] Failed to register SOAP Handler directiveName, illegal characters in directive name
Cause: The Integration Server was not able to successfully register the SOAP processor,
because directiveName contains characters that are not allowed in a directive name.
Response: Register the SOAP processor under a name that is composed only of letters,
digits, or the characters -_.!~*'( ).
[ISS.0088.9133] Error while encoding RPC output.

Cause: The message coder could not XML‐encode the parameters associated with a SOAP
remote procedure call.
Response: See the detail element in the SOAP fault for information about the specific
failure that occurred.
[ISS.0088.9134] Exception occurred while processing the body of the message.

Cause: The Integration Server, the SOAP processor, or one of the services processing the
SOAP message has thrown an exception.

Response: See the detail element in the SOAP fault to determine the exception that was
thrown and which process it was thrown by.
[ISS.0088.9135] A WMDocument Exception was thrown in the server, usually because an XML block
was not well-formed.
Cause: The SOAP message handler, the soapHTTP service, or the soapRPC service has
received a SOAP message that contains invalid XML.
Response: Check the process that submitted the SOAP message to the Integration Server
and make sure that it is producing valid XML. This error usually occurs because of a basic
error in the XML document, such as missing tags or overlapping elements.
[ISS.0088.9136] A WattEvaluationException was thrown by the XQL Query engine.

Cause: The XQL query processor encountered a serious internal error.
[ISS.0088.9137] Invalid input parameter; paramName must be a Document (IData).

Cause: The requested SOAP utility failed to execute because the object passed in
paramName is not an IData object.
Response: Check the logic in the SOAP processor or client to make sure that it passes an
IData in paramName.
[ISS.0088.9138] Input parameters do not conform to targetInputSignature: validationDetails.

Cause: The pub.client:soapRPC service could not submit the remote procedure call because
the input parameters did not pass the data‐validation process.
Response: This error is thrown when a client supplies an invalid set of input parameters
for a SOAP remote procedure call. Specifically, it indicates that the parameters submitted
to pub.client:soapRPC in reqParms do not match the structure and constraints of the
document type specified in targetInputSignature.
Generally, you will want to code your client to detect this kind of error and take some type
of corrective action when it occurs.
[ISS.0088.9139] Output parameters do not conform to targetOutputSignature: validationDetails.

Cause: The SOAP RPC client could not submit the remote procedure call because the
output parameters returned by the remote server did not pass the data‐validation process.
Response: This error is thrown when a client receives an invalid set of output parameters
(results) from a SOAP remote procedure call. Specifically, it indicates that the parameters
returned to pub.client:soapRPC in respParms do not match the structure and constraints of the
document type specified in targetOutputSignature.

Generally, you will want to code your client to detect this kind of error and take some type
of corrective action when it occurs.
[ISS.0088.9140] Invalid target signature docTypeName, must be a Document Type

Cause: The SOAP RPC client could not process the remote procedure call because it was
not able to validate the input or output parameters associated with the request. The
signature it was given for validation is not a document type.
Response: Examine the logic in the SOAP RPC client and make sure that the object it
specifies in targetInputSignature and/or targetOutputSignature is a document type. That is,
these parameters, if used, specify the fully qualified name of a document type that exists
on the Integration Server.
[ISS.0088.9141] Invalid target signature docTypeName, Document Type does not exist
Cause: The SOAP RPC client could not process the remote procedure call because it was
not able to validate the input or output parameters associated with the request. The
specified document type does not exist on the Integration Server.
Response: Examine the logic in the SOAP RPC client and make sure that
targetOutputSignature and/or targetOutputSignature are correctly specified. (Remember
that the names of document types are case sensitive.). Also verify that the specified
document type exists on the server and the package in which it resides is loaded and
enabled.
[ISS.0088.9142] attribute() incorrect attribute name \"{0}\"

Cause: The pub.soap.util:addBodyEntry service failed because it was given an XML node that
was not namespace qualified.
Response: Examine the logic in the SOAP client or target service (depending on which
entity issued the error) and verify that the XML node that the addBodyEntry service is
attempting to add is namespace qualified (that is, that it includes the xmlns attribute and
that the element name has the proper namespace prefix).
Note: This error occurs only if namespace checking is enabled on the Integration Server.
See “watt.server.SOAP.enforceMsgPartNS” on page 115.
[ISS.0088.9143] count() takes a query parameter

Cause: The pub.soap.util:addHeaderEntry service failed because it was given an XML node that
was not namespace qualified.
Response: Examine the logic in the SOAP client or target service (depending on which
entity issued the error) and verify that the XML node that the addHeaderEntry service is
attempting to add is namespace qualified (that is, that it includes the xmlns attribute and
that the element name has the proper namespace prefix).

Note: This error occurs only if namespace checking is enabled on the Integration Server.
See “watt.server.SOAP.enforceMsgPartNS” on page 115.
[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: Any SOAPEnvelope object must contain a maximum of one SOAPHeader
objects.
[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: Any 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 SOAPBody Element 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,
unknown. The only valid SOAPMessage property names are
javax.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
one only Fault object.
Response: Remove the existing Fault object before adding a 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.

Response: No action is required.
[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 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.
Response: No action is required.
[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 fails because the Web
service descriptor does not exist.
Response: Correct the name of the web service and verify that the Web service descriptor
exists.

[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 specific Web service
descriptor.
[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 returned false, indicating a failure.
Response: Check the 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 SOAPMessage.
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.b2bserver.saaj.SAAJMetaFactory”.
[ISS.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.

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.
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.
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/xop+xml”
Cause: Value for the “start‐info” parameter of the “Content‐Type” header field of the
MIME message is not equal to “application/xop+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 messages.

value of the “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
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 Part is not of version 1.2.
Cause: The version of the SOAP Message is not equal to 1.2.
Response: Edit the version of the SOAP Message to 1.2 and 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 name space 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.

Appendix B. Encoding/Decoding Data-Type Mapping
XML-to-Java Mappings (Decoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Java-to-XML Mappings (Encoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
webMethods to XML Mappings (Encoding & Decoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

B. Encoding/Decoding Data-Type Mapping
XML-to-Java Mappings (Decoding)

The following tables describe the Java objects that the message coder creates for the
various XML Schema data types.
Note: The message coder generates the objects listed below only when a parameter is
declared as an Object in the accompanying signature. This list does not apply to
parameters that the signature declares as Strings. If the signature defines a parameter as a
String or if a parameter is not defined in a signature, the message coder always renders it
as a String.
Data types from http://schemas.xmlsoap.org/soap/encoding/

The following describes the Java objects to which Simple Object Access Protocol (SOAP) 1.1 ‐
W3C Note 08 May 2000 types are converted (that is, types from namespace
http://schemas.xmlsoap.org/soap/encoding/):
When the XML parameter is of type… The message coder renders it as a…
ENTITIES String
ENTITY String
ID String
IDREF String
IDREFS String
NCName String
NMTOKEN String
NMTOKENS String
NOTATION String
Name String
QName String
base64 byte[ ]
binary String
boolean Boolean
byte Byte
century String
date Date

decimal BigDecimal
double Double
float Float
int Integer
integer BigInteger
language String
long Long
month String
negativeInteger BigInteger
nonNegativeInteger BigInteger
nonPositiveInteger BigInteger
positiveInteger BigInteger
recurringDate String
recurringDay String
recurringDuration String
short Short
string String
time GregorianCalendar
timeDuration String
timeInstant String
timePeriod String
unsignedByte Short
unsignedInt Long
unsignedLong BigInteger
unsignedShort Integer
uriReference String
year String

Data types from http://www.w3.org/1999/XMLSchema

The following describes the Java objects to which the types defined in XML Schema
Datatypes ‐ W3C Last Call Draft April 7 2000 are converted (that is, types from namespace
http://www.w3.org/1999/XMLSchema).
ENTITIES String
ENTITY String
ID String
IDREF String
IDREFS String
NCName String
NMTOKEN String
NMTOKENS String
NOTATION String
Name String
QName String
binary String
boolean Boolean
byte Byte
century String
date Date
decimal BigDecimal
double Double
float Float
int Integer
integer BigInteger
language String
long Long
month String

recurringDay String
short Short
string String
timeDuration String
timeInstant String
timePeriod String
unsignedByte Short
unsignedInt Long
uriReference String
year String
Data types from http://www.w3.org/2000/10/XMLSchema

The following describes the Java objects to which XML Schema Datatypes ‐ W3C Candidate
Recommendation Oct 24 2000 types are converted (that is, types from namespace
http://www.w3.org/2000/10/XMLSchema):
CDATA String
ENTITIES String
ENTITY String
ID String
IDREF String
IDREFS String
hexBinary byte[ ]

NCName String
NMTOKEN String
NMTOKENS String
NOTATION String
Name String
QName String
binary String
boolean Boolean
byte Byte
century String
date Date
decimal BigDecimal
double Double
float Float
int Integer
integer BigInteger
language String
long Long
month String
recurringDay String
short Short
string String
timeDuration String

timeInstant String
timePeriod String
token String
unsignedByte Short
unsignedInt Long
uriReference String
year String
Data types from http://www.w3.org/2001/XMLSchema

The following describes the Java objects to which XML Schema Datatypes ‐ W3C
Recommendation May 2 2001 types are converted (that is, types from namespace
http://www.w3.org/2001/XMLSchema):
ENTITIES String
ENTITY String
ID String
IDREF String
IDREFS String
hexBinary byte[ ]
NCName String
NMTOKEN String
NMTOKENS String
NOTATION String
Name String
QName QName
anyURI String
base64Binary String
boolean Boolean

byte Byte
date Date
dateTime GregorianCalendar
decimal BigDecimal
double Double
duration String
float Float
gDay String
gMonth String
gMonthDay String
gYear String
gYearMonth String
int Integer
integer BigInteger
language String
long Long
normalizedString String
short Short
string String
token String
unsignedByte Short
unsignedInt Long

Java-to-XML Mappings (Encoding)

The following describes how Java objects are encoded as XML schema data types.
Note: The following data types are used only when message coder is encoding a parameter
that is defined as an Object in the accompanying signature or is encoding a parameter that
is not declared in a signature. When a parameter is defined as a String in the
accompanying signature, it is always encoded according to its Content type constraint.
Is encoded as
Object of type… type… From namespace…
BigDecimal decimal http://www.w3.org/2001/XMLSchema

BigInteger integer http://www.w3.org/2001/XMLSchema
Boolean boolean http://www.w3.org/2001/XMLSchema
Byte byte http://www.w3.org/2001/XMLSchema
byte[ ] base64 http://schemas.xmlsoap.org/soap/encoding/
Date date http://www.w3.org/2001/XMLSchema
Document string http://www.w3.org/2001/XMLSchema
Double double http://www.w3.org/2001/XMLSchema
ElementNode string http://www.w3.org/2001/XMLSchema
Float float http://www.w3.org/2001/XMLSchema
GregorianCalendar datetime http://www.w3.org/2001/XMLSchema
Hashtable Hashtable http://www.webmethods.com/2001/10/soap/encoding
IData* data http://www.webmethods.com/2001/10/soap/encoding
Integer int http://www.w3.org/2001/XMLSchema
Long long http://www.w3.org/2001/XMLSchema
MBoolean boolean http://www.w3.org/2001/XMLSchema
MByte byte http://www.w3.org/2001/XMLSchema
MDouble double http://www.w3.org/2001/XMLSchema
MFloat float http://www.w3.org/2001/XMLSchema
MInteger int http://www.w3.org/2001/XMLSchema
MLong long http://www.w3.org/2001/XMLSchema
MShort short http://www.w3.org/2001/XMLSchema

Is encoded as
Object of type… type… From namespace…
QName QName http://www.w3.org/2001/XMLSchema

Short short http://www.w3.org/2001/XMLSchema
String string http://www.w3.org/2001/XMLSchema
Vector Vector http://www.webmethods.com/2001/10/soap/encoding
webMethods to XML Mappings (Encoding & Decoding)
Data types from

http://www.webmethods.com/2001/10/soap/encoding
The following Java objects are encoded with webMethods‐specific data types (that is,
types from namespace http://www.webmethods.com/2001/10/soap/encoding).
Java Object XML type
Hashtable Hashtable
Vector Vector
IData* data
com.wm.util.Table data array
* Or any class that implements the IData interface (for example, BasicData,
IDataCodable, Values).

Appendix C. SOAP-Related Server Parameters
SOAP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

C. SOAP-Related Server Parameters
SOAP Parameters
The following describes the server parameters that you can use to configure the way in
which SOAP operates on the Integration Server. For information about how to set server
parameters, see the webMethods Integration Server Administrator’s Guide.
watt.server.SOAP.directive
Specifies the directive that represents the SOAP message handler. The default is soap. This
parameter determines the URL that is used to access SOAP processors on the Integration
Server.
http://hostName:portNum/soap/[processDirective]
This parameter specifies this segment of the SOAP
processor URL
watt.server.SOAP.defaultProtocol
Specifies the default protocol that Integration Server uses for new SOAP messages.
Specify SOAP 1.1 Protocol or SOAP 1.2 Protocol. The default is SOAP 1.1 Protocol.
watt.server.SOAP.MTOMThreshold
Specifies the field size, in kilobytes, that determines whether Integration Server handles
base64binary encoded data in a SOAP request as a MIME attachment or whether it sends
it inline in the SOAP message. If the Web service descriptor for the SOAP message enables
attachments for the SOAP request, Integration Server passes as MIME attachments any
base64 fields in a SOAP message that are larger than the threshold. This only applies to
SOAP 1.2 messages. The default is 0.
watt.server.SOAP.validateSOAPMessage
Specifies whether the SOAP message handler will validate messages that it receives and
sends. Set to true or false. Default is true.
When watt.server.SOAP.validateSOAPMessage is true, the message handler validates
messages against the SOAP schema. Be aware that the this validation process checks only
that the message envelope is structured correctly—for example, it checks the message has
at least one body element and there is at most one header element. It does not validate any
of the data carried by the message.
If you are operating in a production environment where the validity of the messages
submitted to the server is assured, you might set
watt.server.SOAP.validateSOAPMessage to false to optimize performance.
Note: This parameter is overridden by an individual SOAP processor’s
validateSOAPMessage setting. Consequently, the server’s
watt.server.SOAP.validateSOAPMessage setting is used only when a SOAP processor’s
validateSOAPMessage parameter has not been set. For more information about setting the
validateSOAPMessage parameter, see the pub.soap.processor:registerProcessor service in the
webMethods Integration Server Built‐In Services Reference.

watt.server.SOAP.useMultiReference
Specifies how the message coder is to encode parameters that point to the same
underlying data object in the pipeline. Set to true or false. Default is true.
For example, if two output parameters cDate and oDate point to the same underlying data
in the pipeline, the message coder encodes the parameters like this if
watt.server.SOAP.useMultiReference is true:
.
.
.
<amt id="id2">300</amt> The oDate parameter is encoded as a reference
.
.
.
And like this if watt.server.SOAP.useMultiReference is false:
.
.
.
<amt>300</amt> The oDate parameter is encoded as an
<oDate>03/15/2000</oDate> independent element
<acct>cash</acct>
.
.
.
Note: This parameter affects only the way in which multi‐referenced parameters are
encoded. It does not affect the way in which they are decoded. The message coder always
recognizes and decodes multi‐referenced elements regardless of how
watt.server.SOAP.useMultiReference is set.
watt.server.SOAP.enforceMsgPartNS
Specifies whether the server allows non‐namespace qualified header and body entries to
be added to a SOAP message. Set to true or false. Default is true.
If watt.server.SOAP.enforceMsgPartNS=true, the server will throw an exception if the
pub.soap.utils:addHeaderEntry or pub.soap.utils:addBodyEntry service (or their underlying
methods) attempts to insert a non‐namespace qualified element into a SOAP message. If
false, non‐namespace qualified elements are permitted.
For interoperatbility with other SOAP implementations, we recommend that you run
your server with this parameter enabled (the default setting). This ensures that your
server will not generate and transmit SOAP messages that have non‐namespace qualified
header or body entries.


Appendix D. Using the SOAP RPC Processor
What is the RPC Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Behavior of the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Building Target Services for the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
The Message Coder and the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

D. Using the SOAP RPC Processor
What is the RPC Processor?

The RPC processor is the subsystem that the Integration Server uses to receive and process
SOAP remote procedure calls (RPCs). The RPC processor is invoked when the message
handler receives a URL with a process directive set to “rpc,” as shown below:
To submit a SOAP RPC message to the Integration

http://rubicon:5555/soap/rpc Server, specify the “rpc” directive in the URL
Note: The RPC Processor is deprecated for Integration Server 7.1.
What Does a SOAP RPC Message Look Like?

A SOAP RPC message is an ordinary SOAP message whose body conveys a remote
procedure call. The body of an RPC message has a standard structure that specifies the
name of the requested procedure and its input parameters.
The qualified name (QName) of the first element within the body identifies the procedure
that the client is calling. On the Integration Server, the QName specifies the universal
name of the service to be executed.
The children within the first element represent the input parameters for the requested
procedure.
For example, the following message body contains a call to a procedure named
GL:journalEntry. It also conveys four input parameters to this procedure: Id, date, amt,
and acct.
Basic structure of a SOAP remote procedure call
.
.
The QName of the first .
element specifies the <SOAP-ENV:Body>
requested procedure...
GL:journalEntry xmlns:GL="http://www.expt.com/GL">
<GL:journalEntry
<Id>2398</Id>
<date>03/15/2000</date>
...and its children
<amt>237.50</amt>
supply the input
parameters. <acct>Cash</acct>
</GL:journalEntry>
</SOAP-ENV:Body>
.
.
.

For more information about the structure of a SOAP RPC message, see the Simple Object
Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/.
QNames and Input Parameters

When an RPC processor receives a SOAP remote procedure call, it must:
Resolve the QName in the body in the message with the name of a procedure in the
local environment, and…
Render the input parameters in a form that the target procedure can use.
On the Integration Server, the RPC processor performs this work by:
Matching the QName to the universal name of a service, and…
Engaging the message coder to convert the XML‐encoded input parameters to a set of
Java objects that the service can consume.
Note: The Integration Server expects the QName in the incoming SOAP message to be
normalized according to Unicode Normalization Form C. Normalization ensures that
characters) are represented in a standard way. If the client has not normalized the QName,
the Integration Server might not be able to match it with a universal name in its registry.
What Does a Results Message Look Like?

Results are also carried in the body of the message and are formatted in a standard way.
The qualified name (QName) of the first element within the body of the message is the
same as the QName of the first in the original request, except that the suffix
“Response” is appended to it.
The children of this element contain the output values from the requested procedure.
The following is an example of a response message that contains two output parameters:
status and balance.

Basic structure of a SOAP RPC results message

.
.
The QName of the first .
element has the <SOAP-ENV:Body>
“Response” suffix...
<ser-root:journalEntryResponse
ser-root:journalEntryResponse xmlns:ser-root="http://www.expt.com/GL">
<status xsi:type="xsd:string">closed</status>
...and its children
<balance xsi:type="xsd:int">0</balance>
contain the output
parameters </ser-root:journalEntryResponse>
</SOAP-ENV:Body>
.
.
.
The results use the same namespace as the original request. By default, the webMethods
Integration Server uses the prefix “ser‐root” for this namespace.
For more information about the structure of a SOAP RPC response, see the Simple Object
Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/.
Behavior of the RPC Processor

When the RPC processor receives a SOAP message, the following occurs:
1 The processor searches for the target service. The processor locates the service whose
universal name (explicit or implicit) matches the QName of the first element in the
body of the message.
For example, if the RPC processor received the following request, it would fetch the
service whose universal name matches the namespace name http://www/expt.com/GL/ and
the local name journalEntry.
.
.
.
<SOAP-ENV:Body>
<GL:journalEntry xmlns:GL="http://www.expt.com/GL/">
<date>03/15/2000</date>
<amt>237.50</amt>
<acct>Cash</acct>
</GL:journalEntry>
</SOAP-ENV:Body>
.
.
.
If the processor cannot locate the target service, it returns a SOAP fault that contains
the following error message:
[ISS.0088.9122] Service namespaceName:localName does not exist
For more information about this error, see Appendix A, “SOAP Faults Returned by
the Integration Server”.

2 If the processor finds the requested service, the message coder decodes the input parameters.
The message coder extracts the XML‐encoded input parameters from the body of the
message and converts them into Java objects. For more information about the
decoding process, see “Decoding the Input Parameters” on page 126.
3 The processor invokes the target service and passes the decoded parameters to the service
via the pipeline.
4 When the service ends, the message coder encodes the results. The message coder converts
the parameters named in the output signature to a set of XML‐encoded values. For
more information about encoding, see “Encoding the Output Parameters” on
page 130.
5 The processor assembles the SOAP response message and passes it back to the message
handler.
Building Target Services for the RPC Processor

Any service on the Integration Server can function as a target service of a SOAP remote
procedure call, providing it satisfies the following criteria:
The service’s implicit or explicit universal name matches the QName that the client
will submit in the remote procedure call. For information about assigning universal
names to services, see “To assign, edit, or view an explicit universal name” on
page 36.
The names of the parameters in the target service’s input signature match the names
of the parameters that the client will pass in the remote procedure call. (Keep in mind
that these names are case sensitive.)
The service’s output signature defines all of the values that are to be returned to the
client.
The service’s ACL specifies the groups of users who are authorized to execute it.
To ensure that parameters are properly encoded, decoded, and validated, you should also
ensure that:
The Content type property for each String‐based parameter in the output signature
specifies the data type that is to be assigned when they are XML‐encoded. (See “The
Message Coder and the RPC Processor” on page 125 for information about how the
Content type property is used to encode and decode parameter values.)
The service’s Validate input and/or Validate output properties are enabled if you want the
input and/or output values to be validated at run time.

Error Handling
If a target service throws an exception while it is processing, the message handler
automatically returns a SOAP fault to the client. Depending on the type of error that
occurs, the SOAP fault may include a “detail” element, which provides specific
information about the exception. This element will include a stackTrace element if the
client is a member of the Developers or Administrators user group.
<SOAP-ENV:Envelope
When the target
service throws an
exception, the xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
message handler <SOAP-ENV:Body>
returns a SOAP <SOAP-ENV:Fault>
fault... <faultcode>
SOAP-ENV:Client
</faultcode>
<faultstring>
[ISS.0088.9134] Exception occurred while processing the body of message
...containing the error </faultstring>
message... <faultactor>
</faultactor>
<exception>
...and details <message xml:lang="en-US">detailedMsgIssuedbyException</message>
about the error. <stackTrace>textFromStackTrace</stackTrace>
</exception>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>

Example—Target Service for the RPC Processor

The following is an example of a very simple target service that is suitable for calling with
SOAP RPC. This service takes three String parameters (acct, amt, and loc) and returns one
String parameter (authCode).
This service is located in sample.soap:targetSvc_rpcProcSimple. You can call it via SOAP RPC by
executing the client service, sample.soap:buildRPC_SendHTTPSimple, from Developer. When
you run the client service in Developer, it will prompt you for the following values:
For this input parameter... Enter...
acct Any string of characters.
amt A decimal value, such as 150.75 or 15.00. (Omit commas from
large values; otherwise, the value will fail validation.)
loc Any string of characters.
userName A user name that belongs to the Developers ACL.
password The password for the user name that you entered in userName.
A simple target service
This flow simulates a service that issues an authorization code based on the value in the
input parameter amt. Because a SOAP RPC target does not require any special logic, the
service does not perform any work that is SOAP‐specific. You could call this service from
any type of client. It contains nothing that restricts its use to SOAP remote procedure calls.
The characteristics that are significant if this service is to be used as a SOAP RPC target are
its signature and its universal name.
The Signature. The signature for this service defines three input variables (acct, amt, and
loc) and one output variable (authCode). Note that the Validate input and Validate output
settings are enabled in this example to ensure that the input and output values are
validated at run time.

Signature for the sample target service
The signature is critical because it determines how variables are decoded and encoded
at run time. In this example, the input variables are declared as Strings, which means
that the message coder will render them as Strings regardless of the data types
specified in the XML.
If you examine the properties for these parameters with the Developer, you will see
that the Content type and Required properties are specified. These will be used to
validate the values that the client provides.
The signature declares one output variable called authCode. Because this is the only
variable declared in the output signature, it will be the only parameter returned to the
client.
If you examine the properties for authCode, you will see that its Content type is set to
string {http://www.w3.org/2001/XMLSchema}. This tells the message coder to set
the type attribute to ʺxsd:stringʺ when it encodes this parameter.
The Universal name. An explicit universal name has been specified for this service in the
Universal name category of the Properties panel. The universal name determines the
QName that causes this service to execute. In this example, the service will be
triggered when a client submits a SOAP remote procedure call whose QName is
composed of the namespace name http://www.expt.com/AUTH and the local name
getAuthCode.

Properties for the sample target service
Universal name is
specified on the
Properties panel
The Message Coder and the RPC Processor

The message coder is the subsystem that decodes and encodes the input and output
parameters associated with a SOAP remote procedure call. Its role is to turn a set of XML‐
encoded values into a pipeline of the appropriate data types (the decoding process) and,
conversely, to turn objects in the pipeline to a set of XML‐encoded values (the encoding
process).
Note: The encoding and decoding processes are sometimes referred to as “serializing and
deserializing” or “marshalling and unmarshalling.”
Encoding/Decoding Rules
To encode and decode the parameters in a SOAP RPC message, the message coder follows
the SOAP 1.1 encoding style, which is specified by the following SOAP encodingStyle
attribute:
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
This attribute specifies the set of rules that govern how the input and output parameters
of a SOAP RPC message are to be represented in XML. These rules are defined in the
“SOAP Encoding” section of the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08
May 2000 at http://www.w3.org/TR/SOAP/.

Note: Currently, the Integration Server supports only the SOAP 1.1. encoding style.
However, the ability to accommodate different encoding styles is designed into the
product, so as additional styles become available, support for them can easily be added to
the Integration Server.
Decoding the Input Parameters

The decoding process is the process of converting a set of XML‐encoded values to an IData
object (a pipeline).
When the RPC processor receives a valid procedure call, it engages the message coder,
which decodes the input parameters and produces the pipeline that is passed to the target
service.
Note: The message coder is also engaged by the SOAP RPC client to decode the output
parameters returned by a SOAP remote procedure call. For information about this use of
the message coder, see “The Message Coder and the RPC Client” on page 73.
Transforming Input Parameters into a Pipeline

To produce a pipeline for the target service, the message coder uses the input parameters
from the body of the message and the input signature from the target service.

Producing a pipeline from the input parameters in a remote procedure call
1 The message coder takes the 2

…and the input signature from the
encodingStyle and the input
target service…
parameters from the SOAP RPC
message…
Message Coder
3 …and produces a pipeline for the

target service
During the decoding process, the message coder matches the names of the parameters
passed by the client with the names of the parameters defined in the input signature. It
uses the input signature to determine how to render the parameters in the pipeline.
If the input signature declares a parameter as a String, the parameter is rendered as a Java
If the input signature declares a parameter as an Object, the value is rendered according to
the data type declared in the XML. (For a list of XML data types and the Java classes to
which they are converted, see Appendix B, “Encoding/Decoding Data‐Type
Mapping”.) If an XML element does not declare its type, the parameter is rendered as
a String.
The following table shows how the message coder would decode an input parameter
named amt given various data‐type declarations and input signatures. Note that when the
input signature defines the parameter as a String, the message coder always produces a

and Input The Message Coder

When XML data type is... Signature is... produces...
<amt xsi:type="xsd:decimal">500.00</amt>
<amt xsi:type="xsd:decimal">500.00</amt>
of class java.math.BigDecimal
<amt xsi:type="xsd:float">500.00</amt>
<amt xsi:type="xsd:float">500.00</amt>
of class java.lang.Float
<amt>500.00</amt> (that is, undeclared)
<amt>500.00</amt> (that is, undeclared)
Parameters that are Not in the Input Signature

The message coder decodes every input parameter that a client submits, even those that
do not appear in the input signature. When a client submits parameters that are not
declared in the input signature, the message coder renders them as Strings.
Decoding Complex Structures and Arrays

For complex data types (XML elements that contain child elements), the message coder
produces documents (IData objects) in the pipeline.
The message coder creates arrays of elements (that is, String Lists, Document Lists, Object
lists) for elements that are properly encoded as SOAP arrays in the SOAP message. For
more information about how the arrays are encoded in a SOAP message, see the “Arrays”
section in the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at
Decoding Multi-Referenced Parameters

The message coder can resolve parameters that are referenced through the href attribute as
long as the referenced value appears within the body of the SOAP message. The message
coder cannot resolve external references (references that point to resources outside of the
message) or references that point to elements outside the Body element.
Within the Body element, the href attribute may appear before or after the value that it
references. The message coder can successfully resolve either type.

Example of a Backward Reference

In a backwards reference, .
a referenced value .
appears before the point .
where it is referenced. <cDate id="id1">03/15/2000</cDate>
<amt id="id2">300</amt>
.
.
.
Example of a Forward Reference

.
.
.
In a forward reference, a <amt id="id2">300</amt?
referenced value appears <cDate id="id1">03/15/2000</cDate>
after the point where it is
.
referenced.
For referenced elements, the message coder puts a single copy of the value in the pipeline
and generates references to it.
Note: If the message coder cannot resolve a reference, it generates a null object for that
parameter. It also reports the problem in the server log if the server is running at debug
level 5 or higher.
Decoding and Validation

Be aware that the message coder does not validate the input parameters that it decodes.
For example, it does not verify that an element of type xsi:type=decimal actually
contains a numeric value. It simply renders the element as a java.lang.String object or a
java.math.BigDecimal object, depending on the data type specified in the signature of the
target service.
Additionally, the message coder does not verify that the set of parameters it receives from
the client matches the parameters in the input signature in name or number. If a client
includes parameters that are not in the input signature, the message coder includes them
in the pipeline anyway (as Strings). If a parameter is declared in the input signature, but is
not supplied by the client, that parameter is omitted from the pipeline.
Validating Input Parameters

If you want to validate the input parameters that a client submits via SOAP RPC, you use
the server’s normal validation mechanisms to impose data validation on the target service.

For example, to ensure that clients provide a non‐negative integer for a parameter named
hours, you would:
Constrain the hours parameter by setting its Content type property to:
nonNegativeInteger {http://www.w3.org/2001/XMLSchema}
Enable the parameterʹs Required property, and
Set the Validate input option on the target service’s Input/Output tab.

These settings would cause the server to throw an exception if the client omitted the hours
parameter or submitted a value such as .5 or twenty rather than a non‐negative integer.
For more information about validating data at run time, see the webMethods Developer
User’s Guide.
Encoding the Output Parameters

The encoding process is the process of converting a Java object to an XML‐encoded value.
The SOAP RPC processor engages the message coder to encode the results of services that
are invoked via a SOAP remote procedure call.
Note: The message coder is also engaged by the SOAP RPC client to encode the input
parameters for an outbound remote procedure call. For information about this use of the
message coder, see “The Message Coder and the RPC Client” on page 73.
Transforming Output Parameters to XML

When the message coder encodes the results of a remote procedure call, it uses both the
values in the pipeline and the output signature of the target service.

Encoding the output parameters from a remote procedure call
1 The message coder uses the 2

…and the output signature of the
pipeline… target service…
Message Coder
3 …to produce the XML-encoded

results
During the encoding process, the message coder converts the parameters defined in the
output signature to XML‐encoded values.
If the output signature declares a parameter as a String, the value of the parameter is
encoded according to its Content type property. For example, if Content type were
nonNegativeInteger {http://www.w3.org/2001/XMLSchema}, the value would be
encoded as an xsi:type="xsd:nonNegativeInteger". If Content type is not specified,
the message coder encodes the value as a string (as if the parameter were Content type
string {http://www.w3.org/2001/XMLSchema}).
If the output signature declares a parameter as an Object, the value of the parameter is
encoded according to its underlying Java class. For example, if the object were a
java.lang.Boolean, the message coder would declare it as xsi:type="xsd:boolean"
in the resulting XML. For a list of recognized Java classes and the XML Schema data
types to which they are converted, see Appendix B, “Encoding/Decoding Data‐Type
Mapping”. If the message coder does not recognize the underlying class, it encodes
the parameter as a string (it uses the object’s toString( ) method to produce the
parameter’s value).

Important! It is important to understand that the message coder encodes only those
parameters defined in the service’s output signature. It does not encode the entire pipeline.
Therefore, if a service has no output signature, no values are returned to the client.
Additionally, this means that if any of the original input values need to be returned to the
client, those values must be included in the output signature.
Encoding Complex Structures and Arrays

The message coder encodes documents (IData objects) as complex data types.
The message coder encodes Document Lists, String Lists, and Object Lists as SOAP arrays.
For more information about how the arrays are encoded in SOAP messages, see the
“Arrays” section in the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at
Encoding Multi-Referenced Elements

By default, the message coder generates references when encoding parameters that
reference the same underlying data in the pipeline. However, this behavior can be
modified with the watt.server.SOAP.useMultiReference parameter.
When watt.server.SOAP.useMultiReference is true, the message coder generates the
appropriate id and href attributes for parameters that reference the same underlying data.
For example, if the parameters cDate and oDate refer to the same object, the message coder
encodes them like this if watt.server.SOAP.useMultiReference=true (or is not set,
which is the server’s installed behavior):
.
.
.
<amt id="id2">300</amt> The oDate parameter is
<oDate href="#id1"></oDate> encoded as a reference
.
.
.

And encodes them like this if watt.server.SOAP.useMultiReference=false:
.
.
.
<amt>300</amt> The oDate parameter is encoded
<oDate>03/15/2000</oDate> as an independent element
<acct>cash</acct>
.
.
.
For more information about watt.server.SOAP.useMultiReference and other SOAP‐
related server parameters, see Appendix C, “SOAP‐Related Server Parameters”. For more
information about setting server parameters, see the webMethods Integration Server
Administrator’s Online Help.


Appendix E. Creating Custom SOAP Processors
What is a Custom SOAP Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Accessing a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Building a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Registering a SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

E. Creating Custom SOAP Processors
What is a Custom SOAP Processor?

If the default processor provided by webMethods Integration Server does not suit your
needs, you can create your own customized SOAP processor and register it on the
Integration Server. For example, you might create a custom processor that delegates
messages based on the value of a particular header entry, or you might create a customer
processor that drops messages into queues based on the type of documents they carry.
Implementing a custom SOAP processor on the Integration Server involves two basic
steps:
1 First, you must build a service that acts as a SOAP processor. You can code this service to
operate on SOAP messages in whatever manner your solution requires. However, it
must accept a soapRequestData object and a soapResponseData object as input, and must
return a soapResponseData object as output. For information about this step, see
“Building a Custom SOAP Processor” on page 137.
2 Second, you must register the service on the Integration Server as a SOAP processor. You do
this to associate the service with a specific process directive (a name that is unique
among all SOAP processors on the server) and make it accessible to the SOAP
message handler. For information about registering a service as a SOAP processor, see
“Registering a SOAP Processor” on page 145.
Important! The creation of custom processors is deprecated for Integration Server 7.1.
Custom processors created in earlier releases are still supported.
Accessing a Custom SOAP Processor

To direct a message to a custom processor, a client specifies the processor’s “process
directive” in the URL. The process directive is the name under which the custom
processor is registered with the SOAP message handler. For example, the following URL
would invoke the custom processor registered as “inbox.”
This URL directs the message to the SOAP

http://rubicon:5555/soap/inbox processor registered as “inbox”
The following URL would invoke the custom processor registered as “svcRq.”
This URL directs the message to the SOAP

http://rubicon:5555/soap/svcRq processor registered as “svcRq”
Important! Process directives are case sensitive. The directive specified in the URL must
match exactly the process directive as it is defined on the webMethods Integration Server.

If the URL specifies a process directive that is not registered on the server, the SOAP
message handler returns a SOAP fault containing the following error message:
[ISS.0088.9123] Requested SOAP processor directiveName is not
registered on this server.
For information about SOAP faults, see Appendix A, “SOAP Faults Returned by the
Building a Custom SOAP Processor

A SOAP processor is a service that operates on SOAP messages. It can be any type of
service and can contain any kind of logic that your solution requires.
Inputs and Outputs

When the SOAP message handler invokes a custom processor, it passes two input
parameters to that processor:
soapRequestData, an object containing the entire SOAP message
soapResponseData, an object containing an empty SOAP message
When the custom processor ends or exits, the SOAP message handler returns the contents
of soapResponseData to the client (unless the processor throws an exception, in which case
the SOAP message handler generates a SOAP fault and returns it to the client).
How to Create a Custom SOAP Processor

The following describes the general steps you take to create a custom processor.
1 Create a new service that has the following signature:
Inputs: soapRequestData (of type Object)
soapResponseData (of type Object)
Outputs: soapResponseData (of type Object)
You can use pub.soap.utils:requestResponseSpec to specify the inputs and outputs for the
service.
2 Code the service to process SOAP messages in the way you need. The following describes
several tasks that a custom processor typically executes. However, the behavior of
your processor will depend entirely on the needs of your solution. It might include all,
some, or none of the following:
Extracting data from the SOAP request message. To extract information from a SOAP
message, you use the data‐retrieval utilities such as getBody and getHeader. (For a
complete list of the data‐retrieval services, see page 60.) These services retrieve a

specified element from the soapRequestData and return the requested element as
an XML node (or an array of XML nodes). To extract data from the returned node,
you query it with the pub.xml:queryXMLNode service.
Important! Be aware that you cannot query the soapRequestData object directly. To
extract information from soapRequestData (or similar SOAP objects, such as
soapData and soapResponseData), you must use one of the data‐retrieval services to
extract an element of the message (for example, the header, the body, or the entire
envelope) and query the resulting XML node.
Invoking services to process the data extracted from the message. After extracting the

data with which you want to work, you can map it to the appropriate variables (if
necessary) and pass it to services that process it in some way. (To ensure that the
data you have extracted is in the correct format, you might want to validate it
against a schema using pub.schema:validate or make sure that the service to which
you pass the data performs data validation on its input parameters.)
Invoking services based on a particular QName in the SOAP request message. If your
SOAP messages use a qualified name (QName) to specify a target service on the
webMethods Integration Server, you can use pub.soap.utils:getQName (which resides
in the WmPublic package) to extract the element’s QName from the message and
then use pub.universalName:find (which resides in the WmPublic package) to locate
the service associated with that name.
Note: To invoke the service associated with a QName, you will need to create a
Java service that performs a doInvoke of the service returned by
pub.universalName:find. See the com.wm.app.b2b.server package in the webMethods
Integration Server Java API Reference for information about the doInvoke method.
This method is a member of the Service class.
3 Use the SOAP message-composition services to populate soapResponseData. The message‐

composition services are services (such as addHeaderEntry and addBodyEntry) that you use
to add content to the empty message in soapResponseData. (For a complete list of
message‐composition services, see page 53.)
The message‐composition services require an XML node representation of the header
entry or body entry that you want to add to the message. You can generate an XML
node using services such as pub.xml:documentToXMLString and pub.xml:xmlStringToXMLNode.
For an example of how to do this, see Step 3 in the sample code shown on page 141.
4 When you finish coding the service, register it as a SOAP processor. This step associates the
service with a specific process directive and makes it accessible to the SOAP message
handler. For information about registering a service as a SOAP processor, see
“Registering a SOAP Processor” on page 145.

Error Handling
If your SOAP processor (or any service that it calls) throws an exception, the SOAP
message handler automatically returns the following SOAP fault to the client. The fault
includes a “detail” element that provides specific information about the exception. This
element will include a stackTrace element if the client is a member of the Developers or
Administrators user group.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
When a custom <SOAP-ENV:Fault>
processor throws an <faultcode>
exception, the SOAP-ENV:Client
message handler </faultcode>
returns a SOAP fault... <faultstring>
[ISS.0088.9134] Exception occurred while processing the body of the message
...containing an error </faultstring>
message... <faultactor>
</faultactor>
<exception>
...and details <message xml:lang="en-US">detailedMessageIssuedbyException</message>
about the error.
<stackTrace>textFromStackTrace</stackTrace>
</exception>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Note: The SOAP message returned to the client when an exception occurs contains only the
SOAP fault. It does not include any message content (for example, header entries, body
entries) that the target service may have inserted into soapResponseData before the
exception occurred.
Returning Your Own SOAP Faults

Although the SOAP message handler automatically returns a SOAP fault when a custom
processor throws an exception, there may be times when you want your custom processor
to return a SOAP fault. For example, you might want to return a fault if the client omits a
required piece of data or if a requested resource is not available. In these situations, you
can choose to do either of the following:
Code your processor to detect the error condition and throw an exception. This will
cause the message handler to return the standard SOAP fault code shown above. If
you include a detailed error message when you throw the exception, that message
will be included in the detail element within the SOAP fault.

—OR—
Code the processor to detect the error, but instead of throwing an exception, compose
your own SOAP fault in soapResponseData and then exit normally. This will cause the
message handler to simply return the contents of soapResponseData (which contains
the SOAP fault that your processor generated) to the client. If you choose this
approach, you must be thoroughly familiar with the SOAP specification regarding
fault codes.
Important! The SOAP specification states explicitly that the recipient of a SOAP message
must return a SOAP fault anytime it fails to process the submitted message successfully.
Integration Server” of this document and the Simple Object Access Protocol (SOAP) 1.1 ‐
W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/#_Toc478383507 for SOAP 1.1 and
the SOAP 1.2 W3C Recommendation 27 April 2007 at http://www.w3c.org/TR/soap12‐part1/
for SOAP 1.2.
Example—Custom Processor
The following is an example of a SOAP processor that drops the body of the message
(along with several other pieces of control information that it extracts from the header)
into a queue based on the value of a certain header entry. If the document is successfully
logged into the queue, the processor returns an acknowledgment. Otherwise, it generates
an error message and throws an exception so that the client receives a SOAP fault.
This example is located in sample.soap:customProc_msgQueue in the WmSamples package.
You can find the WmSamples package in the certified samples area of the Knowledge Base
on the Advantage Web Site. You might want to open this example with Developer to see
how the pipeline is mapped between steps.
Note: If you want to execute this service from Developer, enable the acquireSOAPMessage
step at the top of the flow. This step generates soapRequestData and soapResponseData
objects, which simulate the pipeline that this service would receive from the SOAP
message handler. If you want to execute this service via the SOAP message handler (that
is, from a client), disable acquireSOAPMessage.

Custom processor that drops messages into queues
# Description
Step 1 Extract data from SOAP request message. This sequence retrieves required pieces

of information from the message by extracting the header and body elements
from soapRequestData and querying the results. This example expects a
SOAP message that is structured as follows:

# Description

<SOAP-ENV:Envelope
This service
pulls certain <SOAP-ENV:Header>
control <EXP:postmark xmlns:EXP="http://www.exprint.com/inbox">
information
<docType>RFQ</docType>
from the
header... <priority>05</priority>
<sender>http://www.polymfg.com/PURCH/A30155G</sender>
<tStamp>20011129.161434206</tStamp>
</EXP:postmark>
</SOAP-ENV:Header>
...and extracts
the document <SOAP-ENV:Body>
carried in the <RFQ:quoteReq xmlns:RFQ="http://www.exprint.com/orderSys">
body of the <acct>1417-A199-0404-5POLY</acct>
message and <jobSpecs>
drops it in a <copies>5000</copies>
queue
<stock>30F-SIL</stock>
<ink>P440</ink>
</jobSpecs>
</RFQ:quoteReq>
</SOAP-ENV:Body>
To extract information from the message, this service executes the following
steps:
Step Description
1.1 getHeader—This step retrieves the header from soapRequestData. It
returns an XML node that represents the entire header element (that is,
from <Header> to </Header>).
1.2 queryXMLNode—This step extracts specific pieces of control
information from the header by executing the following XQL queries
against the XML node returned by Step 1.1.
Var Name XQL Query
QU_docType /PMK:postmark/docType/text()
QU_priority /PMK:postmark/priority/text()
QU_sender /PMK:postmark/sender/text()

# Description
QU_timeSen /PMK:postmark/tStamp/text()
t
If you examine the queryXMLNode step with Developer, you will see that
it also executes the following query, which extracts the entire Header
node as a String:
Var Name XQL Query
wholeNode /source()
This query is included for debugging purposes. It allows you to
examine the raw XML associated with the Header node. If you were to
put this service into production, you would omit this query.
1.3 getBody—This step retrieves the body from soapRequestData. It returns
an XML node that represents the entire body element (that is, from
<Body> to </Body>).
1.4 queryXMLNode—This step extracts the contents of the body element by
executing the following XQL query against the XML node returned in
Step 1.3.
Var Name XQL Query
QU_doc //source()
Step 2 Log extracted data in a queue. This sequence generates a timestamp and drops

the information extracted by Step 1 into a queue (in this example, this action is
simulated by a MAP step). It produces a “receipt” that reports the name of
the queue into which the message was dropped. If the message is rejected by
the queue, the receipt will contain an error message.

# Description
Step 3 Compose SOAP Response Message. This sequence checks the result generated

by Step 2. If Step 2 returns an error, this step generates an error message and
throws an exception (which causes a SOAP fault to be returned to the client).
Otherwise, it generates a response message that is structured as follows:

<SOAP-ENV:Envelope
The receipt SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
from the <SOAP-ENV:Body>
queue is <EXP:QU_receipt xmlns:EXP="http://www.exprint.com/orderSys">
returned in <msg>Document RFQ.20030217.160828.837.A8F7 successfully placed in
the body of queue RFQ</msg>
the SOAP <entryTime>20030217.160828.837</entryTime>
response <qID>RFQ.20030217.160828.837.A8F7</qID>
message </EXP:QU_receipt>
</SOAP-ENV:Body>
To produce the response message, this service executes the following steps:
Step Description
3.1.1 documentToXMLString—This service converts the receipt document to
an XML String.
3.1.2 xmlStringToXMLNode—This step converts the XML String to an XML
node. (Recall that to add a body entry to soapResponseData, you must
place the entry in the pipeline as an XML node.)
3.1.3 addBodyEntry—This step adds the body entry to soapResponseData.
Step 4 FOR DEBUG ONLY. This step converts the contents of soapResponseData to a
String using the soapDataToString service. This allows you to examine the
finished message with Developer, which is useful during testing and
debugging. You would not include this step in a production service.

# Description
If you execute this service and examine the contents of finishedMessage on the
Results panel, you will see a SOAP message similar to the following:
Registering a SOAP Processor

To make a custom SOAP processor available for use, you must register it on the
Integration Server. This action associates your processor with a particular directive and
makes it known to the SOAP message handler. (If your server runs in a cluster, be sure to
register it on every server in the cluster.)
To register a SOAP processor, you execute the service, pub.soap.processor:registerProcessor. To
ensure that your SOAP processor is registered whenever the server is restarted, we
recommend that you include pub.soap.processor:registerProcessor in a startup service.
Note: If you register your SOAP processor using a startup service, make sure that the
package in which the startup service resides designates the WmPublic package as a
dependency. This will instruct the server to load WmPublic before it loads your package
and ensure that pub.soap.processor:registerProcessor is available when your startup service
executes.

How to Register a SOAP Processor

The following describes the general steps you take to register a SOAP processor.
1 Create a flow service that invokes pub.soap.processor:registerProcessor. Set the following
input variables for this service:
Set... To...
directive A String specifying the process directive that you want to
assign to the processor.
Note: Use only letters, digits, or the characters -_.!~*'( ) in

the name you specify in directive.
svcName A String specifying the fully qualified name of the service
that you are registering as a SOAP processor.
descriptiveName Optional. A String that contains a descriptive comment for
this SOAP processor. This comment is shown when you run
the utility service pub.soap.processor:list to get a list of the
registered SOAP processors.
validateSoapMessage Optional. A String indicating whether the SOAP message
handler is to validate the SOAP messages that this processor
sends and receives. This setting overrides the server’s global
watt.server.SOAP.validateSOAPMessage setting.
2 Run the flow service that you just created and verify that it executed successfully. If a processor
is already registered under the name you specified in directive, the service will throw
an exception. In this case, you must either register the new processor under a different
name, or, if you want the new processor to replace the current one, you must
unregister the current processor (with pub.soap.processor:unregisterProcessor) and then
register the new one.
3 Add the flow service to the startup list. To ensure that your processor is automatically
registered with the SOAP message handler whenever the server is started, we suggest
that you make it a startup service.
Viewing the List of Registered SOAP Processors

If you want to view the list of currently registered SOAP processors, execute
pub.soap.processor:list from Developer. This service returns a document list called list that
contains a document (an IData object) for each SOAP processor registered on the server.

List of registered SOAP processors
Each document in list will contain the following keys:
Key Value
directive A String containing the process directive that is assigned to the
SOAP processor.
svcName A String containing the fully qualified name of the service that
functions as the SOAP processor.
descriptiveName A String containing the descriptive comment that was given to the
SOAP processor when it was registered. This element will be empty
if the processor was not registered with a descriptive comment.
validateSoapData A String indicating whether the SOAP message handler validates
the SOAP messages that this processor sends and receives.
Deactivating a Registered SOAP Processor

To deactivate a registered SOAP processor, execute pub.soap.processor:unregisterProcessor and
specify the process directive of the processor that you want to deactivate. This action will
remove the processor from the list of registered SOAP processors and make it inaccessible
to the message handler.
You can also use this service when you want to change the registration information for a
SOAP processor. For example, if you wanted to change a processor’s directive, service, or
descriptive name, you would unregister the processor and then re‐register it with the new
information.


Index
Index
A business payload 15
accessing
custom processor 136 C
default processor 40 classname element 81
RPC Client 66 composing
RPC processor 118 SOAP request 52, 53
actor attribute SOAP response 43, 48, 138, 144
example of 14, 15 conventions used in this document 7
general usage 14, 15 createSoapData service 52, 54
addBodyEntry service 43, 49, 53, 56, 138, 144 creating
addHeaderEntry service 43, 49, 53, 55, 138 SOAP messages 52
adding content to a SOAP message 43, 48, 53, 55, 56, 138, 144 custom processors
addTrailer service 43, 53, 138 accessing 136
application data 15 addressing messages to 136
architecture of SOAP facility 22 example of 140
attributes (actor, mustUnderstand) 14, 15 how to build 137
inputs and outputs 136, 137
B overview of 136
behavior registering on server 136, 138, 145
default processor 40 returning errors from 139
RPC processor 120 unregistering on server 147
Body element
adding content to 48, 56 D
basic structure of 10 data types
example of 16 supported by message coder 103
Fault codes 17, 80 XML to Java conversion 104, 111
requirements of 15 data-retrieval services
building a custom processor using in custom processors 137, 141
example 140 using in target service 42, 46
general steps 137 deactivating a SOAP processor 147
building a target service decoding SOAP RPC parameters. See message coder
example 44, 123 decomposing SOAP messages. See extracting data from SOAP
general steps 42 messages
building SOAP messages default processor
example 53 accessing 40
general steps 52 addressing messages to 40
building solutions behavior of 40
receive messages 32 building target services for 42
send messages 37 inputs and outputs 41

Index
selection of target services 40 G

use of QNames 40 getBody service 42, 46, 60, 137, 143
use of universal names 40 getBodyEntries service 60
detail element 17, 81, 82 getDocument service 60
developing solutions getHeader service 42, 60, 137, 142
that receive messages 32 getHeaderEntries service 60
that send messages 37 getQName service 138
documentation getTrailers service 42, 60, 137
additional 8
conventions used 7
H
feedback 8
documentToXMLString service 43, 48, 49, 53, 138, 144 Header element
adding content to 49, 55
attributes of 14
E
basic structure of 10
encoding SOAP RPC parameters. See message coder example of 13
encodingStyle attribute 125 namespace declarations 12
enforceMsgPartNS parameter 115 requirements of 12
Envelope element HTTP, using to send SOAP messages 57
namespace declarations 11
I
requirements of 11
implicit universal names 34
error handling
in custom processors 139 invoking a remote procedure call 66
in target services 43, 122
list of Fault codes 79 J
explicit universal names 34 Java data types 103
extracting data from SOAP messages 42, 46, 63, 73, 137, 141 Java-to-XML data type mapping 111
F L
Fault codes list service
example of 18, 82 for registered processors 146
list of 79 for universal names 37
structure of 17, 80 local names 33, 34
testing for 63, 73
faultactor element 17, 81 M
faultcode element 17, 80 message coder
faultstring element 17, 81 data type mapping 103
feature overview 22 data-type mappings for decoding 104
fetching data from a SOAP message 42, 46, 63, 73, 137, 141 data-type mappings for encoding 111
find service 37, 138 decoding Object parameters, RPC client 76
decoding Object parameters, RPC processor 127
decoding RPC parameters, RPC client 76
decoding RPC parameters, RPC processor 126

Index
decoding String parameters, RPC client 76 configuring encoding behavior 115

decoding String parameters, RPC processor 127 decoding 77, 128
decoding structures and arrays 77, 128 encoding 75, 132
decoding undeclared parameters, RPC processor 128 mustUnderstand attribute 14
encoding Object parameters, RPC client 75 causing addHeaderEntry utility to fail 89
encoding Object parameters, RPC processor 131
encoding RPC parameters, RPC client 74 N
encoding RPC parameters, RPC processor 130 namespace names 33
encoding String parameters, RPC client 74 namespaces
encoding String parameters, RPC processor 131 enforcing in header and body entries 53, 115
encoding structures and arrays 75, 132 for SOAP elements 11
multi-referenced parameters 75, 77, 128, 132 usage in Envelope 11
usage by RPC client 73 usage in the Header 12
usage by RPC processor 125 usage in universal names 33
validating parameters, RPC client 74 nodes
validating parameters, RPC processor 129 adding to SOAP messages 43, 49, 53, 55, 138, 144
message element 81 extracting data by querying 42, 46, 60, 137, 142, 143
message handler generating 43, 49, 53, 55, 138, 144
relationship to SOAP processors 24 returned by data-retrieval services 42, 46, 60, 137, 142, 143
response generated by 25 validating contents of 43, 138
role in overall architecture 23, 24 normalization
validation performed by 24 expected of QNames 41, 119
message-composition services universal names 34
using in a custom processor 138, 144
using in target service 43, 48
O
using to compose a new message 53
messages overview of SOAP 10
Body element 15 P
building solutions that receive messages 32 parameters, watt.server.SOAP 114
building solutions that send messages 37 payload 15
composing 52 posting SOAP messages to the webMethods Integration Server
Envelope element 11 23
extracting data from 42, 46, 63, 73, 137, 141 process directive
Header element 12 assigning to custom processor 145
payload 15 deactivating 147
posting to the webMethods Integration Server 23 description of 32
receiving 22 for custom processor 136
sending 25, 57 for default processor 40
sending RPC 27, 66 for RPC processor 118
testing for Faults 63, 73 modifying 147
validation of 24 position in URL 23
multi-referenced parameters processor:list service 146
processor:registerProcessor service 145

Index
processor:unregisterProcessor service 147 decoding parameters. See message coder

processors. See SOAP processors encoding parameters. See message coder
program code conventions in this document 7 receiving a SOAP message 120
target service criteria 121
Q
QNames S
extracting from message 138 schemas
invoking services by 138 governing Envelope structure 12
used in SOAP RPC 118, 119, 120 validating application data against 43, 138
qualified names. See QNames validating messages against 24
queryXMLNode service 42, 46, 60, 137, 142, 143 sending SOAP messages
building solutions that send messages 37
R example 61
receiving messages general steps 57
building solutions that receive messages 32 overview of 25
overview of 22 sending SOAP RPC messages
via custom processor 136 overview of 27
via default processor 40 using the RPC client 66
via RPC processor 118 ser-root prefix 120
registering a custom processor 136, 138, 145 server parameters
registerProcessor service 145, 146 watt.server.SOAP.directive 114
remote procedure call watt.server.SOAP.enforceMsgPartNS 115
decoding output parameters 76 watt.server.SOAP.useMultiReference 115
encoding input parameters 74 watt.server.SOAP.validateSOAPMessage 114
invoking 66 serviceStackTrace element 82
processing response 73 SOAP directive, changing 114
request messages SOAP faults. See Fault codes
composing 52 SOAP message handler. See message handler
processing 42, 137 SOAP processors
response messages custom processors 33, 136
composing 43, 138 default processor 33, 40
processing 63, 73 displaying list of 146
retrieving data from SOAP messages 42, 46, 63, 73, 137, 141 overview of 32
RPC client 66 posting messages to 23
calling procedures remotely 66 registering on server 145
RPC message role in overall architecture 23, 25
example of 118 RPC processor 33, 118
QName 118, 119 supplied by webMethods 33
response namespace 120 unregistering 147
results example 119 soapData object
RPC processor adding content to 53
accessing 118 creating 52, 54
addressing messages to 118 soapDataToString service 49, 56, 63, 144

Index
soapHTTP service 57, 58 local portion of name 34

soapRequestData namespace portion of name 33
creation by message handler 24 overview of 33
passed from default processor 41 removing from a service 36
passed to custom processors 136, 137 Universal Name Registry 37
soapResponseData usage by default processor 40
composing 43, 48, 138, 144 viewing name assigned to service 36
creation by message handler 24 universalName:find service 37, 138
passed from default processor 41 universalName:list service 37
passed to cusom processors 136, 137 unregistering a SOAP processor 147
soapRPC client unregisterProcessor service 146, 147
composing the remote procedure call 72 URLs
invoking 66 for custom SOAP processors 136
processing output values 69 for the default SOAP processor 40
stackTrace element 81, 122 for the RPC SOAP processor 118
submitting a remote procedure call 70 format of 23
used to address SOAP processors 23
T useMultiReference parameter 75, 115, 132
target services
V
assigning universal names to 43
example of 44, 123 validate service 43, 138
how to build 42 validateSOAPMessage parameter 114
returning errors from 43, 122 validating
selection process 40 application data 43, 138
signature requirements 42 SOAP Envelope 24
using with RPC processor 121 SOAP RPC parameters 129
trailers VersionMismatch fault code 24
example of 18 viewing
usage 18 list of registered processors 145, 146
troubleshooting information 7 list of universal names 37
typographical conventions in this document 7
W
U watt.server.SOAP.directive 114
Universal Name Registry watt.server.SOAP.enforceMsgPartNS 115
finding services in 37 watt.server.SOAP.useMultiReference 75, 115, 132
overview of 37 watt.server.SOAP.validateSOAPMessage 114
services that operate on 37
viewing contents of 37 X
universal names XML data types 103
assigning to a service 36 XML nodes. See nodes
assigning, editing, and viewing 36 XML, encoding and decoding. See message coder
finding service name for 37, 138 xmlStringToXMLNode service 43, 49, 53, 138, 144
implicit vs explicit 34 XML-to-Java data type mapping 104

Index

WebMethods SOAP Developer&#39;s Guide - Software AG Documentation

Uploaded by

Document Information

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

WebMethods SOAP Developer&#39;s Guide - Software AG Documentation

Uploaded by

Copyright:

Available Formats

Title

Developer Version 7.1 SOAP Developer’s Guide

Document ID: DEV-SOAP-DG-71-20070831

About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 1. Overview of SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 2. SOAP Support on the webMethods Integration Server . . . . . . . . . . . . . . . . . . 21

Chapter 3. Building Solutions with SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

SOAP Developer’s Guide Version 7.1 3

Chapter 4. Using the Default SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 5. Composing and Sending SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Chapter 6. Using the SOAP RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Appendix A. SOAP Faults Returned by the Integration Server . . . . . . . . . . . . . . . . . . . . . 79

SOAP Developer’s Guide Version 7.1 4

Appendix B. Encoding/Decoding Data-Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Appendix C. SOAP-Related Server Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Appendix D. Using the SOAP RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

SOAP Developer’s Guide Version 7.1 5

Appendix E. Creating Custom SOAP Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

SOAP Developer’s Guide Version 7.1 6

About This Guide

SOAP Developer’s Guide Version 7.1 7

SOAP Developer’s Guide Version 7.1 8

What Does a SOAP Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

SOAP Developer’s Guide Version 7.1 9

What Does a SOAP Message Look Like?

A simple SOAP message packet

SOAP Developer’s Guide Version 7.1 10

The SOAP Namespace Declaration

SOAP Developer’s Guide Version 7.1 11

SOAP Developer’s Guide Version 7.1 12

Soap 1.1 message with single header entry

Soap 1.2 message with single header entry

<?xml version="1.0" encoding="UTF-8"?>

SOAP Developer’s Guide Version 7.1 13

SOAP 1.1 Header Attributes

Message that uses the “actor” and “mustUnderstand” attributes

SOAP 1.2 Header Attributes

SOAP Developer’s Guide Version 7.1 14

Message that uses the “role” and “mustUnderstand” attributes

SOAP Developer’s Guide Version 7.1 15

A body containing one entry

A body containing two body entries

SOAP Developer’s Guide Version 7.1 16

SOAP Fault Elements

SOAP Developer’s Guide Version 7.1 17

A SOAP message returning a fault

SOAP Developer’s Guide Version 7.1 18

A SOAP 1.1 message containing two trailers

SOAP Developer’s Guide Version 7.1 19

SOAP Developer’s Guide Version 7.1 20

Receiving SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Sending SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Sending SOAP RPC Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

SOAP Developer’s Guide Version 7.1 21

SOAP Versions Supported by webMethods Integration Server

Receiving SOAP Messages with the Integration Server

SOAP Developer’s Guide Version 7.1 22

Processing and receiving a SOAP request

webMethods Integration Server

SOAP Message Handler

SOAP Developer’s Guide Version 7.1 23

SOAP Developer’s Guide Version 7.1 24

Stage 3 The SOAP Processor Performs Work and Generates a Response

Stage 4 The Message Handler Returns the Response to the Client

WebMethods SOAP Developer's Guide - Software AG Documentation

WebMethods SOAP Developer's Guide - Software AG Documentation