WebMethods SOAP Developer's Guide - Software AG Documentation

TitlePage
Developer
Version 7.1
SOAP Developers Guide
Copyright
& Docu
mentID
Cerebra,Glue,InfravioXBroker,InfravioXRegistry,Infravio,MywebMethodsServer,MywebMethods,webMethodsAccess,webMethodsAdministrator,
webMethodsBroker,webMethodsCentralConfiguration,webMethodsDashboard,webMethodsDesigner,webMethodsDeveloper,webMethodsFabric,
webMethodsGlue,webMethodsInfrastructureDataCollector,webMethodsInfravioXBroker,webMethodsInfravioXRegistry,webMethodsInstaller,
webMethodsIntegrationServer,webMethodslogo,webMethodsMainframe,webMethodsManager,webMethodsModeler,webMethodsMonitor,
webMethodsOptimizeforInfrastructure,webMethodsOptimizeforProcess,webMethodsOptimize,webMethodsPortal,webMethodsProcessEngine,
webMethodsServicenet,webMethodsTaskEngine,webMethodsTradingNetworks,webMethodsWorkflow,andwebMethodsareeitherregistered
trademarksortrademarksofwebMethods,Inc.
Acrobat,Acrobat,andReaderareregisteredtrademarksofAdobeSystemsIncorporated.AmdocsandClarifyCRMareregisteredtrademarksofAmdocs.
AribaisaregisteredtrademarkofAriba,Inc.BEA,BEAWebLogicServer,Jolt,andTuxedoareregisteredtrademarks,andBEAWebLogicPlatformisa
trademarkofBEASystems,Inc.ActionRequestSystem,BMCSoftware,PATROL,andRemedyareregisteredtrademarksofBMCSoftware,Inc.BroadVision
isaregisteredtrademarkofBroadVision,Inc.ChemeStandardsandCIDXaretrademarksofCIDX,TheChemicalIndustryDataExchange.SiteMinderand
UnicenterareregisteredtrademarksofCA,Inc.PopChartisaregisteredtrademarkofCORDATechnologies,Inc.KenanandArborareregisteredtrademarks
ofAlcatelLucent.DataConnectionandSNAPIXareregisteredtrademarksofDataConnectionCorporation.D&BandDUNSareregisteredtrademarksof
Dun&BradstreetCorporation.EclipseisatrademarkofEclipseFoundation,Inc.EntrustisaregisteredtrademarkofEntrust,Inc.papiNetisaregistered
trademarkoftheEuropeanUnionandtheUnitedStates.FinancialInformationeXchange,F.I.X,andF.I.XProtocolaretrademarksofFIXProtocolLtd.
UCCnetandeBusinessReadyareregisteredtrademarks,and1SYNCandTransoraaretrademarksofGS1US.HewlettPackard,HP,HPUX,OpenView,PA
RISC,andSNAplus2aretrademarksofHewlettPackardCompany.i2isaregisteredtrademarkofi2Technologies,Inc.AIX,AS/400,CICS,ClearCase,DB2,
Domino,IBM,Informix,Infoprint,Lotus,LotusNotes,MQSeries,OS/390,OS/400,RACF,RS/6000,SQL/400,S/390,System/390,VTAM,andWebSphere,and
z/OSareregisteredtrademarks;andCommunicationsSystemforWindowsNT,DB2UniversalDatabase,IMS,MVS,andSQL/DSaretrademarksofIBM
Corporation.InnoDBisatrademarkofInnobaseOy.ItaniumisaregisteredtrademarkofIntelCorporation.LinuxisaregisteredtrademarkofLinus
Torvalds.W3Cisaregisteredtrademark,andXWindowSystemisatrademarkoftheMassachusettsInstituteofTechnology.MetaSolvisaregistered
trademarkofMetasolvSoftware,Inc.ActiveX,Microsoft,Outlook,VisualBasic,VisualSourceSafe,Windows,WindowsNT,andWindowsServerare
registeredtrademarksofMicrosoftCorporation.SixSigmaisaregisteredtrademarkofMotorola,Inc.FirefoxandMozillaareregisteredtrademarksofthe
MozillaFoundation.MySQLisaregisteredtrademarkofMySQLAB.nCipherisatrademarkofnCipherCorporationLtd.EclipseisatrademarkofEclipse
Foundation,Inc.EntrustisaregisteredtrademarkofEntrust,Inc.papiNetisaregisteredtrademarkoftheEuropeanUnionandtheUnitedStates.Financial
InformationeXchange,F.I.X,andF.I.XProtocolaretrademarksofFIXProtocolLtd.UCCnetandeBusinessReadyareregisteredtrademarks,and1SYNCand
TransoraaretrademarksofGS1US.HewlettPackard,HP,HPUX,OpenView,PARISC,andSNAplus2aretrademarksofHewlettPackardCompany.i2isa
registeredtrademarkofi2Technologies,Inc.AIX,AS/400,CICS,ClearCase,DB2,Domino,IBM,Informix,Infoprint,Lotus,LotusNotes,MQSeries,OS/390,
OS/400,RACF,RS/6000,SQL/400,S/390,System/390,VTAM,andWebSphere,andz/OSareregisteredtrademarks;andCommunicationsSystemforWindows
NT,DB2UniversalDatabase,IMS,MVS,andSQL/DSaretrademarksofIBMCorporation.InnoDBisatrademarkofInnobaseOy.Itaniumisaregistered
trademarkofIntelCorporation.TeradataisaregisteredtrademarkofNCRCorporation.NetscapeisaregisteredtrademarkofNetscapeCommunications
Corporation.ServletExecisaregisteredtrademark,andNewAtlantaisatrademarkofNewAtlantaCommunications,LLC.SUSEisaregisteredtrademark
ofNovell,Inc.AppiaisaregisteredtrademarkandJavelinTechnologiesisatrademarkofNYFIX,Inc.CORBAisaregisteredtrademarkofObject
ManagementGroup,Inc.JDEdwards,OneWorld,Oracle,PeopleSoft,Siebel,andVantiveareregisteredtrademarks;andInfranet,PeopleSoftPureInternet
Architecture,Portal,andWorldSoftwarearetrademarksofOracleCorporation.PerforceisatrademarkofPerforceSoftware.JBossandRedHatare
registeredtrademarksofRedHat,Inc.PIPandRosettaNetaretrademarksofRosettaNet,anonprofitorganization.SAPandR/3areregisteredtrademarks
ofSAPAG.PVCSisaregisteredtrademarkofSerenaSoftware,Inc.SWIFTandSWIFTNetareregisteredtrademarksofSocietyforWorldwideInterbank
FinancialTelecommunicationSCRL.SPARCandSPARCStationareregisteredtrademarksofSPARCInternational,Inc.BAANandSSAareregistered
trademarks;andSSAGlobalisatrademarkofSSAGlobalTechnologies,Inc.EJB,EnterpriseJavaBeans,Java,JavaServer,JDBC,JSP,J2EE,Solaris,Sun,and
SunMicrosystemsareregisteredtrademarks;andJavaNamingandDirectoryInterface,JavaServerPages,SOAPwithAttachmentsAPIforJava,andSunSoft
aretrademarksofSunMicrosystems,Inc.SybaseisaregisteredtrademarkofSybase,Inc.VERITASisaregisteredtrademark,andVERITASClusterServeris
atrademarkofSymantecCorporation.UNIXisaregisteredtrademarkofTheOpenGroup.UnicodeisatrademarkofUnicode,Inc.VeriSignisaregistered
trademarkofVerisign,Inc.
SoftwareAGandallSoftwareAGproductnamesareeithertrademarksorregisteredtrademarksofSoftwareAG.
Otherproductandcompanynamesmentionedhereinmaybethetrademarksoftheirrespectiveowners.
Copyright2007webMethods,Inc.Allrightsreserved.
Copyright2007SoftwareAGand/oritssuppliers,Uhlandstrasse12,64297Darmstadt,Germany.Allrightsreserved.
Document ID: DEV-SOAP-DG-71-20070831
Contents
Contents
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 1. Overview of SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

What is SOAP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What Does a SOAP Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The SOAP Namespace Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SOAP 1.1 Header Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SOAP 1.2 Header Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SOAP Fault Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Trailers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 2. SOAP Support on the webMethods Integration Server . . . . . . . . . . . . . . . . . .

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

Building Solutions that Receive SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is a SOAP Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SOAP Processors Provided by the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Universal Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Implicit and Explicit Universal Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Universal Name Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Services You Use to Interact with the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building Solutions that Send SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SOAP Developers Guide Version 7.1
7
7
7
9
10
10
11
11
12
14
14
15
17
18
21
22
22
22
25
27
31
32
32
33
33
34
37
37
37
Contents
Chapter 4. Using the Default SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Accessing the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Behavior of the Default SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How the Processor Selects the Target Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What if the Requested Service Does Not Exist? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Processor Inputs and Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building Target Services for the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Create a Target Service for the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ExampleTarget Service for Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 5. Composing and Sending SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Composing a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Compose a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ExampleComposing a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Send a SOAP Message via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ExampleSending a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 6. Using the SOAP RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using pub.client:soapRPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ExampleSubmitting a Remote Procedure Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Message Coder and the RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Encoding the Input Parameters for the Remote Procedure Call . . . . . . . . . . . . . . . . . . . . . . . . .
Encoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Encoding Multi-Referenced Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Decoding the Output Parameters from a Remote Procedure Call . . . . . . . . . . . . . . . . . . . . . . .
Decoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Decoding Multi-Referenced Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Appendix A. SOAP Faults Returned by the Integration Server . . . . . . . . . . . . . . . . . . . . .

Basic Structure of a SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Elements of a SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ExampleUnknown SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ExampleException While Processing Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
webMethods SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
39
40
40
40
41
41
42
42
43
44
51
52
52
52
53
57
57
61
65
66
66
70
73
74
75
75
76
77
77
79
80
80
82
82
83
Contents
Appendix B. Encoding/Decoding Data-Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

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

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

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

What is a Custom SOAP Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inputs and Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Create a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Returning Your Own SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ExampleCustom Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering a SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Register a SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing the List of Registered SOAP Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deactivating a Registered SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
136
136
137
137
137
139
139
140
145
146
146
147
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
About This Guide
About This Guide
WelcometotheSOAPDevelopersGuide.ThisguidedescribeshowtousethewebMethods
IntegrationServertoexchangeSOAPmessagesovertheInternet.
Itisforsolutiondeveloperswhoneedtounderstand:
HowtoreceiveandprocessSOAPmessagesandSOAPremoteprocedurecallswith
thewebMethodsIntegrationServer.
HowtosubmitSOAPmessagesandSOAPremoteprocedurecallstootherservers.
Document Conventions
Convention
Description
Bold
Identifieselementsonascreen.
Italic
Identifiesvariableinformationthatyoumustsupplyorchange
basedonyourspecificsituationorenvironment.Identifiestermsthe
firsttimetheyaredefinedintext.Alsoidentifiesserviceinputand
outputvariables.
Narrow font
IdentifiesstoragelocationsforservicesonthewebMethods
IntegrationServerusingtheconventionfolder.subfolder:service.
Typewriter
font
Identifiescharactersandvaluesthatyoumusttypeexactlyor
messagesthatthesystemdisplaysontheconsole.
UPPERCASE
Identifieskeyboardkeys.Keysthatyoumustpresssimultaneously
arejoinedwiththe+symbol.
Directorypathsusethe\directorydelimiterunlessthesubjectis
UNIXspecific.
[]
Optionalkeywordsorvaluesareenclosedin[].Donottypethe[]
symbolsinyourowncode.
Additional Information
ThewebMethodsAdvantageWebsiteathttp://advantage.webmethods.comprovidesyou
withimportantsourcesofinformationaboutwebMethodsproducts:
Troubleshooting Information.ThewebMethodsKnowledgeBaseprovides
troubleshootinginformationformanywebMethodsproducts.
About This Guide
Documentation Feedback.ToprovidefeedbackonwebMethodsdocumentation,goto
theDocumentationFeedbackFormonthewebMethodsBookshelf.
Additional Documentation.Startingwith7.0,youhavetheoptionofdownloadingthe
documentationduringproductinstallationtoasingledirectorycalled
_documentation,locatedbydefaultunderthewebMethodsinstallationdirectory.In
addition,youcanfinddocumentationforallwebMethodsproductsonthe
webMethodsBookshelf.
Chapter 1. Overview of SOAP
What is SOAP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
What Does a SOAP Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1. Overview of SOAP
What is SOAP?
TheSimpleObjectAccessProtocol(SOAP)isastandard,lightweightprotocolfor
exchangingmessagesacrosstheInternet.ItusesXMLtodefineabasicmessagepacket
thatcanbeusedtoconveyanarbitraryXMLdocumentoraremoteprocedurecall(RPC).
What Does a SOAP Message Look Like?

ASOAPmessageusesXMLtoformasimplemessagepacket.Thepacketconsistsofan
envelopethatenclosestwoelements:anoptionalheaderandamandatorybody.
A simple SOAP message packet
SOAP
Envelope
SOAP Header
(optional)
SOAP Body
<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-ENV:Header>
<MSG:priority xmlns:MSG="http://www.gsx.com/gl/">9</MSG:priority>
</SOAP-ENV:Header>
<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: Althoughnotshownintheexampleabove,SOAP1.1alsoallowsadditional,
implementationspecificelementstofollowthebodyofaSOAPmessage.Inthisbook,
suchelementsarereferredtoastrailers.Formoreinformationabouttrailers,seeTrailers
onpage 18.TrailersarenotsupportedwithSOAP1.2.
10
1. Overview of SOAP
The Envelope
TheenvelopeisthetoplevelelementinaSOAPmessage.Itisthecontainerthatholds
theentiremessage.Theenvelopemustbethefirst(thatis,theoutermost)elementina
SOAPmessage.IthasthenameEnvelope.
Theenvelopemaycontainaheaderelement.WhenaSOAPmessagecontainsa
header,theheaderelementmustbethefirstchildwithintheenvelope.Foradditional
informationabouttheheaderelement,seeTheHeaderonpage 12.
Theenvelopemustcontainabodyelement.Thebodycarriesthecontentofthe
message.FormoreinformationaboutthebodyelementseeTheBodyonpage 15.
TheenvelopemustbeassociatedwithaSOAPnamespace.TheSOAPnamespace
servesasthequalifierforthemessagesSOAPrelatedelementsandattributes.Italso
specifiestheXMLschematowhichthemessageconforms.Foradditionalinformation
abouttheSOAPnamespace,seeTheSOAPNamespaceDeclarationbelow.
Theenvelopemayincludeotherimplementationspecificnamespacedeclarations.
TheenvelopemaycontaintheencodingStyleattribute,whichspecifiesthewayinwhich
theelementswithintheenvelopeareserializedanddeserialized.
Theenvelopemaycontainadditionalimplementationspecificattributes,butifit
does,theseattributesmustbenamespacequalified.
Theenvelopemaycontainadditionalimplementationspecificchildrenbesidesthe
headerandbodyelements;however,ifitdoes,theadditionalelementsmustbe
namespacequalifiedandmustfollowthebodyelement.
The SOAP Namespace Declaration

TheprimarypurposeoftheSOAPnamespaceistodistinguishSOAPrelatedelements
andattributesfromtheapplicationspecificelementsandattributesconveyedinthe
message.TheSOAPnamespacealsoservesanotherpurpose;itspecifiestheschemato
whichtheSOAPmessageconforms.
ASOAP1.1messageusesthenamespace http://schemas.xmlsoap.org/soap/envelope/ toqualify
theelementsandattributesthatmakeuptheSOAPmessagepacket.ASOAP1.2message
usesthenamespacehttp://www.w3.org/2003/05/soap-envelope/. ASOAPmessagemustdeclare
thisnamespaceintheSOAPenvelope.Byconvention,theprefixSOAP-ENV (forSOAP1.1)
and env (forSOAP1.2) isgiventotheSOAPnamespace;however,amessagemayuseany
prefixtorepresenttheSOAPnamespace.
11
1. Overview of SOAP
The SOAP namespace

is declared in the
envelope element...
...and is used to qualify

the elements and
attributes that make up
the SOAP packet.
<SOAP-ENV:Envelope
<SOAP-ENV:Header>
.
.
.
</SOAP-ENV:Header>
<SOAP-ENV:Body>
.
.
.
</SOAP-ENV:Body>
MessagesthatconformtotheSimpleObjectAccessProtocol(SOAP)1.1W3CNote08May
2000usethenamespacehttp://schemas.xmlsoap.org/soap/envelope/ andthosethatconformtothe
SOAP1.2W3CRecommendation27April2007specificationusethenamespace
http://www.w3.org/2003/05/soap-envelope/.
Messageswhoseenvelopesdeclareadifferentnamespace,ornonamespace,are
consideredinvalidandarerejectedbyIntegrationServer.
Note: Unlessotherwisenoted,whenthenamespaceprefixSOAP-ENVappearsinthisbook,
itrepresentsthenamespacehttp://schemas.xmlsoap.org/soap/envelope/.
The Header
ASOAPmessagecanincludeanoptionalheadercomponenttostoreadditional
information.Theheaderelementprovidesaplacewhereasendercanpassauxiliary,
implementationspecificinformationsuchasauthorizationcodes,routinginformation,
versionnumbers,ormessageIDs.Forexample,ifyoursolutionroutesinvoicesthrough
oneormoreapprovalstepsbeforepassingittoanaccountspayableprocessor,theheader
couldholdthedocumentsroutinginformation.
WhenaheaderisincludedinaSOAPmessage,itmustappearasthefirstchildelement
withintheenvelopeandmusthavethenameHeader.Aheadermaycontainoneormore
childelements.Eachchildisreferredtoasaheaderentry.Allheaderentriesmustbe
namespacequalified.
12
1. Overview of SOAP
Important! Theinclusionofaheadercomponentandtheinformationitstoresare
implementationspecific.TheSOAPspecificationdoesnotdefineanystandardheader
entries.Itsimplyprovidestheheaderasacontainerthatimplementerscanuseasneeded.
ThepartiesexchangingSOAPmessagesareresponsiblefordefiningheaderentriesfor
processingthem.
ThefollowingexampleshowsaSOAPenvelopecontainingasingleheaderentrycalled
<MSG:priority>.Notethattheentryisnamespacequalified,whichisarequirementofall
headerentriesinaSOAPmessage.
Soap 1.1 message with single header entry
This message has a

header...
...containing one entry
<SOAP-ENV:Envelope
<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>
13
1. Overview of SOAP
SOAP 1.1 Header Attributes

TheSOAP1.1specificationdefinesthefollowingoptionalattributesforaheaderentry.
Theseattributesallowanentrytospecifyitsintendedrecipientandtoindicatewhether
therecipientisrequiredtoprocesstheentry.
Attribute
Description
actor
Identifiestheintendedrecipientoftheheaderentry.Thisattribute
allowsasendertodirectaheaderentrytoaspecificprocess.
mustUnderstand
Indicateswhetherprocessingoftheheaderentryismandatory.
RecipientsthatdonotrecognizeanentrywhosemustUnderstand
attributeissetto1mustrejectthemessageandreturnafaulttothe
client.
ThefollowingexampleshowsaSOAP1.1headerentrythatusesboththeactorand
mustUnderstandattributes.
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>
.
.
.
FormoreinformationaboutusingtheactorandmustUnderstandattributes,seetheSimple
ObjectAccessProtocol(SOAP)1.1W3CNote08May2000at
http://www.w3.org/TR/SOAP/#_Toc478383498.
SOAP 1.2 Header Attributes

TheSOAP1.2specificationdefinestheoptionalattributesforaheaderentry.
14
1. Overview of SOAP
Attribute
Description
encodingStyle
IdentifiestheusageofencodingrulestoserializepartsofaSOAP
message.
role
IdentifiestheSOAPnodetowhichaparticularSOAPheaderentryis
targeted.
mustUnderstand
Identifieswhetherprocessingoftheheaderentryismandatory.
RecipientsthatdonotrecognizeanentrywhosemustUnderstand
attributeissetto1mustrejectthemessageandreturnafaulttothe
client.
relay
IdentifieswhetheraheaderentrytargetedataSOAPreceivermustbe
relayed,ifitisnotprocessed.
ThefollowingexampleshowsaSOAP1.2headerentrythatusesboththeroleand
mustUnderstandattributes.
Message that uses the role and mustUnderstand attributes
This header entry...
...uses both the role

and mustUnderstand
attributes
.
.
.
<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">
rubicon:5555
</MSG:nextDest>
</SOAP-ENV:Header>
.
.
FormoreinformationaboutusingtheroleandmustUnderstandattributes,seetheSOAP1.2
W3CRecommendation27April2007athttp://www.w3.org/TR/2003/RECsoap12part1.
The Body
WhenaSOAPmessageconveysanarbitraryXMLdocument(sometimesreferredtoas
applicationdataorthebusinesspayload),thedocumentiscarriedinthebodyofthemessage.
WhenSOAPisusedasanRPCprotocol,thebodyspecifiesthemethodnamethatthe
clientiscallingandcarriesthemethodsinputvalues.
ASOAPmessagemustcontainabodyelement.ThiselementmustbenamedBody.Ifa
SOAPmessagecontainsaheader,theBodyelementmustappearimmediatelyafterthe
header.Otherwise,thebodymustbethefirstelementintheSOAPenvelope.
EachimmediatechildoftheBodyelementisreferredtoasabodyentry.
15
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: AlthoughaSOAPmessagemustcontainabody,thebodydoesnothavetocontain
data.AmessagethathasanemptyBodyelementisavalidSOAPmessage.
16
1. Overview of SOAP
SOAP Fault Elements

TheSOAPspecificationdefinesonebodyelement,whosenameisFault.Arecipientmust
returntheFaultelementifitcannotprocessaSOAPmessagesuccessfully.SOAP1.2faults
arestructureddifferentlythanSOAP1.1.
TheSOAP1.1faultelementcontainsthefollowingchildelements:
Element
Value
<faultcode>
Aqualifiednameindicatingthetypeoferrorthatoccurred.The
SOAPspecificationdefinesseveralstandarderrorcodes(for
example,SOAP-ENV:Server,SOAP-ENV:Client).See
http://www.w3.org/TR/2000/NOTESOAP20000508/fordetails.
<faultstring>
Astringdescribingthefaultthatoccurred.
<faultactor>
Optional.AURIindicatingwhichprocessorapplicationproduced
thefault.
<detail>
Optional.Anelementcontainingimplementationspecificdetails
abouttheerror.Thiselementmustbepresentiftheerroroccurs
whileprocessingthebodyofthemessage.Foradescriptionofthe
detailelementreturnedbyIntegrationServer,seeAppendix A,
SOAPFaultsReturnedbytheIntegrationServer.
TheSOAP1.2faultelementcontainsthefollowingchildelements:
Element
Value
Code
Anelementcontainingthechildvalue<env:Value>withvalueof
VersionMismatch,mustUnderstand,dataEncodingUnknown,
Sender,Receiver,andtheoptionalsubelements<env:Subcode>and
<env:Value>.
Reason
Anelementintendedtoprovideahumanreadableexplanationof
thefault.Thevalueisintheformofastring.
Node
Optional.AURIfortheSOAPnodethatgeneratedthefault.
Role
Optional.Theroleplayedbythenodethatgeneratedthefault.
Detail
Optional.Anelementcontainingimplementationspecificdetails
abouttheerror.Thiselementmustbepresentiftheerroroccurs
whileprocessingthebodyofthemessage.Foradescriptionofthe
detailelementreturnedbythewebMethodsIntegrationServer,see
Appendix A,SOAPFaultsReturnedbytheIntegrationServer.
Note: Faultsmustbenamespacequalifiedwiththenamespace
http://www.w3.org/2003/05/soapenvelope.
17
1. Overview of SOAP
ThefollowingshowsanexampleoftheSOAP1.1faultthattheIntegrationServerreturns
whenasendersubmitsamessagetoanonexistentSOAPprocessor.
A SOAP message returning a fault
A fault is returned in the

body of a message
<SOAP-ENV:Envelope
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">
<SOAP-ENV:Body>
<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>
WhenyouwriteclientsthatsubmitSOAPmessagestotheIntegrationServer,yourclient
codeshouldtestforthepresenceofafaultcodeandprocesstheresponseappropriately.
ForinformationaboutwhenandhowtheIntegrationServerreturnsaSOAPfault,see
Appendix A,SOAPFaultsReturnedbytheIntegrationServer.
Trailers
TheSOAP1.1specificationpermitsadditionalimplementationspecificelements
(elementsbesidesaheaderandabody)toresideinaSOAPenvelope.TheIntegration
Serverreferstotheseelementsastrailers.IfaSOAPenvelopecarriestrailers,theymust
appearafterthebodyandtheymustbenamespacequalified.
Important! SOAP1.2doesnotsupporttrailers.Ifyouaredesigninganewsolution,
Software AGrecommendsagainsttheuseoftrailers.However,ifyouexchangeSOAP
messageswitholdersystemsthatusetrailers,IntegrationServerprovidesservicesthat
allowthemtowork.
18
1. Overview of SOAP
A SOAP 1.1 message containing two trailers
trailer
trailer
<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>
</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>
</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>
TrailersallowyoutotransmitinformationinaSOAPmessagewithoutplacingitinthe
bodyortheheaderofthemessage.Althoughusedinfrequently,theyarepermittedbythe
SOAP1.1specificationandtheyprovideamechanismthatyoucanusetodeliver
informationtoapreprocessor,amessagehandlerorsomeotherintermediateprocess
withouttrespassingonthemessagesheaderorbody.
19
1. Overview of SOAP
20
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
21
2. SOAP Support on the webMethods Integration Server
Overview
SupportforSOAPisdeliveredbyaSOAPmessagehandlerandasetofbuiltinservices.
Thesefacilitiesallowyouto:
ReceiveandprocessSOAPmessagesviaHTTPorHTTPS.
SubmitSOAPmessagestootherserversviaHTTPorHTTPS.
ComposeanddecomposeSOAPmessagesusingasetofbuiltinservices.
UseRPCEncoded,RPCLiteralorDocumentLiteralmessagingforSOAP1.1requests
andDocumentLiteralmessagingforSOAP1.2requests.
MakeIntegrationServerservicesavailabletoclientsviaRPCEncodedorDocument
Literalbindings.Formoreinformationaboutbindings,seetheWebServices
DevelopersGuide.
SOAP Versions Supported by webMethods Integration Server

ThewebMethodsIntegrationServersupportsSOAP1.1asdescribedinSimpleObject
AccessProtocol(SOAP)1.1W3CNote08May2000athttp://www.w3.org/TR/SOAP/and
SOAP1.2asdescribedinSOAP1.2W3CRecommendation27April2007at
http://www.w3c.org/TR/soap12part1/.
Receiving SOAP Messages with the Integration Server

ThefollowingdiagramillustratestheprocessbywhichIntegrationServerreceivesand
processesSOAPmessages.
22
Processing and receiving a SOAP request
webMethods Integration Server

SOAP Message Handler
1
2
HTTP
ListenerDispatcher
HTTP
Client
3
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

AnHTTPclientsubmitsaSOAPmessagebypostingittotheURLforaSOAPprocessor
ontheIntegrationServer.ASOAPprocessorisaspecialservicethatoperatesonSOAP
messages.
TheURLforaSOAPprocessorhasthefollowingformat:
http://hostName:portNum/soap/[processDirective]
Where...
Is...
hostName
ThenumericIPaddressornameofthewebMethodsIntegration
Server.
portNum
ThenumberofaportonwhichhostNameacceptsHTTPorHTTPS
requests.
processDirective
TheprocessdirectiveassociatedwiththerequestedSOAPprocessor.
TheprocessdirectiveisauniquenamethatyouassigntoaSOAP
processorwhenyouregisteritontheIntegrationServer.If
processDirectiveisomittedorsettodefault,themessageispassed
tothedefaultSOAPprocessor.TheWebServicesprocessoristhe
defaultprocessor;providedwithwebMethodsIntegrationServer.
23
Stage 2
The SOAP Message Handler Invokes the Appropriate SOAP Processor

WhentheIntegrationServerreceivesamessageforaSOAPprocessor,itpassesthe
messagetotheSOAPmessagehandler,whichdoesthefollowing:
VerifiesthattherequestedSOAPprocessorisregisteredontheserver.IftheSOAP
processordoesnotexistorisnotavailable,themessagehandlerreturnsaSOAPfault
containingtheISS.0088.9123orISS.0088.9111error.(Foradescriptionofthese
errormessages,seeAppendix A,SOAPFaultsReturnedbytheIntegrationServer.)
VerifiesthatthemessagedeclarestheappropriateSOAPnamespace.Ifthemessage
doesnotdeclareanamespaceordeclaresanamespaceotherthan
http://schemas.xmlsoap.org/soap/envelope/ (SOAP1.1)orhttp://www.w3.org/2003/05/soapenvelope/(SOAP1.2),themessagehandlerreturnsaSOAPfaultcontainingthe
ISS.0088.9128error.
ValidatesthestructureofthemessageagainsttheSOAPschema(iftheSOAP
processorrequestsmessagevalidation).IfthemessageviolatestheSOAPschema,the
messagehandlerreturnsaSOAPfaultcontainingthe ISS.0088.91125error.
Duringthevalidationstep,themessagehandlervalidatesthestructureoftheSOAP
envelopeonly.Forexample,itensuresthatthemessagehasatleastonebodyelement
andonlyoneheaderelement.
Important! ValidatingtheapplicationdatathatiscarriedinsidetheSOAPenvelopeisthe
responsibilityoftheprocessororapplicationthatconsumestheSOAPmessage.
AfterthemessagehandlerestablishesthattheSOAPprocessorisavailableandhas
receivedavalidSOAPmessage,themessagehandlerdoesthefollowing:
TransformsthemessageintoasoapRequestDataobject.Thisobjectcontainstheentire
SOAPenvelopeinadditiontootheroperationalvaluesthattheIntegrationServer
usestomanagethemessageinternally.
CreatesanemptysoapResponseDataobject.Thisobjectisusedtocomposethemessage
tobereturnedtotheclient.
InvokestherequestedSOAPprocessorandpassesthesoapRequestDataand
soapResponseDataobjectstoit.
24
Stage 3
The SOAP Processor Performs Work and Generates a Response

TheselectedSOAPprocessorhandlesthemessageinsoapRequestData(usuallybycalling
otherservicesonthewebMethodsIntegrationServer)andcomposesaresponsemessage
insoapResponseData.
Note: ForIntegrationServer7.1,theRPCprocessorandtheuseofcustomSOAP
processorsisdeprecated.ProcessorsbuiltwithpriorversionsofIntegrationServerarestill
supported.
Stage 4
The Message Handler Returns the Response to the Client

WhentheSOAPprocessorendsorexits,themessagehandlergeneratesanHTTP
responsefromthemessagecontainedinsoapResponseDataandreturnsittotheclient.
Note: IftheSOAPprocessororoneoftheservicesitcallsthrowsanexception,themessage
handlerautomaticallyreturnsaSOAPfaulttotheclient.
Sending SOAP Messages with the Integration Server

BesidesreceivingandprocessingSOAPmessages,theIntegrationServercansendSOAP
messagestoremoteserversviaHTTP.
TosendaSOAPmessage,execute pub.client:soapHTTPwiththefollowinginputparameters:
Input Parameter
Description
soapRequestData
ThesoapRequestDataobjectcontainingthemessagethatyouwantto
send.Youconstructandpopulatethisobjectusingtheservers
messagecompositionservices(forexample,createSoapData,
addHeaderEntry,addBodyEntry).
address
TheURLwheretheSOAPmessageistobesent.
Example: http://servername:5555/soap/rpc
auth
Optional.TheusernameandpasswordthattheIntegrationServer
mustsupplywhenitconnectstothetargetserver.
25
Input Parameter
Description
validateSOAP
Optional.Indicateswhethertheresponsemessagewillbevalidated
againsttheSOAPschema.
SOAPAction
Setto...
To...
true
Validatetheresponsemessageandthrowanexception
iftheresponsedoesnotconformtotheSOAPschema.
false
Bypassthevalidationprocess(default).
Optional.ValuetowhichyouwanttosettheSOAPActionHTTP
header.
Note: TheSOAPActionheaderwasrequiredbytheinitialSOAP
specificationbuthassincebeendeprecated.TheIntegrationServer
doesnotusetheSOAPActionheaderandacceptsSOAPmessages
thatomitit.Ifyouaredesigningacompletelynewsolution,we
recommendthatyouavoidusingtheSOAPActionheader.However,
ifyouexchangeSOAPmessageswithsystemsthatrequirea
SOAPActionheader,thisparameterallowsyoutosetit.
contentType
Optional.SpecifiesthevalueofContentTypeintheHTTPheader.
loadAs
Optional.SpecifiestheformatofthesoapResponseData.Defaultis
streamforanHTTPserviceandbyteArrayStreamforanHTTPS
service.
timeout
Set to...
To...
stream
Returntheresponsebodyasajava.io.InputStreamobject.
UsethissettingtoinvokeanHTTPWebservice.
bytes
Returntheresponsebodyasabytearray.Usethissetting
ifthemessagebodywillbeusedasinputtoaservicethat
operatesonentireHTMLorXMLdocuments.
byteArray
Stream
Readtheresponsestreamfullyandconverttoa
java.io.ByteArrayStreamobject.Thissettingprevents
datalossoratruncatedSOAPresponseiftheconnection
closesprematurely.UsethissettingtoinvokeanHTTPS
Webservice.
Optional.Time(inmilliseconds)towaitforaresponsefromthe
remoteserverbeforetimingoutandterminatingtherequest.The
defaultvalueistowaitforever.
26
ThisservicereturnsasoapResponseDataobjectthatcontainstheresponsedocument
returnedbythetargetserver.Youusetheserversdataretrievalservices(forexample,
getHeaderEntries,getBody)toretrieveinformationfromthemessage.
FormoreinformationaboutsendingSOAPmessagesfromtheIntegrationServer,see
ComposingandSendingSOAPMessagesonpage 51.
Sending SOAP RPC Messages with the Integration Server

TheIntegrationServersupportsSOAPRPC,whichallowsyoutomakeremoteprocedure
callstootherserverswithSOAP.
Note: SOAPRPCissupportedonlybySOAP1.1.
Tosubmitaremoteprocedurecall,youexecutepub.client:soapRPCwiththefollowingbasic
setofparameters:
Input Parameter
Description
address
AstringspecifyingtheHTTPaddressoftheserveronwhichthe
remoteprocedureresides.(Ifyouaresubmittingtherequesttoa
webMethodsIntegrationServer,remembertodirectittothe
RPCprocessorasshowninthefollowingexample.)
reqParms
Adocument(anIDataobject)whoseelementsrepresentthe
inputparametersthataretobepassedtotheremoteprocedure.
Forexample,ifyouweretopassthreestringparameters,acct,
amt,andorg,containingthevalues,Cash,150.00 andSales,
reqParmswouldcontainthefollowing:
Key
Value
acct
Cash
amt
150.00
org
Sales
Atruntime,thevaluesinreqParmsareXMLencodedbythe
messagecoder.Foradescriptionofthisprocess,seeEncoding
theInputParametersfortheRemoteProcedureCallonpage 74.
27
Input Parameter
Description
method
Adocument(anIDataobject)specifyingtheQNameofthe
requestedprocedure,where:
auth
Key
Description
namespaceName
Astringspecifyingthenamespaceportion
oftheproceduresQName.
localName
Astringspecifyingthelocalportionofthe
proceduresQName.
Adocument(anIDataobject)specifyingtheusernameand
passwordthataretobesubmittedtotheserverspecifiedin
address,where:
Key
Description
type
Astringspecifyingthetypeof
authenticationthattheserveruses.Settype
tobasic.
user
Astringspecifyingtheusernamethatisto
bepresentedtotheserver.
pass
Astringspecifyingthepasswordforthe
usernamespecifiedinuser.
targetInputSignature
Optional.Astringspecifyingthefullyqualifiednameofthe
documenttypethatistobeusedtovalidateandencodethe
contentsofreqParms.Foradescriptionofhowthemessagecoder
usestargetInputSignature,seeEncodingtheInputParametersfor
theRemoteProcedureCallonpage 74.
targetOutputSignature
documenttypethatistobeusedtovalidateanddecodethe
outputvaluereturnedbytheremoteprocedure.Fora
descriptionofhowthemessagecoderusestargetInputSignature,
seeDecodingtheOutputParametersfromaRemoteProcedure
Callonpage 76.
28
Input Parameter
Description
SOAPAction
Optional.Astringspecifyingthevaluetowhichyouwantthe
SOAPActionHTTPheaderset.
specification,buthassincebeendeprecated.TheIntegration
ServerdoesnotusetheSOAPActionheaderandacceptsSOAP
messagesthatomitit.
Ifyouaredesigningacompletelynewsolution,werecommend
thatyouavoidusingtheSOAPActionheader.However,ifyou
exchangeSOAPmessageswithsystemsthatrequirea
contentType
Optional.AstringthatspecifiesthevalueofContentTypeinthe
HTTPheader.
Set to...
To...
text/xml;
charset=utf-8
Default.SpecifythecontenttypeasXML
andthecharacterencodingofthetextas
UTF8.
text/xml
SpecifythecontenttypeasXML.Sincethe
charsetparameterisnotspecified,the
characterencodingofthetextdefaultsto
USASCII.
encoding
Optional.Specifiestheencodingmethod.DefaultvalueisUTF8.
loadAs
Optional.SpecifiestheformatofthesoapResponseData.Default
valueisstreamforanHTTPserviceandbyteArrayStreamforan
HTTPSservice.
Set to...
To...
stream
Returntheresponsebodyasa
java.io.InputStreamobject.Usethisoption
toinvokeanHTTPWebservice.
byteArrayStream
Readtheresponsestreamfullyandconvert
toajava.io.ByteArrayStreamobject.This
settingpreventsdatalossoratruncated
SOAPresponseiftheconnectioncloses
prematurely.Usethissettingtoinvokean
HTTPSWebservice.
29
Input Parameter
Description
timeout
remoteserverbeforetimingoutandterminatingtherequest.The
defaultvalueistowaitforever.
Thisservicereturnsadocument(anIDataobject)calledrespParms,whichcontainsthe
resultsfromtheremoteprocedure.
ForinformationaboutsubmittingSOAPremoteprocedurecallsfromtheIntegration
Server,seeUsingtheSOAPRPCClientonpage 65.
30
Chapter 3. Building Solutions with SOAP
Building Solutions that Receive SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Building Solutions that Send SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
31
3. Building Solutions with SOAP
Building Solutions that Receive SOAP Messages

IfyouarebuildingasolutionthatreceivesandprocessesSOAPmessages,youwillneed
todothefollowing:
UnderstandthestructureoftheSOAPmessagethatclientswillsubmittoyour
IntegrationServer.
DefinetheworkthatyouwanttheIntegrationServertoperformwhenitreceivesthe
SOAPmessage.
DeterminewhethertheSOAPprocessorprovidedbytheIntegrationServerwill
satisfytheneedsofyoursolutionorwhetheryouwillneedtobuildandregistera
customSOAPprocessor.
What is a SOAP Processor?

ASOAPprocessorisaservicethatactsuponSOAPmessagesthattheIntegrationServer
receives.WhentheSOAPmessagehandlerreceivesaSOAPmessage,itinvokestheSOAP
processorbasedontheprocessdirectivespecifiedintheURLrequestedbytheclient.
TheprocessdirectiveisthelastsegmentoftheURLfortheSOAPmessagehandlerona
webMethodsIntegrationServer.Forexample,ifaclientsubmitsaSOAPrequesttothe
followingURL,theSOAPmessagehandlerwouldinvoketheSOAPprocessorregistered
asgenLedger.
http://rubicon:5555/soap/genLedger
The process directive determines the SOAP

processor to which the message is passed
Note: TheSOAPprocessorsthatwereprovidedwithpreviousversionsofIntegration
Serveraredeprecated,butarestillsupported.CustomSOAPprocessorscreatedfor
previousversionsofIntegrationServerarealsodeprecated.
32
SOAP Processors Provided by the Integration Server

TheIntegrationServerisinstalledwiththefollowingSOAPprocessors:
SOAP Processor
Description
default
ThisisabasicprocessorthatinvokesaservicebasedontheQName.
Thisprocessorpassestheentireenvelopetotheservicesthatit
invokes.TheWebServicesprocessoristhedefaultprocessor
providedwithIntegrationServer7.1.
Forinformationaboutthedefaultprocessor,seeUsingtheDefault
SOAPProcessoronpage 39.
RPC
ThisprocessorprocessesSOAPremoteprocedurecalls(messages
thatconformtotheremoteprocedurecall(RPC)sectionoftheSOAP
specification).
ForinformationabouttheRPCprocessor,seeAppendix D,Using
theSOAPRPCProcessor.
Note:TheSOAPRPCProcessorisdeprecatedforIntegrationServer
7.1.ItissupportedonlyforWebserviceconnectorscreatedinearlier
versionsofIntegrationServer.
Universal Names
Auniversalnameisauniquepublicidentifierthatexternalprotocolsusetoreferencea
serviceonawebMethodsIntegrationServer.AQNameisaqualifiedname,madeupofa
namespaceURI,alocalpart,andaprefix.
TheSOAPprocessorroutesmessagestoservicesbasedonaqualifiedname(QName).If
theSOAPmessageincludesanHTTPheader,theQNameisderivedfromtheSOAPAction
(SOAP1.1)orActionHTTP(SOAP1.2)fieldoftheheader.IftheSOAPmessagedoesnot
includeanHTTPheader,theQNameisderivedfromthefirstelementintheSOAPbody.
ThestructureofauniversalnameisthesameasthestructureofaQNameinanXML
namespaceandconsistsoftwoparts:anamespacenameandalocalname.
The namespace name isaqualifierthatdistinguishesawebMethodsIntegrationServer
servicefromotherresourcesontheInternet.Forexample,theremightbemany
resourceswiththenameAcctInfo.AnamespacenamedistinguishesoneAcctInfo
resourcefromanotherbyspecifyingthenameofthecollectiontowhichitbelongs
(similartothewayinwhichastateorprovincenameservestodistinguishcitieswith
thesamenameforexample,Springfield,Illinois,versusSpringfield,Ontario).
LikenamespacesinXML,thenamespaceportionofauniversalnameisexpressedasa
URI.Thisservestoassureuniqueness,becauseURIsarebasedongloballyunique
domainnames.
33
Thenamespaceportionoftheuniversalnamecanconsistofanycombinationof
charactersthatformavalidabsoluteURI(relativeURIsarenotsupported).For
example,thefollowingareallvalidnamespacenames:
http://www.gsx.com
http://www.gsx.com/gl/journals
http://www.ugmed.ch/rsum
ForacompletedescriptionofwhatmakesupavalidURI,seeRFC3986Uniform
ResourceIdentifiers(URI):GenericSyntaxathttp://www.ietf.org/rfc/rfc3986.txt.
The local nameuniquelyidentifiesaservicewithinaparticularnamespace.Many
webMethodsusersuseaservicesunqualifiednameasitslocalname.Underthis
scheme,aservicenamedgl.journals:closeGLwouldhavealocalnameofcloseGL.
LocalnamesfollowthesameconstructionrulesasNCNamesinXML.Basically,a
localnamecanbecomposedofanycombinationofletters,digits,ortheperiod(.),
dash(),andunderscore(_)characters.
Additionally,itmustbeginwithaletteroranunderscorecharacter(the_character).
Thefollowingareexamplesofvalidlocalnames:
addCustOrder
authorize-Level1
gnrent
ForspecificrulesrelatingtoNCNames,seetheNCNamedefinitioninthe
Namespaces in XML specification athttp://www.w3.org/TR/1999/RECxml
names19990114.
Note: TheservernormalizesUniversalNamesaccordingtoUnicodeNormalizationForm
C,asrecommendedbytheCharacterModel,SOAP,andXMLstandards.Thisensuresthat
namescontainingnonASCIIcharacters(particularlythosewithaccentedorcombining
characters)arerepresentedinastandardway.
Forinformationaboutnormalization,seehttp://www.unicode.org/reports/tr15/(Unicode
StandardAnnex#15)andhttp://www.w3.org/TR/charmod/(CharacterModelforthe
WorldWideWeb).
Implicit and Explicit Universal Names

EveryservicethatexistsonawebMethodsIntegrationServerhasanexplicitoranimplicit
universalname.
An explicit universal name isauniversalnamethatyouspecificallyassigntoaservice
withDeveloper.Whenyouassignanexplicituniversalname,youmustspecifyboth
thenamespacenameandthelocalname.
34
Specifying explicit universal names in Developer
You assign an
explicit universal
name on the
Properties panel in
Developer
An implicit universal nameisautomaticallyderivedfromthenameoftheserviceitself.

Theimplicitnameactsastheuniversalnamewhenaservicedoesnothaveanexplicit
universalname.Theserverderivesanimplicitnameasfollows:
Thenamespacenameistheliteralstringhttp://localhost/followedbythefully
qualifiednameofthefolderinwhichtheserviceresidesontheIntegrationServer.
Thelocalnameistheunqualifiednameoftheservice.
Thefollowingtableshowstheimplicitnamesforavarietyofservicenames:
The services 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! ToensureinteroperabilitywithothervendorsimplementationsofSOAP,we
recommendthatyoualwaysassignexplicituniversalnamestothoseservicesthatyou
wanttomakeavailabletoSOAPclients.
Note: EarlierversionsofthewebMethodsSOAPimplementationdidnotincludethe
http://localhost/prefixaspartofanimplicitname.However,theserverisbackward
compatible.ItwillresolveQNamesthatclientssubmitineithertheoldform(withoutthe
httpprefix)orthenewform(withthehttpprefix).
Note: Itispossibleforanimplicitnametomatchtheexplicitnameofanotherservice.
Whenthisconditionexists,theexplicitnametakesprecedence.Thatis,whenauniversal
nameisrequested,theIntegrationServersearchesitsregistryofexplicitnamesfirst.Ifit
doesnotfindtherequestednamethere,itlooksforamatchingimplicitname.
35
To assign, edit, or view an explicit universal name

1
StartDeveloperandconnecttotheserveronwhichtheserviceresides.
FromtheNavigationpanel,opentheservicewhoseuniversalnameyouwantto
assign,edit,orview.
Ifyouwanttoassignoredittheservicesuniversalname,specifythefollowinginthe
Universal name categoryoftheservicesPropertiespanel:
In this field...
Specify...
Namespace name
TheURIthatwillqualifythelocalnameofthisservice.The
namecanbecomposedofanysequenceofcharactersexcept
leadingandtrailingwhitespacecharacters
Local name
Anamethatuniquelyidentifiestheservicewithinthe
collectionencompassedbyNamespace name.Thenamecanbe
composedofanycombinationofletters,digits,ortheperiod
(.),dash(),andunderscore(_)characters.Additionally,itmust
beginwithaletterortheunderscorecharacter.
Note: ManywebMethodsusersusetheunqualifiedportionof
theservicenameasthelocalname.
OntheFilemenu,clickSavetosavethenewsettings.
Important! Whenyouassignanexplicituniversalnametoaservice,youmustentervalues
inboththeNamespace nameandLocal namefields.Ifyouspecifyonefieldbutnottheother,
youwillreceiveanerrormessagewhenyouattempttosavetheservice.Youwillnotbe
permittedtosavetheserviceuntilyouspecifybothpartsoftheuniversalname.
Note: Ifyoumoveaservice,orafoldercontainingaservice,Developerretainstheservices
explicituniversalname.Ifyoucopyaserviceorafoldercontainingaservice,Developer
doesnotretaintheservicesexplicituniversalname.Youmustrestoretheuniversalname
forthecopiedservicebyeditingtheservicesproperties.
To delete an explicit universal name

1
StartDeveloperandconnecttotheserveronwhichtheserviceresides.
FromtheNavigationPanel,opentheservicewhoseuniversalnameyouwantto
delete.
36
IntheUniversal name categoryoftheservicesPropertiespanel,removethecurrent

settingsfromtheNamespace nameandLocal namefields.
OntheFilemenu,clickSavetosavethenewsettings.
The Universal Name Registry

ThewebMethodsIntegrationServermaintainsaregistry,calledtheUniversalName
Registry,whichmapsexplicituniversalnamestotheservicesthattheyrepresent.The
registryisgeneratedeachtimetheIntegrationServerisstartedandismaintainedin
memorywhiletheserverisrunning.
WhenyouusetheDevelopertoassign,modify,ordeleteaservicesuniversalname,you
updatetheUniversalNameRegistry.Toviewthecontentsoftheregistry,youcanexecute
theservicepub.universalName:listinDeveloperandviewthecontentsofthenamesvariable
ontheResultspanel.(ThisserviceresidesintheWmPublicpackage.)
Services You Use to Interact with the Registry

ThefollowingservicescanbeusedtodisplaytheUniversalNameRegistryorlocatethe
nameofaserviceassociatedwithanexplicituniversalname.Formoreinformationabout
theseservices,seethewebMethodsIntegrationServerBuiltInServicesReference.
Service
Description
pub.universalName:list
Returnsadocumentlistcontainingtheentriesinthecurrent
registry.Eachdocumentinthelistrepresentsanentryinthe
registryandcontainsaservicesfullyqualifiedwebMethods
nameandbothpartsofitsexplicituniversalname.
pub.universalName:find
Returnsthefullyqualifiedservicenameforaspecifiedexplicit
universalname.
Building Solutions that Send SOAP Messages

TobuildasolutionthatsendsaSOAPmessagetoaSOAPcompliantserver,youneedto
dothefollowing:
DefinethestructureoftheSOAPmessagethatyouwanttosend.
DeterminewheretheSOAPmessagewillbesubmittedforprocessing(gettheURLof
theserverthatwillprocessthemessage).
UnderstandthestructureoftheSOAPmessagethattheserverwillreturninresponse
totheSOAPmessagethatyousend.
BuildaservicethatcomposestheSOAPmessage,submitsitviaHTTPtothe
appropriateserver,andprocessestheresponse.
37
ForinformationaboutbuildingservicesthatcomposeandsendSOAPmessages,see
ComposingandSendingSOAPMessagesonpage 51.
ForinformationaboutbuildingaservicesthatsubmitSOAPRPCmessagestoremote
servers,seeUsingtheSOAPRPCClientonpage 65.
Note: SOAPRPCmessagesareonlysupportedbySOAP1.1.
38
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
39
4. Using the Default SOAP Processor
Accessing the Default Processor

TheIntegrationServerprovidesadefaultSOAPprocessorregisteredunderthenameWeb
Servicesprocessor.TheSOAPmessagehandlerinvokesthisSOAPprocessorwhenthe
processdirectiveisomittedorwhenthespecifiedprocessdirectiveisundefinedin
IntegrationServer.
ThefollowingexamplesillustratethetwotypesofURLsthatinvokethedefaultprocessor:
http://rubicon:5555/soap/ws/example:calculator
OR
You can specify the ws

process directive...
...or omit the process
directive
http://rubicon:5555/soap/
Behavior of the Default SOAP Processor

ThedefaultSOAPprocessoractsasadispatcherthatdelegatesmessagestootherservices
ontheIntegrationServer.Itdoesthisbyinvokingtheservicewhoseuniversalname
matchesthequalifiedname(QName)ofthemessagebodysfirstelementoroftheaction
fieldinthemessageheader.Thisserviceisreferredtoasthetargetservice.
How the Processor Selects the Target Service

ThedefaultSOAPprocessorselectsatargetservicebymatchingthefullyexpanded
QNametoauniversalname(implicitorexplicit)ofaserviceonthewebMethods
IntegrationServer.
Forexample,ifthedefaultprocessorweretoreceiveaSOAPmessagewiththebody
shownbelow,itwouldinvoketheservicewhoseuniversalnameismadeupofthe
namespacenamehttp://www/exprint.com/GL/andthelocalnameJournalEntry.
.
.
.
<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>
.
.
.
40
Ifthedefaultprocessorreceivedamessagewiththebodyshownbelow,itwouldinvoke
theservicewhoseimplicituniversalnameismadeupofthenamespacename
GL.journals.queriesandthelocalnameviewJournal.(Recallthatanimplicitnameisderivedby
combiningaservicesfullyqualifiedservicenamewiththeprefixstring
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: TheIntegrationServerexpectstheQNameintheincomingSOAPmessagetobe
normalizedaccordingtoUnicodeNormalizationFormC.Normalizationassuresthat
characters)arerepresentedinastandardway.IftheclienthasnotnormalizedtheQName,
theIntegrationServermightnotbeabletoproperlymatchitwithauniversalnameinits
registry.
What if the Requested Service Does Not Exist?

Ifthedefaultprocessorcannotlocatetheservicewhoseuniversalnamematchesthe
QNameofthebodysfirstelementoroftheactionfieldinthemessageheader,itreturnsa
SOAPfaulttotheclientwiththefollowingerror:[ISS.0088.9122] Service
namespaceName:localName does not exist.SeeAppendix A,SOAPFaultsReturned
bytheIntegrationServerforinformationaboutthiserror.
Processor Inputs and Outputs

WhenthedefaultSOAPprocessorcallsatargetservice,itpassestwoinputparametersto
theservice:
soapRequestData,anobjectcontainingtheentireSOAPmessage
soapResponseData,anobjectcontaininganemptySOAPmessage.
Whenthetargetserviceexits,thedefaultSOAPprocessorreturnssoapResponseDatatothe
SOAPmessagehandler.ThemessagehandlerextractstheSOAPmessagefrom
soapResponseDataandreturnsthemessagetotheclient.
41
BeawarethatneitherthedefaultprocessornortheSOAPmessagehandleraddsany
contenttotheresponsemessageinsoapResponseData.Itistheresponsibilityofthetarget
servicetopopulatesoapResponseDatawithmessagecontent.
Building Target Services for the Default Processor

TousethedefaultSOAPprocessor,youmustbuildtargetservicesthatprocessincoming
SOAPmessages.Atargetservicecanbeanytypeofservice:aflowservice,aJavaservice,
aC/C++service.However,itmustacceptasoapRequestDataobjectandasoapResponseData
objectasinput.Additionally,thetargetservicemustproduceasoapResponseDataobject
thatispopulatedwiththedatathatistobereturnedtotheclient.
Atargetservicecancontainanysortoflogic.Atargetserviceusuallyperformsthreebasic
tasks:
ItextractsthepertinentinformationfromtheincomingSOAPmessage.
Itprocessestheinformation(usuallybypassingittooneormoreservicesthat
performsometypeofbusinesslogic).
ItcomposestheresponseSOAPmessagetobereturnedtotheclient.
How to Create a Target Service for the Default Processor

Thefollowingdescribesthegeneralstepsyoutaketocreateatargetserviceforthedefault
processor.
1
Create a new service that has the following signature:

Inputs:
soapRequestData(oftypeObject)
soapResponseData(oftypeObject)
Outputs:
Youcanusepub.soap.utils:requestResponseSpectospecifytheinputsandoutputsforthe
service.
2
Use the SOAP data-retrieval utilities to extract information from the message. Thedata
retrievalutilitiesareservicessuchasgetBodyandgetHeaderEntries,whichyouuseto
fetchelementsfromSOAPmessageobjects.Theseservicesreturntherequested
elementasanXMLnode(oranarrayofXMLnodes).Toextractdatafromthe
returnednode,youqueryitusingthe pub.xml:queryXMLNode service.
42
Important! BeawarethatyoucannotqueryasoapRequestDataobjectdirectly.Toextract
informationfromsoapRequestData(orsimilarSOAPobjects,suchassoapDataand
soapResponseData),youmustuseoneofthedataretrievalservicestoextractan
elementofthemessage(forexample,theheader,thebody,ortheentireenvelope)and
querytheresultingXMLnode.
3
Invoke services to perform work on the extracted data. Afterextractingthedatawithwhich

youwanttowork,youcanpassittoservicesthatcontainyourbusinesslogic.(To
ensurethatthedatayouhaveextractedisinthecorrectformat,youmightwantto
validateitwith pub.schema:validateormakesurethattheservicetowhichyoupassthe
dataperformsdatavalidationonitsinputparameters.)
Use the SOAP message-composition utilities to populate soapResponseData. Themessage

compositionutilitiesareservicessuchasaddHeaderEntryandaddBodyEntrythatyouuse
toaddcontenttotheemptymessageinsoapResponseData.
ThemessagecompositionservicesrequireanXMLnoderepresentationoftheheader
entry,bodyentry,ortrailerthatyouwanttoaddtothemessage.Youcangeneratean
XMLnodeusingtheservicespub.xml:documentToXMLStringandpub.xml:xmlStringToXMLNode.
Foranexampleofhowtodothis,seeStep 3.1inthesamplecodeshownonpage 45.
Note: Bydefault,nodesthatyouaddtoasoapResponseDatamustbenamespace
qualified.Ifyouattempttoaddaheaderentryorbodyentrythatisnotnamespace
qualified,theserverwillthrowanexception.Foradditionalinformation,seethe
pub.soap.utils:addHeaderEntryandpub.soap.utils:addBodyEntryentriesinthewebMethods
IntegrationServerBuiltInServicesReference.
Assign the appropriate universal name to the service.Whenyoufinishbuildingatarget

service,youmustensurethatitsuniversalnamematchestheQNamethatclientswill
usetodirectSOAPmessagestoit.Inotherwords,theservicesuniversalnamemust
matchtheQNameofthefirstelementinthebodyortheactionfieldintheheaderof
theclientsSOAPmessage.Forinformationaboutsettingauniversalname,seeTo
assign,edit,orviewanexplicituniversalnameonpage 36.
Note: Asabestpractice,werecommendthatyoualwaysassignexplicituniversalnames
totargetservices.
Error Handling
Ifatargetservicethrowsanexceptionwhileitisprocessing,themessagehandler
automaticallyreturnsaSOAPfaulttotheclient.Dependingonthetypeoferrorthat
occurs,theSOAPfaultmayincludeadetailelement,whichprovidesspecific
informationabouttheexception.ThiselementwillincludeastackTraceelementifthe
clientisamemberoftheDevelopersorAdministratorsusergroup.
43
<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
</faultstring>
...containing an
error message...
<faultactor>
http://hostName:portNum/soap/processorName
</faultactor>
<detail xmlns="http://www.webmethods.com/2001/10/soap/">
<exception>
<className>nameOfClassThatWasThrown</className>
<message xml:lang="en">detailedMessageIssuedbyException</message>
...and details about
the error.
<stackTrace xml:lang="en-US">textFromStackTrace</stackTrace>
</exception>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Note: TheSOAPmessagereturnedtotheclientwhenanexceptionoccurscontainsonlythe
SOAPfault.Itdoesnotincludeanymessagecontent(forexample,headerentries,body
entries)thatthetargetservicemayhaveinsertedintosoapResponseDatabeforethe
exceptionoccurred.
FormoreinformationaboutSOAPfaults,seeAppendix A,SOAPFaultsReturnedbythe
IntegrationServer.
ExampleTarget Service for Default Processor

ThefollowingisanexampleofatargetservicethattakesaSOAPmessage,extracts
informationfromthebodyofthemessage,passestheinformationtoasetofbusiness
services,andcomposesaSOAPresponsecontainingtheresultsoftheservices.
Thisexampleislocatedinsample.soap:targetSvc_defaultProc intheWmSamplespackage.You
canfindtheWmSamplespackageinthecertifiedsamplesareaoftheKnowledgeBaseon
theAdvantageWebSite.YoumaywanttoopenthisexamplewithDevelopertoseehow
thepipelineismappedbetweensteps.
44
Note: IfyouwanttoexecutethisservicefromDeveloper,enabletheacquireSOAPMessage
stepatthetopoftheflow.ThisservicegeneratesatestsoapRequestDataand
soapResponseDataobject,whichsimulatesthepipelinethatthisservicewouldreceivefrom
thedefaultSOAPprocessor.Ifyouwanttoexecutethisserviceasatargetofthedefault
processor,disabletheacquireSOAPMessagestep.
Target service that extracts data from a SOAP message and composes a response
45
Description
Step 1
Extract data from SOAP Request Message. Thissequenceretrievesseveralspecific

piecesofbusinessdatabyextractingthebodyofthemessagefrom
soapRequestDataandqueryingtheresult.ThisexampleexpectsaSOAP
messagestructuredasfollows:
<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>
Toextractthebusinessdatafromthemessage,thisserviceexecutesthe
followingsteps:
Step
Description
1.1
getBodyThisstepretrievesthebodyofthemessagefrom
soapRequestData.ItreturnsanXMLnodethatrepresentstheentire
Bodyelement.
1.2
queryXMLNodeThisstepextractsthebusinessdatabyexecutingthe
followingXQLqueriesagainsttheXMLnodereturnedinStep 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()
46
Description
IfyouexaminethequeryXMLNodestepwithDeveloper,youwillsee
thatitalsoexecutesthefollowingquery,whichextractstheentire
BodynodetoaString:
Var Name
XQL Query
wholeNode
/source()
Thisqueryisincludedfordebuggingpurposes.Itallowsyouto
examinetherawXMLassociatedwiththeBodynode.Ifyouwereto
putthisserviceintoproduction,youwouldomitthisquery.
1.3
Step 2
MAPThisstepmapstheresultsfromStep 1.2toadocumentthatwill
beprocessedbythebusinessservicesinthenextstep.Italsocleansup
thepipelinebydroppingunneededvariables.
Perform business logic.Thissequenceinvokesbusinessservicesthatprocess

thedataextractedbyStep 1.Inthisexample,thebusinessservicesusethe
datatocalculatethecostofaprintingjob.Theyreturnthecostinavariable
namedqCost.
47
Description
Step 3
Compose SOAP response message. Thissequencegeneratestheresponse

messagethatcarriestheresultsbacktotheclient.ItproducesaSOAP
messagestructuredasfollows:
The service
generates a
header entry
called msgInfo..
...and a body
entry called
quoteResp

<SOAP-ENV:Envelope
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
<SOAP-ENV:Header>
<AUDIT:msgInfo xmlns:AUDIT="http://www.accumon.com/msgTracker">
<msgType>quoteResp</msgType>
<sender>http:www.exprint.com/RFQ</sender>
<docID>RFQ-0.41</docID>
<tStamp>20010731.155453.454</tStamp>
</AUDIT:msgInfo>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<RFQ:quoteResp xmlns:RFQ="http://www.exprint.com/orderSys">
<acct>1417-A199-0404-5POLY</acct>
<jobSpecs>
<ink>P440</ink>
</jobSpecs>
<qCost>2850</qCost>
</RFQ:quoteResp>
</SOAP-ENV:Body>
Toproducethisresponsemessage,theserviceexecutesthefollowingsteps:
Step
Description
3.1
Thissequenceexecutesthefollowingservicestoaddabodyentryto
soapResponseData.
Step
Description
3.1.1
documentToXMLStringThisservicegeneratesa
documentcalledRFQ:quoteResp,whichdescribesthe
bodyentrytobeinsertedintosoapResponseData.Thenit
convertsthatdocumenttoXML.Notethatthe
documentincludesafieldcalled@xmlns:RFQ,which
setsthenamespaceattributeintheresultingXML.
48
Description
3.2
3.3
3.1.2
xmlStringToXMLNodeThisstepconvertstheXMLString
toanXMLnodeobject.(Recallthattoaddabodyentry
tosoapResponseData,youmustplacetheentryinthe
pipelineasanXMLnode.)
3.1.3
addBodyEntryThisstepaddsthebodyentryto
soapResponseData.
Thissequenceexecutesthefollowingservicestoaddaheaderentryto
soapResponseData.
Step
Description
3.2.1
documentToXMLStringThisstepcreatesadocument
calledAUDIT:msgInfo,whichdescribestheheaderentry
tobeinsertedintosoapResponseDataandconvertsthe
documenttoanXMLString.Notethatthedocument
containsafieldcalled@xmlns:AUDIT,whichsetsthe
namespaceattributeintheresultingXML.
3.2.2
xmlStringToXMLNodeThisstepconvertstheXMLString
toanXMLnode.(Recallthattoaddaheaderentryto
soapResponseData,youmustplacetheentryinthe
pipelineasanXMLnode.)
3.2.3
addHeaderEntryThisstepaddstheheaderentryto
soapResponseData.
FOR DEBUG ONLY. ThisstepconvertsthecontentsofsoapResponseData

toaStringusingthesoapDataToStringservice.Thisallowsyouto
examinethefinishedmessagewithDeveloper,whichisusefulduring
testinganddebugging.Youwouldnotincludethisstepina
productionservice.
49
Description
IfyouexaminethecontentsoffinishedMessageontheResultspanel,
youwillseeaSOAPmessagesimilartotheonebelow.Ifthisservice
wereinvokedthroughthedefaultprocessor,themessagehandler
wouldsendthismessagetotheclient.
50
Chapter 5. Composing and Sending SOAP Messages
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Composing a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Sending a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
51
5. Composing and Sending SOAP Messages
Overview
TheIntegrationServerprovidesasetofservicesthatallowyoutogenerateSOAP
messagesandsendthemacrossthenetworkviaHTTP.
Important! IfyouwanttouseSOAPtosubmitremoteprocedurecalls,youcomposethose
messageswithSOAPRPCclient.ForinformationaboutsendingSOAP1.1RPCmessages,
seeUsingtheSOAPRPCClientonpage 65.
Composing a SOAP Message

TocomposeaSOAPmessage,youfirstcreateanemptySOAPobjectwiththe
createSoapDataservice.Thenyouusethemessagecompositionservices(forexample,
addHeaderEntryandaddBodyEntry)toaddcontenttoit.
Note: AlthoughIntegrationServersupportsincomingSOAPmessagesinanyencoding,
SOAPmessagessentfromIntegrationServeralwaysusetheUTF8characterencoding.
How to Compose a SOAP Message

Thefollowingdescribesthegeneralstepsyoutaketocodeaservicethatcomposesa
SOAPmessage.
1
Create an empty SOAP object using pub.soap.utils:createSoapData. Youmustprovidethe

followinginputparameters.TheresultisanemptySOAPobjectnamedsoapDatain
thepipeline.
Name
Description
encoding
Optional.Specifiestheencodingmethod.DefaultvalueisUTF8.
soapProtocol
Optional.IndicatestheSOAPprotocolthattheemptySOAP
objectcomplieswith.Thedefaultvalueisreadfromthe
watt.server.SOAP.defaultProtocolproperty.
Set to...
To...
SOAP1.1
protocol
IndicatetheSOAPobjectcomplieswithSOAP1.1.
SOAP1.2
IndicatetheSOAPobjectcomplieswithSOAP1.2.
52
Add content to soapData using any of the following message-composition services. Youcan
executetheseservicesinanyorder.
Use this service...
To...
pub.soap.utils:addHeaderEntry
Addasingleheaderentrytothemessage.Ifyour
messageincludesmultipleheaderentries,execute
addHeaderEntryonceforeachentrythatyouwantto
add.
pub.soap.utils:addBodyEntry
Addasinglebodyentrytothemessage.Ifyour
messageincludesmultiplebodyentries,execute
addBodyEntryonceforeachentrythatyouwanttoadd.
pub.soap.utils:addTrailer
Addatrailertothemessage.Ifyourmessageincludes
multipletrailers,executeaddTraileronceforeachtrailer
thatyouwanttoadd.
Note:ThisserviceisonlyavailablewithSOAP1.1.
Themessagecompositionservicesrequiretwoinputs:thesoapDataobjecttowhichyou
areaddingcontentandanXMLnoderepresentationoftheelementthatyouwanttoadd.
AnXMLnodeisanobjectthatcontainsaparsedrepresentationofanXMLelement.You
cangenerateanXMLnode,usingthepub.xml:documentToXMLStringand
pub.xml:xmlStringToXMLNode services.ForanexampleofhowtocreateanXMLnode,see
Step 2andStep 3inthesampleshownonpage 54.
Note: BecausemostSOAPimplementationsrequirenamespacequalifiedheaderandbody
entries,theaddHeaderEntryandaddBodyEntryserviceswill,bydefault,throwexceptionsifthe
XMLnodeyoupasstothemisnotnamespacequalified.Thispreventsyoufrom
generatingandtransmittingSOAPmessagesthatarelikelytoberejectedbytheir
recipients.
EarlierversionsoftheIntegrationServerdidnotenforcenamespacechecking.Ifyouhave
asolutionthatproducesunqualifiednodes,youcansuppresstheserversdefault
namespacecheckingbehavior.Forinformation,seethe
watt.server.SOAP.enforceMsgPartNSparameterdescriptioninAppendix C,SOAP
RelatedServerParameters.
WhenyoufinishpopulatingthesoapDataobject,youusepub.client:soapHTTPtosendthe
SOAPmessagetoaserverviaHTTP.Foradetailedprocedure,seeSendingaSOAP
Messageonpage 57.
ExampleComposing a SOAP Message

ThefollowingflowservicegeneratesaSOAPmessagethatcontainstwoheaderentries
andonebodyentry.Thisexampleislocatedinsample.soap:buildMsg_sendHTTPinthe
53
WmSamplespackage.YoucanfindtheWmSamplespackageinthecertifiedsamplesarea
oftheKnowledgeBaseontheAdvantageWebSite.Youmaywanttoopenthisexample
withDevelopertoseehowthepipelineismappedbetweensteps.
Note: Thefollowingisatwopartexample.Thefirstpartillustrateshowtocomposea
SOAPmessage.Thispartisexplainedbelow.Thesecondpartillustrateshowtosendthe
SOAPmessage.ItisexplainedinSendingaSOAPMessageonpage71.
Composing a SOAP message
Description
Step 1
Create empty SOAP object.ThisstepcreatesanemptySOAPobject.Youmust

providethefollowinginputparameters.TheresultisanemptySOAPobject
namedsoapDatainthepipeline.
Name
Description
encoding
Optional.Specifiestheencodingmethod.Defaultvalueis
UTF8.
soapProtocol
Optional.IndicatestheSOAPprotocolthattheempty
SOAPobjectcomplieswith.Thedefaultvalueisreadfrom
thewatt.server.SOAP.defaultProtocolproperty.
Set to...
To...
SOAP1.1
protocol
IndicatetheSOAPobjectcomplieswith
SOAP 1.1.
54
Description
SOAP1.2
Step 2
IndicatetheSOAPobjectcomplieswith
SOAP 1.2.
Add header entries.Thissequencebuildsthefollowingheaderentriesand

addsthemtosoapData:
<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>
Notethatbothentriesarenamespacequalified,asrequiredbytheSOAP
specification.
Note: Insteadofbuildingheaderentriesmanually,youcanusethe
IntegrationServersenhancedWebservicedescriptorcapabilities.
Toaccomplishthis,theserviceexecutesthefollowingsteps:
Step
Description
2.1
generateAuditHeaderThishelperserviceconvertsa
documentrepresentation(anIDataobject)ofthefirst
headerentrytoanXMLnode.(Recallthattoaddaheader
entrytoasoapDataobject,youmustplacetheentryinthe
pipelineasanXMLnode.)Youcanexaminethehelper
servicetounderstandhowthisisaccomplished.
2.2
addHeaderEntryThisstepaddsthefirstheaderentryto
soapData.
2.3
currentDateThisservicegeneratesatimestamp,which
willbeinsertedintothesecondheaderentryinthenext
step.
2.4
generatePostmarkHeaderThishelperserviceconvertsa
documentrepresentationofthesecondheaderentrytoan
XMLnode.Youcanexaminethehelperserviceto
understandhowthisisaccomplished.
2.5
addHeaderEntryThisstepaddsthesecondheaderentryto
soapData.
55
Description
Step 3
Add body entry.Thisstepgeneratesthefollowingbodyentryandaddsitto

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>
Toaccomplishthis,theserviceexecutesthefollowingsteps:
Step 4
Step
Description
3.1
generateBodyEntry_GLThishelperserviceconvertsa
documentrepresentationofthebodyentrytoanXML
node.(RecallthattoaddabodyentrytoasoapDataobject,
youmustplacetheentryinthepipelineasanXMLnode.)
Youcanexaminethehelperservicetounderstandhowthis
isaccomplished.
3.2
addBodyEntryThisstepaddsthebodyentrytosoapData.
FOR DEBUG ONLY. ThisstepconvertsthecontentsofsoapDatatoaStringusing

thesoapDataToStringservice.ThisallowsyoutoexaminethefinishedSOAP
messagewithDeveloper,whichisusefulduringtestinganddebugging.You
wouldnotincludethisstepinaproductionservice.
56
Description
IfyouexaminethecontentsofstringontheResultspanel,youwillseea
SOAPmessagesimilartothefollowing:
Sending a SOAP Message

TousetheIntegrationServertosendaSOAPmessagetoaremoteserver,youcompose
theSOAPmessageinasoapDataobjectasdescribedintheprevioussection(Composing
aSOAPMessageonpage 52),andthenyoupassthatobjecttopub.client:soapHTTP,which
submitsittoaserverthatyouspecify.
SOAPmessagesthatyousendviasoapHTTPelicitaresponse,which,ifthetargetserveris
SOAPcompliant,willbeaSOAPresponsedocument.Therefore,yourservicemustalso
includelogictoprocesstheresponsethatthetargetserverreturns.
How to Send a SOAP Message via HTTP

ThefollowingdescribesthegeneralstepsyoutaketocodeaservicethatsendsaSOAP
messagetoaremoteserverviaHTTP.
57
Compose a SOAP message in a soapData object.ForinformationaboutcomposingSOAP

messages,seeComposingaSOAPMessageonpage 52.
Send the SOAP message to the server using pub.client:soapHTTP. Thisservicetakesthe

SOAPmessagefromthesoapDataobjectproducedbystep 1andpostsittotheURL
thatyouspecify.
NotethatthesoapHTTPserviceexpectstofindtheSOAPmessageinanobjectnamed
soapRequestData.Ifyouarebuildingaflowservice,youwillneedtousethePipelinetab
tomapthesoapDataproducedinstep 1tosoapRequestData.)
BesidesthesoapDataobjectfromstep 1,youmustprovidethefollowingparametersto
soapHTTP:
Name
Description
address
AstringspecifyingtheHTTPaddresstowhichyouwantthe
messageposted.
auth
passwordthattheservicewillsubmittothetargetserver:
Name
Description
type
Astringspecifyingthetypeofauthenticationthatthe
servicewillperform.Settypetobasic.
user
Astringspecifyingtheusernamethatthisservice
willusetoaccessaprotectedresource.
password
Astringspecifyingthepasswordthatthisservicewill
usetoaccessaprotectedresource.
Youmayalsoprovidethefollowingoptionalparameters:
Name
Description
validateSoap
Astringindicatingwhetherornotyouwanttherequestand
responseenvelopetobevalidatedagainsttheSOAPschema.
Set to...
To...
true
ValidatetheSOAPenvelopegeneratedby
soapHTTPandtheonereceivedbysoapHTTP.
WhenvalidateSoapistrue,theservicewill
throwanexceptioniftherequestor
responsedoesnotconformtotheSOAP
schema.
58
Name
Description
false
SOAPAction
Bypassthevalidationprocess.
AstringspecifyingthevalueoftheSOAPActionHTTPheader.
specification,buthassincebeendeprecated.TheIntegration
ServerdoesnotusetheSOAPActionheaderandacceptsSOAP
messagesthatomitit.
Ifyouaredesigningacompletelynewsolution,werecommend
thatyouavoidusingtheSOAPActionheader.However,ifyou
exchangeSOAPmessageswithsystemsthatrequirea
contentType
AstringspecifyingthevalueofContentTypeintheHTTP
header.
Set to...
To...
text/xml;
charset=utf-8
Default.SpecifythecontenttypeasXML
andthecharacterencodingofthemessage
textasUTF8.
text/xml
SpecifythecontenttypeasXML.Sincethe
charsetparameterisnotspecified,the
characterencodingofthemessagetext
defaultstoUSASCII.
timeout
serverhostingtheremoteprocedurebeforetimingoutand
terminatingtherequest.Thedefaultvalueistowaitforever.
loadAs
Optional.SpecifiestheformatofthesoapResponseData.Defaultis
streamforHTTPandbyteArrayStreamforHTTPS.
Set to...
To...
stream
java.io.InputStreamobject.Usethisoption
toinvokeanHTTPWebservice.
59
Name
Description
bytes
Returntheresponsebodyasabytearray.
Usethissettingifthemessagebodywillbe
usedasinputtoaservicethatoperateson
entireHTMLorXMLdocuments.
byteArrayStream
Readtheresponsestreamfullyandconvert
toajava.io.ByteArrayStreamobject.This
settingpreventsdatalossoratruncated
SOAPresponseiftheconnectioncloses
prematurely.
Use the data-retrieval services to fetch information from the response message.Iftheserver
returnsaSOAPmessage,soapHTTPreturnsthemessageinaSOAPobjectcalled
soapResponseData.ToretrievethedatainsoapResponseData,youuseanyofthe
followingdataretrievalservices.
Use this service...
To...
pub.soap.utils:getBody
RetrievethebodyasasingleXMLnode.
pub.soap.utils:getBodyEntries
RetrievethecontentsofthebodyasanarrayofXML
nodes,whereeachelementinthearrayrepresentsa
singlebodyentry.
pub.soap.utils:getDocument
RetrievetheSOAPenvelopeasanXMLnode.
pub.soap.utils:getHeader
RetrievetheheaderasasingleXMLnode.
pub.soap.utils:getHeaderEntries
Retrievethecontentsoftheheaderasanarrayof
XMLnodes,whereeachelementinthearray
representsasingleheaderentry.
pub.soap.utils:getTrailers
RetrievethetrailersasanarrayofXMLnodes,where
eachelementinthearrayrepresentsasingletrailer.
ThedataretrievalservicesreturnanXMLnode(oranarrayofXMLnodes)asoutput.
ToextractinformationfromanXMLnode,youcanqueryitwiththe
pub.xml:queryXMLNode service.SeeStep 2inthesampleflowshownonpage 62foran
exampleofhowtodothis.
ThesoapHTTPservicealsoreturnsastatusparameter,whichyoucanusetotestthe
resultsbeforeprocessingthem.
60
Output Parameter
Description
soapStatus
AstringindicatingwhethertheSOAPrequestmessagewas
processedsuccessfully,where:
A value of...
Indicates that...
Theremoteserversuccessfullyprocessedthe
SOAPrequestmessageandreturnedaSOAP
responsemessage.
TheremoteserverreturnedaSOAPfault,
indicatingthattheSOAPrequestmessagewas
received,butwasnotprocessedsuccessfully.
TheserverreturnedanerrorthatwasnotaSOAP
fault.ThisindicatesthatsometypeofHTTPerror
occurred(often,anHTTP404).Youcancheckthe
statuselementinheadertodeterminewhattypeof
HTTPerroroccurred.
Foranexampleofhowtotestthesevalues,seeStep 2inthefollowingexample.
ExampleSending a SOAP Message

ThefollowingflowservicecomposesaSOAPmessageandthensendsittoaSOAP
processorathttp://localhost:5555/soap/inbox.
IfyouwanttoexecutethisexamplefromDeveloper,youmustfirstexecute
sample.soap:registerCustomProcessor toregisterthecustomProc_msgQueueservicewiththeSOAP
messagehandler(itwillberegisteredundertheinboxprocessdirective).Ifyouarenot
runningtheIntegrationServeronyourlocalmachine,modifytheURLintheaddress
parameterinStep 1topointtothemachinewhereyourserverisrunning.
Thisexamplewillpromptyouforausernameandpasswordwhenyouexecuteit.Torun
thissamplesuccessfully,youmustprovideausernameandpasswordthatbelongstothe
DevelopersACLonyourIntegrationServer.
Note: Thefollowingexampleisbrokenintotwoparts.Thefirstpartillustrateshowto
composeaSOAPmessage.ThispartisexplainedinComposingaSOAPMessageon
page 52.ThesecondpartillustrateshowtosendtheSOAPmessage.Thispartisexplained
below.
61
Sending a SOAP message and processing the response
Description
Step 1
Submit SOAP message to server via HTTP.ThisstepsendstheSOAPmessageto

theSOAPprocessorregisteredunderthenameinbox.NotethatthesoapData
objectcreatedinPart1ismappedtothesoapRequestDatathatthissteptakes
asinput.Thisstepalsosetsthefollowinginputvalues:
Name
Description
address
Thisparameterissetto:
http://localhost:5555/soap/inbox
ThisURLassumesthattheIntegrationServerisrunningon
yourlocalmachineandislisteningforHTTPrequestson
port5555.Ifyourserverisrunningonadifferentmachine
orport,modifythehostnameandportportionsofthis
URL.
62
Description
auth
Thisdocumentspecifiestheusernameandpasswordthat
thisservicewillusetoconnecttotheIntegrationServer.
ThesevaluesaremappedfromtheuserNameandpassword
parametersthatthisservicetakesasinput.(Whenyou
executethisservicefromDeveloper,youarepromptedfor
thesevalues.)
Thisexamplesubmitsitsmessagetothe
customProc_MsgQueueprocessor,whichiscontrolledby
theDevelopersACL.Tosubmitamessagetothis
processor,youmustprovideausernameandpassword
thatbelongstotheDevelopersACL.
Step 2
Process response from server.ThissequenceprocessestheresultsfromStep 1.

Todeterminewhethertherequestwasprocessedsuccessfully,itchecksthe
stateofthesoapStatusvariable:
If soapStatus is...
Step 3
The service...
Composesanerrormessageandthrowsanexception.A
valueof2indicatesthatanHTTPfailureoccurred.
Extractserrorinformationfromthereturnedmessageand
throwsanexception.Avalueof1indicatesthattheremote
serverreturnedaSOAPfault.
ProcessesthecontentsofsoapResponseData.Avalueof0
indicatesthattheremoteserverreceivedandsuccessfully
processedtheSOAPmessage.
FOR DEBUG ONLY.ThisstepconvertsthecontentsofsoapResponseDatatoa

StringusingsoapDataToString.ThisallowsyoutoexaminetheSOAPresponse
messagewithDeveloper,whichisusefulduringtestinganddebugging.You
wouldnotincludeitinaproductionservice.
63
Description
IfyouexaminethecontentsofstringontheResultspanel,youwillseea
SOAPmessagesimilartothefollowing:
64
Chapter 6. Using the SOAP RPC Client
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Using pub.client:soapRPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
The Message Coder and the RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
65
6. Using the SOAP RPC Client
Overview
TheSOAPRPCclient(pub.client:soapRPC)allowsyoutocallproceduresonremote,SOAP
enabledservers.
TousetheSOAPRPCclientsuccessfully,youneedtohavethefollowinginformation
abouttheprocedurethatyouarecalling:
TheHTTPaddressoftheserveronwhichitresides.
Thecredentials(usernameandpassword),ifany,thatarerequiredtoaccessit.
Thequalifiedname(QName)associatedwiththeprocedure.
Thenamesanddatatypesoftheparametersthattheprocedureexpectsasinputand
returnsasoutput.
Using pub.client:soapRPC
ThefollowingdescribesthegeneralstepsyoutaketosubmitaSOAPremoteprocedure
callfromthewebMethodsIntegrationServer.
1
Invoke pub.client:soapRPCwiththefollowinginputparameters:
Input Parameter
Description
address
AstringspecifyingtheHTTPaddressoftheserveronwhich
theremoteprocedureresides.(Ifyouaresubmittingthe
requesttoawebMethodsIntegrationServer,besuretodirect
ittotheRPCprocessorasshowninthefollowingexample.)
Example: http://rubicon:5555/soap/rpc
reqParms
Adocument(anIDataobject)whoseelementsrepresentthe
inputparametersthataretobepassedtotheremote
procedure.
Forexample,ifyouweretopassthreestringparameters,acct,
amt,andorg,containingthevalues,Cash,150.00 andSales,
reqParmswouldcontainthefollowing:
Key
Value
acct
Cash
amt
150.00
org
Sales
66
Input Parameter
Description
Atruntime,thevaluesinreqParmsareXMLencodedbythe
messagecoder.Foradescriptionofthisprocess,see
EncodingtheInputParametersfortheRemoteProcedure
Callonpage 74.
method
auth
Adocument(anIDataobject)specifyingtheQNameofthe
requestedprocedure,where:
Key
Description
namespaceName
Astringspecifyingthenamespace
portionoftheproceduresQName.
localName
Astringspecifyingthelocalportionof
theproceduresQName.
passwordthataretobesubmittedtotheserverspecifiedin
address,where:
Key
Description
type
Astringspecifyingthetypeof
authenticationthattheserveruses.Set
typetobasic.
user
Astringspecifyingtheusernamethatis
tobepresentedtotheserver.
pass
Astringspecifyingthepasswordforthe
usernamespecifiedinuser.
documenttypethatistobeusedtovalidateandencodethe
contentsofreqParms.Foradescriptionofhowthemessage
coderusestargetInputSignature,seeEncodingtheInput
ParametersfortheRemoteProcedureCallonpage 74.
targetOutputSignature Optional.Astringspecifyingthefullyqualifiednameofthe
documenttypethatistobeusedtovalidateanddecodethe
outputvaluereturnedbytheremoteprocedure.Fora
descriptionofhowthemessagecoderuses
targetInputSignature,seeDecodingtheOutputParameters
fromaRemoteProcedureCallonpage 76.
67
Input Parameter
Description
SOAPAction
Optional.AStringspecifyingthevaluetowhichyouwant
theSOAPActionHTTPheaderset.
Note: TheSOAPActionheaderwasrequiredbytheinitial
SOAPspecification,buthassincebeendeprecated.The
IntegrationServerdoesnotusetheSOAPActionheaderand
acceptsSOAPmessagesthatomitit.
Ifyouaredesigningacompletelynewsolution,we
recommendthatyouavoidusingtheSOAPActionheader.
However,ifyouexchangeSOAPmessageswithsystemsthat
requireaSOAPActionheader,thisparameterallowsyouto
setit.
contentType
Optional.AstringthatspecifiesthevalueofContentTypein
theHTTPheader.
Set to...
To...
text/xml;
charset=utf-8
Default.Specifythecontenttypeas
XMLandthecharacterencodingofthe
textasUTF8.
text/xml
SpecifythecontenttypeasXML.Since
thecharsetparameterisnotspecified,
thecharacterencodingofthetext
defaultstoUSASCII.
encoding
Optional.Specifiestheencodingmethod.Defaultvalueis
UTF8.
loadAs
Optional.SpecifiestheformatofthesoapResponseData.
DefaultvalueisstreamforanHTTPserviceand
byteArrayStreamforanHTTPSservice.
Set to...
To...
stream
java.io.InputStreamobject.Usethis
optiontoinvokeanHTTPWebservice.
68
Input Parameter
Description
byteArrayStream
timeout
Readtheresponsestreamfullyand
converttoajava.io.ByteArrayStream
object.Thissettingpreventsdatalossor
atruncatedSOAPresponseifthe
connectionclosesprematurely.Usethis
settingtoinvokeanHTTPSWeb
service.
Optional.Time(inmilliseconds)towaitforaresponsefrom
theserverhostingtheremoteprocedurebeforetimingout
andterminatingtherequest.Thedefaultvalueistowait
forever.
Process the results returned by pub.client:soapRPC.Iftheremoteprocedurereturnsoutput

values,thosevaluesaredecodedbythemessagecoderandplacedinanIDataobject
calledrespParms.Forexample,iftheprocedurereturnedtwostringparameters,status
andbalance,whosevalueswereclosedand4.95,respParmswouldcontainthe
following:
Key
Value
status
closed
balance
-4.95
Whendecodingtheresults,themessagecoderusesthedocumenttypenamedin
targetOutputSignature(ifonewasspecified)tovalidatethevaluesinrespParms.Fora
descriptionofthedecodingprocess,seeDecodingtheOutputParametersfroma
RemoteProcedureCallonpage 76.
BesidesrespParms,pub.client:soapRPCreturnsthefollowingvalues,whichyoucanuse
todeterminewhethertherequestwasprocessedsuccessfully:
Output Parameter
Description
soapStatus
AStringindicatingwhethertheremoteprocedurecallwas
processedsuccessfully,where:
A value of...
Indicates that...
Theremoteserversuccessfullyreturnedthe
resultsoftheremoteprocedurecall.
TheremoteserverreturnedaSOAPfault,
indicatingthattheremoteprocedurecallwas
received,butwasnotprocessedsuccessfully.
69
Output Parameter
Description
2
header
soapResponseData
Theserverreturnedanerrorthatwasnota
SOAPfault.Thisindicatesthatsometypeof
HTTPerroroccurred(often,anHTTP404).You
cancheckthestatuselementinheader(below)to
determinewhattypeofHTTPerroroccurred.
Adocument(anIDataobject)containinginformationfromthe
HTTPheaderreturnedbytheremoteserver.headercontainsthe
followingelements:
Key
Value
lines
Adocument(anIDataobject)inwhicheach
entryrepresentsafield(line)oftheresponse
header.Keynamesrepresentthenamesofthe
headerfieldsandkeyvaluesareStrings
containingthevaluesoftheheaderfields.
status
AStringcontainingthestatuscodefromthe
HTTPresponse.Forexample,iftheserver
returnsaHTTP404error,statuswillcontain
404.
statusMessage
AStringcontainingthestatusmessagefromthe
HTTPresponse.
ASOAPobjectcontainingtheentireSOAPresponsemessage.
Youcanextractdatafromthisobjectusingthedataretrieval
servicessuchasgetBodyandgetHeaderEntries.(Foracompletelist
ofdataretrievalservices,seepage 60.)
ExampleSubmitting a Remote Procedure Call

ThefollowingflowservicecallsaremoteprocedurethattakesthreeStringparameters
(acct,amt,andloc)andreturnsoneStringparameter(authCode).
Thisexampleislocatedinsample.soap:buildRPC_SendHTTPSimple.Youmaywanttoexamine
itwithwebMethodsDevelopertounderstandhowitsparametersareset.
TheservicecallsaremoteprocedurewhoseQNameismadeupofthenamespacename,
http://www.expt.com/AUTH/,andlocalname,getAuthCode.OnawebMethodsIntegration
Server(version4.6orlater)thisnameisregisteredtosample.soap:targetSvc_rpcProcSimple.
(ThisserviceresidesintheWmSamplespackageandisdescribedinExampleTarget
ServicefortheRPCProcessoronpage 123.Youcanfindthispackageinthecertified
samplesareaoftheKnowledgeBaseontheAdvantageWebSite.)
ToexecutethisexamplefromDeveloper,modifytheURLintheaddressparameterin
Step 1topointtothemachinewhereyourIntegrationServerisrunning.
70
Whenyouexecutethisexample,youwillbepromptedforthefollowingvalues:
For this input parameter...
Enter...
acct
Anystringofcharacters.
amt
Adecimalvalue,suchas150.75or15.00.(Omitcommasfrom
largevalues;otherwise,thevaluewillfailvalidation.)
loc
userName
AusernamethatbelongstotheDevelopersACL.
password
Thepasswordfortheusernamethatyouenteredin
userName.
Example of a service that submits a remote procedure call and processes the response
71
Description
Step 1
Submit remote procedure call. Thisstepcomposestheremoteprocedurecalland

submitsittotheserverspecifiedinaddress.Ifyouexaminethepipeline,youwill
seethatitsinputparametersaresetasfollows:
Name
Description
address
http://localhost:5555/soap/rpc
ThisdirectstherequesttotheRPCprocessorona
webMethodsIntegrationServer.ThisURLassumesthat
theIntegrationServerisrunningonyourlocalmachine
andislisteningforHTTPrequestsonport5555.Ifyour
serverisrunningonadifferentmachineorport,modify
thehostnameandportportionsofthisURL.
auth
Thisdocumentspecifiestheusernameandpassword
thatthisservicewillusetoconnecttothewebMethods
IntegrationServer.Thesevaluesaremappedfromthe
userNameandpasswordparametersthatthisservice
takesasinput.(Whenyouexecutethisservicefrom
webMethodsDeveloper,youarepromptedforthese
values.)
Note: WhenyousubmitaSOAPremoteprocedurecall
toanIntegrationServer,yourcredentialsareverified
againsttheACLforthetargetservice.
method
ThisdocumentspecifiestheQNameoftheremote
procedure.Inthisexample,methodissetasfollows:
Key
Value
namespaceName
http://www.expt.com/AUTH/
localName
getAuthCode
OnthewebMethodsIntegrationServer,thisQName
representstheuniversalnameassignedtotheservice
sample.soap:targetSvc_rpcProcSimple.
reqParms
Thisdocumentcontainstheinputparametersthatare
tobepassedtotheremoteprocedure.Notethat
authCodeReq,adocumentthatispartoftheinput
signatureforthisexample,ismappedtoreqParms.
72
Description
sample.soap.helpers.docTypes:docType_authCodeReq
whichisthenameofadocumenttype.Thisparameter
tellsthemessagecodertovalidatethecontentsof
reqParms(theinputparametersfortheremote
procedure)againstthisdocumenttypeatruntime.It
alsoinstructsthemessagecodertoencodethecontents
ofreqParmsaccordingtothedatatypesspecifiedinthis
documenttype.
targetOutputSignature
sample.soap.helpers.docTypes:docType_authCodeResp
whichisthenameofadocumenttype.Thisparameter
tellsthemessagecodertovalidatethecontentsof
respParms(theresultsfromtheremoteprocedure)
againstthisdocumenttypeatruntime.Italsoinstructs
themessagecodertodecodethecontentsofrespParms
accordingtothedatatypesspecifiedinthisdocument
type.
Step 2
Processresponsefromserver.ThissequenceprocessestheresultsfromStep 1.
Todeterminewhethertherequestwasprocessedsuccessfully,thisstepfirst
checksthestateofthesoapStatusparameter:
If soapStatus is...
The service...
Composesanerrormessageandthrowsanexception.
Avalueof2indicatesthatanHTTPfailureoccurred.
Extractserrorinformationfromthereturnedmessage
andthrowsanexception.Avalueof1indicatesthatthe
remoteserverreturnedaSOAPfault.
ProcessesthecontentsofrespParms.Avalueof0
indicatesthattheremoteserverreturnedtheresultsof
therequestedprocedure.
The Message Coder and the RPC Client

TheSOAPRPCclientengagesthemessagecodertoconverttheinputandoutput
parameterstoandfromXML.
73
Encoding the Input Parameters for the Remote Procedure

Call
Atruntime,theparametersinreqParmsareconvertedtoXMLbythemessagecoder.This
processisknownasencoding.Thewayinwhichthemessagecoderencodesthe
parametersinreqParmsdependsonwhethertargetInputSignatureisset.
IftargetInputSignatureisnotset,themessagecoderencodestheelementsinreqParms
accordingtotheirunderlyingJavaclasses.Forexample,ifaparameterwereofclass
java.lang.Boolean,themessagecoderwouldencodeitasxsi:type="xsd:boolean"in
theresultingXML.Ifthemessagecoderdoesnotrecognizetheunderlyingclass,it
encodestheparameterasastring(itusestheobjectstoString()methodtoproduce
theparametersvalue).
Thefollowingtableshowshowthemessagecoderwouldencodeaparameteramt
(withavalueof500.00)dependingonitsJavaclass.
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>
ForalistofrecognizedJavaclassesandtheXMLdatatypestowhichtheyare
converted,seeAppendix B,Encoding/DecodingDataTypeMapping.
IftargetInputSignatureisset,themessagecoderfirstvalidatesthecontentsofreqParms
againstthedocumenttypespecifiedintargetInputSignature.Iftheparametersin
reqParmsviolatethespecifieddocumenttype,(forexample,ifarequiredparameteris
missingoravalueisnotofthecorrecttype),themessagecoderthrowsanexception.
Iftheparametersarevalid,themessagecoderencodesthemasfollows:
If the parameter is a String,thevalueoftheparameterisencodedaccordingtoits
Content typeproperty.Forexample,ifitsContent typeisnonNegativeInteger
{http://www.w3.org/2001/XMLSchema},thevalueisencodedasan
xsi:type="xsd:nonNegativeInteger".IftheContent typepropertyisnot
specified,themessagecoderencodesthevalueasastring(asthoughitsContent
typewerestring {http://www.w3.org/2001/XMLSchema}).
ThefollowingtableshowshowthemessagecoderwouldencodeaString
parameteramt(withavalueof500.00)fordifferentContentTypevalues.
74
If Content Type were...
The Message Coder would produce...
decimal
{http://www.w3.org/2001/XMLSchema}
<amt xsi:type="xsd:decimal">
500.00</amt>
float{http://www.w3.org/2001/
XMLSchema}
<amt xsi:type="xsd:float">
500.00</amt>
not specified
<amt xsi:type="xsd:string">
500.00</amt>
If the parameter is an Object,thevalueoftheparameterisencodedaccordingtoits

underlyingJavaclass.
Encoding Complex Structures and Arrays

Themessagecoderencodesdocuments(IDataobjects)ascomplexdatatypes.
ThemessagecoderencodesDocumentLists,StringLists,andObjectListsasSOAParrays.
FormoreinformationabouthowthearraysareencodedinSOAPmessages,seethe
ArrayssectionintheSimpleObjectAccessProtocol(SOAP)1.1W3CNote08May2000at
Encoding Multi-Referenced Elements

Bydefault,themessagecodergeneratesreferenceswhenencodingparametersthat
referencethesameunderlyingdatainthepipeline.However,thisbehaviorcanbe
modifiedwiththewatt.server.SOAP.useMultiReferenceparameter.
Whenwatt.server.SOAP.useMultiReferenceistrue,themessagecodergeneratesthe
appropriateidandhrefattributesforparametersthatreferencethesameunderlyingdata.
Forexample,iftheparameterscDateandoDaterefertothesameobject,themessagecoder
encodesthemlikethisifwatt.server.SOAP.useMultiReference=true(orisnotset,
whichistheserversinstalledbehavior):
.
.
.
<cDate id="id1">03/15/2000</cDate>
<amt id="id2">300</amt>
<oDate href="#id1"></oDate>
<acct id=id4>cash</acct>
.
.
.
The oDate parameter is encoded as a reference
75
Andencodesthemlikethisifwatt.server.SOAP.useMultiReference=false:
.
.
.
<cDate>03/15/2000</cDate>
<amt>300</amt>
<oDate>03/15/2000</oDate>
<acct>cash</acct>
.
.
.
The oDate parameter is encoded as an independent element
Formoreinformationaboutwatt.server.SOAP.useMultiReferenceandotherSOAP
relatedserverparameters,seeAppendix C,SOAPRelatedServerParameters.Formore
informationaboutsettingserverparameters,seethewebMethodsIntegrationServer
AdministratorsGuide.
Decoding the Output Parameters from a Remote Procedure

Call
WhentheresultsofaremoteprocedurecallarereturnedtotheSOAPRPCclient,the
messagecoderconvertsthemfromXMLandplacesthem,asJavaObjects,inrespParms.
Thisprocessisknownasdecoding.
Thewayinwhichthemessagecoderdecodestheresultsdependsonwhether
targetOutputSignatureisset.
IftargetOutputSignatureisnotset,theoutputparametersarerenderedaccordingto
thedatatypesdeclaredintheXML.Forexample,itwouldconvertaparameterwhose
datatypeisxsi:type=xsd:decimal toaJavaobjectofclassjava.math.BigDecimal.(Fora
listofXMLdatatypesandtheJavaclassestowhichtheyareconverted,see
Appendix B,Encoding/DecodingDataTypeMapping.)IfanXMLelementdoesnot
declareitstype,theparameterisrenderedasaString.
IftargetOutputSignatureisset,themessagecoderconvertstheoutputparameters
accordingtothedocumenttypespecifiedintargetOutputSignature.
If targetOutputSignature declares a parameter as a String,thevalueisrenderedasa
Stringobject,regardlessofthedatatypedeclaredintheXML.
If targetOutputSignature declares a parameter as an Object,thevalueisrendered
accordingtothedatatypedeclaredintheXML.
WhentargetOutputSignatureisspecified,themessagecoderalsovalidatesthecontents
ofrespParms.IftheparametersreturnedinrespParmsviolatethedocumenttype
specifiedintargetOutputSignature,(forexample,ifarequiredparameterismissingor
avalueisnotofthecorrecttype),themessagecoderthrowsanexception.
76
Decoding Complex Structures and Arrays

Forcomplexdatatypes(XMLelementsthatcontainchildelements),themessagecoder
producesdocuments(IDataobjects)inthepipeline.
Themessagecoderwillcreatearraysofelements(thatis,StringLists,DocumentLists,
Objectlists)forelementsthatareproperlyencodedasSOAParrays.Formoreinformation
abouthowthearraysareencodedinaSOAPmessage,seetheArrayssectioninthe
SimpleObjectAccessProtocol(SOAP)1.1W3CNote08May2000at
Decoding Multi-Referenced Parameters

Themessagecodercanresolveparametersthatarereferencedthroughthehrefattributeas
longasthereferencedvalueappearswithinthebodyoftheSOAPmessage.Themessage
codercannotresolveexternalreferences(referencesthatpointtoresourcesoutsideofthe
message)orreferencesthatpointtoelementsoutsidetheBodyelement.
WithintheBodyelement,thehrefattributemayappearbeforeorafterthevaluethatit
references.Themessagecodercansuccessfullyresolveeithertype.
In a backward reference, a
referenced value appears
before the point where it is
referenced
In a forward reference, a
after the point where it is
referenced
.
.
.
.
.
.
.
.
.
<amt id="id2">300</amt?
.
.
.
Forreferencedelements,themessagecoderputsasinglecopyofthevalueinthepipeline
andgeneratesreferencestoit.
Note: Ifthemessagecodercannotresolveareference,itgeneratesanullobjectforthat
parameter.Italsoreportstheproblemintheserverlogiftheserverisrunningatdebug
level5orhigher.
77
78
Appendix A. SOAP Faults Returned by the Integration Server
Basic Structure of a SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

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

IftheIntegrationServerisnotabletoprocessaSOAPmessage,itreturnsaSOAPfault.A
SOAPfaultisaSOAPmessagewiththefollowingstructure.
<SOAP-ENV:Envelope
xmlns:xsd="http://www.w3.org/1999/XMLSchema">
The body contains the Fault

element, which contains
information about the failure
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode></faultcode>
<faultstring></faultstring>
<faultactor></faultactor>
<detail></detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Elements of a SOAP Fault

ThebodyofaSOAPfaultcontainstheFaultelement.WhentheIntegrationServerreturns
aSOAPfault,itcontainsthefollowingchildren:
Element
Value
<faultcode>
AQNameindicatingtheclassoferrorthatoccurred.Thenamespace
fortheQNamewillbethesameasthatoftheSOAPenvelopeandthe
localnamewillbeoneofthefollowing:
Local Name
Indicates that...
Server
TheIntegrationServerwasnotabletoprocess
themessagebecauseofaproblemonthe
server.
Client
TheIntegrationServerwasnotabletoprocess
themessagebecauseitwasformatted
improperly.
OR
IntegrationServerwasnotabletoprocessthe
messagebecausetheSOAPprocessor(orone
oftheservicesitcalled)threwanexception.
80
Element
Value
MustUnderstand
TheSOAPprocessorcouldnotobeyaheader
elementwhosemustUnderstandattributewas
setto1.
VersionMismatch
TheIntegrationServerdoesnotsupportthe
SOAPnamespacespecifiedintheSOAP
envelope.
<faultstring>
Amessagedescribingtheerror.Foralistofmessagesthatmight
appearinfaultstring,seewebMethodsSOAPFaultsonpage 83.
<faultactor>
AURIindicatingwhichSOAPprocessorreturnedtheerror.
Example: http://rubicon:5555/soap/rpc
<detail>
Anelementcontainingdetailedinformationabouttheerror.The
IntegrationServerreturnsthiselementwhenanexceptionoccurs
whileitisprocessingthemessage.
The <detail>elementreturnedbytheIntegrationServerisfromthe
followingnamespace:
http://www.webmethods.com/2001/10/soap
Itcontainsanelementcalled<exception>,whichhasthefollowing
childrenandprovidesspecificinformationabouttheexception:
Element
Description
<classname>
ThenameoftheJavaclassthatwasthrown.
<message>
Thedetailederrormessagefromthe
exception.
<stackTrace>
AJavastacktrace.
Important! Thiselementisincludedonlyifthe
clientisamemberoftheDevelopersor
AdministratorsgrouponthewebMethods
IntegrationServer.
81
Element
Value
<serviceStackTrace>
Aservicestacktrace.Thiselementisreturned
ifaservicestackisavailabletotheSOAP
messagehandler.Itgenerallyappearsonly
whenanexceptionisthrownbyoneofthe
webMethodsSOAPprocessorsorutilities.
Important! Thiselementisincludedonlyifthe
clientisamemberoftheDevelopersor
AdministratorsgrouponthewebMethods
IntegrationServer.
ExampleUnknown SOAP Processor

ThefollowingisanexampleoftheSOAPfaultthattheIntegrationServerreturnswhena
clientdirectsamessagetoaprocessorthatdoesnotexistontheserver.
<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>
Notethatthisfaultdoesnotincludethe<detail>element.
ExampleException While Processing Message

ThefollowingisanexampleoftheSOAPfaultthattheIntegrationServerreturnsifan
exceptionisthrownwhileitisprocessingaSOAPmessage.Notethatthisfaultincludes
thedetailelement,whichprovidesinformationabouttheexception.
<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>
82
<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

ThefollowingareSOAPrelatederrorsthatareissuedbythewebMethodsIntegration
Server.
[ISC.0076.0013] SOAP Message Coder cannot encode output data; pipeline does not match output
signature.
Cause: TheSOAPmessagecodercouldnotXMLencodetheresultsofaSOAPremote
procedurecallbecauseavariableappearedinthepipelinemorethanonce.
Response: OntheIntegrationServer,examinethetargetservicetodeterminewhyitisnot
producingoutputvaluesthatmatchtheoutputsignature.Correcttheservicessignature
and/orlogicafteridentifyingthesourceoftheproblem.
83
[ISC.0076.0014] SOAP Message Coder failure; a Runtime Exception was thrown in the SOAP Coder
Cause: Themessagecoderencounteredaseriousinternalerror.
Response: ContactSoftware AGCustomerCare.
[ISC.0076.0015] SOAP Message Coder cannot encode variable varName; variable does not have a
valid XML name
Cause: ThemessagecodercouldnotXMLencodetheSOAPRPCrequestorresponse
becausethepipelinecontainedthevariablevarName,whosenameisnotavalidnamefor
anXMLelement.
Response: Thiserroroftenoccursbecausethevariablenamecontainsacolon.Changethe
nameofvarNametoonethatisalsovalidasanXMLelementname(ormapvarNametoa
newvariable,andusethatvariableasyourSOAPRPCinputoroutputparameter).
[ISC.0076.0016] Soap Message Coder warning; unregistered coder for variable varName, using String
Cause: ThemessagecoderwasnotabletorecognizethedatatypeforvarNamesoittreated
thevariableasaString.
Note: Thismessageisawarningthatiswrittentotheserverlogatdebuglevel5and
higher.
Response: ChecktheincomingXMLandverifythatitdeclaresthecorrectdatatype.
[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: ThemessagecoderwasnotabletorecognizethecomplexdatatypeforvarNameso
ittreatedthevariableasadocument(anIDataobject).
higher.
Response: ChecktheincomingXMLandverifythatitdeclaresthecorrectdatatype.
84
[ISC.0076.0019] SOAP Message Coder cannot decode message; encoding style styleName is not a
registered style
Cause: ThemessagecodercouldnotdecodethesubmittedXMLbecauseitdoesnot
supportthespecifiedencodingstyle.
Response: ChecktheincomingXMLandverifythattheencodingStyleattributeisspecified
correctlyandthatitspecifiesastylethattheIntegrationServersupports.
[ISC.0076.0020] Soap Message Coder warning; invalid HREF found reference
Cause: Themessagecodercouldnotresolvethehrefpointingtoreference.Anullvaluewas
producedinstead.
higher.
Response: ExaminetheincomingXMLandmakesurethatthespecifiedreferencepointsto
anelementthatexistsinthebodyofthemessage.
[ISC.0076.0021] SOAP Message Coder cannot decode message; arrayType attribute value attValue is
malformed
Cause: ThemessagecodercouldnotdecodeanXMLencodedarraybecauseitcannot
understandthevalueofthearrayTypeattribute.
Response: ChecktheincomingXMLandmakesurethatthearrayTypeattributeisspecified
correctly.Forexample,makesurethatitisnotmissinga[symbol.
[ISC.0076.0022] SOAP Message Coder cannot decode message; cannot determine type of element
elementName
Cause: ThemessagecodercouldnotdecodetheXMLencodedparametersithasreceived,
becausethesimpleelementelementNamehasanunknowndatatype(forexample,
xsi:type="myDataType").
Response: ChecktheincomingXMLandmakesurethedatatypehasbeenspecified
correctly.Alsomakesurethatitisusingthecorrectnamespace.
[ISC.0076.0023] SOAP Message Coder cannot decode message; unable to create array for arrayType
attribute value attValue
Cause: ThemessagecodercouldnotdecodeanXMLencodedarraybecauseitcouldnot
allocateanarrayofthespecifieddimensions.
correctly.Forexample,makesurethatitdoesnotspecifyanegativedimensionoran
invalidarraysize(forexample,toomanydimensionsordimensionsthatare
85
unrealisticallylarge).Ifthearrayisunusuallylargeortheserverisextremelyverylowon
memory,thepossibilityalsoexiststhatthiserrorwastheresultofanoutofmemory
condition.
[ISC.0076.9101] SOAP Encoding Registrar cannot register encoding style styleName; encoding style
already exists
Cause: Theencodingregistrarencounteredaseriousinternalerror.
[ISC.0076.9102] SOAP Encoding Registrar cannot register Java type typeName; Java type already
exists
Cause: Theencodingregistrarencounteredaseriousinternalerror.
[ISC.0076.9103] SOAP Encoding Registrar cannot register Schema type typeName; Schema type
already exists
Cause: Themessagecodeencounteredaseriousinternalerror.
[ISC.0076.9201] Null mime object received
Cause: ThemessagecodercouldnotdecodetheparametersintheSOAPmessagebecause
themessagedoesnotspecifyanencodingstyle.
Response: ThiserrorusuallyoccursbecausetheSOAPencodingStyleattributeismissing,
misplacedormisspelled.ExaminetheRPCrequestthatwassubmittedtotheIntegration
ServerandensurethattheSOAPEnvelopeincludestheencodingStyleattribute.Alsocheck
thattheencodingStyleattributehasthepropersyntaxandnamespace.
[ISC.0076.9202] No data in buffer!
[ISC.0076.9203] SOAP Message Coder cannot decode message; Invalid number value
Cause: ThemessagecodercouldnotdecodeanXMLencodedarraybecauseoneofits
dimensionsissettoanonnumericvalue.
Response: ChecktheincomingXMLandmakesurethatthearrayTypeattributespecifiesa
positiveinteger.Forexample,makesureithasnotbeeninadvertentlysettoanonnumeric
valuesuchasA.
86
signature, duplicate variable varName in pipeline
Cause: ThemessagecodercouldnotXMLencodetheresultsofaSOAPremoteprocedure
callbecausethevariablevarNameappearedinthepipelinemorethanonce.
producingoutputvaluesthatmatchtheoutputsignatureforvarName.Correctthe
servicessignatureand/orlogicafteridentifyingthesourceoftheproblem.
[ISC.0076.9205] SOAP Message Coder cannot encode variable varName; variable does not have a
valid XML name
Cause: ThemessagecodercouldnotXMLencodetheSOAPRPCrequestorresponse
becausethepipelinecontainedthevariablevarName,whosenameisnotavalidnamefor
anXMLelement.
Response: Thiserroroftenoccursbecausethevariablenamecontainsacolon (:).Change
thenameofvarNametoonethatisalsovalidasanXMLelementname(ormapvarNameto
anewvariable,andusethatvariableasyourSOAPRPCinputoroutputparameter).
[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: ThemessagecodercouldnotdecodetheXMLencodedparametersithasreceived,
becausethesimpleelementelementNamehasanunknowndatatype(forexample,
xsi:type="myDataType").
Response: ChecktheincomingXMLandmakesurethedatatypehasbeenspecified
correctly.Alsomakesurethatitisusingthecorrectnamespace.
[ISC.0076.9209] SOAP Message Coder cannot decode message; unable to create array for arrayType
attribute value attValue
Cause: ThemessagecodercouldnotdecodeanXMLencodedarraybecauseitcouldnot
allocateanarrayofthespecifieddimensions.
correctly.Forexample,makesurethatitdoesnotspecifyanegativedimensionoran
invalidarraysize(e.g.,toomanydimensionsordimensionsthatareunrealisticallylarge).
Ifthearrayisunusuallylargeortheserverisextremelyverylowonmemory,the
possibilityalsoexiststhatthiserrorwastheresultofanoutofmemorycondition.
87
[ISC.0076.9210] SOAP Message Coder cannot decode message; arrayType attribute value attValue is
malformed
Cause: ThemessagecodercouldnotdecodeanXMLencodedarraybecauseitcannot
understandthevalueofthearrayTypeattribute.
Response: ChecktheincomingXMLandmakesurethatthearrayTypeattributeisusingthe
correctsyntax.Forexample,makesurethatitisnotmissinga[symbol.
signature, required variable varName is missing
Cause: ThemessagecodercouldnottransformtheresultsofaSOAPremoteprocedure
callbecausetherequiredvariablevarNamewasnotinthepipeline.
producingtherequiredoutputvariables.Correcttheservicessignatureand/orlogicafter
identifyingthesourceoftheproblem.
signature, extra variable varName in pipeline
[ISS.0088.9102] ASSERTION: The directive directiveName in the URL urlName should be
directiveName
Cause: TheSOAPmessagehandlerencounteredaseriousinternalerror.
[ISS.0088.9103] Error reading SOAP Message from HTTP stream -- appears to be empty
[ISS.0088.9105] Failed to register SOAP Handler directiveName
Cause: TheIntegrationServerwasnotabletosuccessfullyaddthespecifiedSOAP
processortotheprocessorregistry.
Response: VerifythattheSOAPprocessordirectiveandfullyqualifiedservicenamehave
beenspecifiedcorrectly.Thiserrorusuallyoccursbecausethedirectivenameorthe
servicenamehasnotbeenspecified.
88
[ISS.0088.9107] Failed to unregister SOAP Handler directiveName

Cause: TheIntegrationServerwasnotabletosuccessfullyremovethespecifiedprocessor
fromtheSOAPProcessorregistry.
Response: Thiserrorgenerallyoccursbecausetheregistrydoesnotcontainaprocessor
registeredtothespecifieddirective.Verifythattheprocessdirectivewasspecified
correctly.(Rememberthatdirectivenamesarecasesensitive.)Alsoverifythatthe
specifieddirectiveiscurrentlyregisteredintheSOAPProcessorregistry.Itmayhave
alreadybeenremoved.
[ISS.0088.9108] SOAP Handler directiveName already registered
Cause: TheIntegrationServerwasnotabletosuccessfullyregistertheSOAPprocessor,
becausetheregistryalreadyhasaprocessorregisteredunderthespecifieddirective.
Response: RegistertheSOAPprocessorunderadifferentdirective.Orunregisterthe
processorthatiscurrentlyregisteredtodirectiveName,andthenregisterthisSOAP
Processor.
[ISS.0088.9109] SOAP is only supported using HTTP POST protocol
Cause: TheSOAPmessagehandlerwasnotabletoaccepttherequestbecausetheSOAP
messagewassubmittedtotheIntegrationServerusingtheHTTPGETmethod.TheSOAP
messagehandleronlyacceptsrequestsviathePOSTmethod(perW3Cspecification).
Response: ModifytheclienttouseHTTPPOSTtosubmitSOAPmessagestothe
IntegrationServer.
[ISS.0088.9110] Invalid BOOLEAN value value for variable varName; must be 0 or 1
Cause: TheaddHeaderEntryutilityfailedbecausethemustUnderstandattributewasnotset
correctly.
Response: Checkthelogicintheprocessthatfailedtomakesurethatitsetsthevalueof
varNametoeither0or1.NoothervaluesarepermittedwhensettingthemustUnderstand
attribute.
[ISS.0088.9111] Cannot load or execute the SOAP processor directiveName
Cause: TheSOAPmessagehandlercannotprocesstheSOAPmessagebecausethe
requestedSOAPprocessorisnonoperational.
Response: Ontheserver,checkthestatusoftheservicethatisregisteredtodirectiveName.
Makesurethisserviceisloadedandoperatingsuccessfully.(Frequentlythiserroroccurs
becausetheprocessorwasmodifiedandthendidnotrecompilesuccessfully.)
89
[ISS.0088.9112] An Exception was thrown in the server

Cause: TheIntegrationServer,theSOAPprocessor,oroneoftheservicesprocessingthe
messagehasthrownanexception.
Response: SeethedetailelementintheSOAPfaulttodeterminetheexceptionthatwas
thrownandwhichprocessitwasthrownby.
[ISS.0088.9113] The SOAP Envelope does not have a Body block
Cause: TheSOAPclientwasgivenasoapRequestDatathatdidnotcontainabodyelement.
Response: ExaminethelogicintheclienttoseewhetheritusesthestringToSoapDataor
streamToSoapDataservicetogeneratetheirSOAPobjects.Ifso,determinewhetherthe
StringorstreamfromwhichtheSOAPobjectwasgeneratedrepresentedavalidSOAP
message.AlsocheckwhethertheSOAPprocessororclientusedanyofthedataremoval
utilities(suchasremoveHeaderEntryorremoveBodyEntry)andmighthaveinadvertently
removedtheentireBodyelement.
[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: TherequestedSOAPutilityfailedtoexecutebecausearequiredparameterwasnot
supplied.
Response: CheckthelogicintheSOAPprocessororclienttomakesurethatitpassesthe
correctparameterstoeachSOAPutilityservicethatitinvokes.
[ISS.0088.9117] One or more header entries were not understood by the SOAP processor
Cause: TheSOAPprocessorhasrejectedtheSOAPmessagebecauseitcannotobeya
mandatoryheaderentry(aheaderentrywhosemustUnderstandattributeisenabled).
[ISS.0088.9118] Parameter paramName must be a valid soapData
Cause: TherequestedSOAPutilityfailedtoexecutebecauseparameterparamNameisnota
SOAPobject.
Response: ExaminethelogicintheSOAPprocessororclientandmakesurethatitpassesa
SOAPobjectinparameterparamName.
90
[ISS.0088.9119] SOAP Processor did NOT return a valid SOAP Response

Cause: ThemessagehandlerdidnotreceiveavalidSOAPmessagefromtheSOAP
processor.
Response: ExaminethelogicintheSOAPprocessortomakesurethatitcomposesthe
SOAPresponsemessagecorrectly.Forexample,checktoseewhetherittheprocessoruses
thestringToSoapDataorstreamToSoapDataservicestogeneratesoapResponseData.Ifso,
determinewhethertheoriginalStringorstreamrepresentsavalidSOAPmessage.Ifthe
SOAPprocessorlogicseemscorrect,contactSoftware AGCustomerCare.Thiswould
indicateaseriousinternalerror.
[ISS.0088.9120] Parameter paramName is not one of the valid data types: dataType
Cause: TherequestedSOAPutilityfailedtoexecutebecauseparameterparamNamedidnot
havethecorrectdatatype.ThetypeindataTypeisthedatatypethatisexpected.
Response: ExaminethelogicintheSOAPprocessororclientandmakesurethatitpasses
toparamNameanobjectofthedatatypespecifiedindataType.
[ISS.0088.9122] Service serviceName does not exist
Cause: TheSOAPfacilitycouldnotcompletetherequestedoperationbecauseitcouldnot
findthespecifiedservice.ThiserrorisissuedbyvariousSOAPprocesses(e.g.,registering
aSOAPprocessor,invokingaSOAPprocessor,invokingatargetservice).
Response: Examinetheprocessthatfailedandmakesurethatitspecifiesthenameofthe
requestedservicecorrectly.Forexample,ifyoureceivethiserrorwhenregisteringaSOAP
processor,checkthatyouhavespecifiedthesvcNameparametercorrectly.Rememberthat
servicenamesarecasesensitive.
[ISS.0088.9123] Requested SOAP processor directiveName is not registered on this server
Cause: TheIntegrationServercouldnotprocesstheSOAPmessagebecauseitdoesnot
havetheSOAPprocessorrequestedbytheclient.
Response: Ontheclientside,verifythatthecorrectprocessdirectiveisspecifiedinthe
URL(rememberthatthedirectiveiscasesensitive).Iftheclienthasspecifiedtheprocess
directivecorrectly,thenusepub.soap.processor:listtoverifythattherequestedprocessoris
registeredontheIntegrationServer.
[ISS.0088.9124] SOAP Message does not conform to the SOAP message model
Cause: TheSOAPmessagepassedtothevalidateSoapDatautilityfailedvalidation(for
example,itismissingtheBodyelementortheHeaderelementfollowsthebody).
Response: Examinethelogicthatproducedthemessageandseewhetheritusesthe
stringToSoapDataorstreamToSoapDataservicetomanuallygenerateaSOAPobjectinsteadof
usingthemessagecompositionservices(e.g.,createSoapData,addHeaderEntry,addBodyEntry).If
91
so,determinewhethertheStringorstreamfromwhichtheSOAPobjectisgenerated
representsavalidSOAPmessage.
AlsocheckwhethertheSOAPprocessororclientusedanyofthedataremovalutilities
(suchasremoveHeaderEntryorremoveBodyEntry)andmighthaveinadvertentlyremoved
requiredportionsoftheSOAPobject(forexample,theentireBodyelement).
[ISS.0088.9125] SOAP request does not conform to the SOAP message model
Cause: TheSOAPmessagehandlercouldnotprocesstheSOAPrequestbecauseitviolates
theSOAPmessageschema(forexample,itismissingtheBodyelementortheHeader
elementfollowsthebody).
Response: Ontheclientside,correctthelogicthatbuildsthemessagetoensurethatit
producesavalidSOAPmessage.
[ISS.0088.9126] SOAP response does not conform to the SOAP message model
Cause: TheSOAPmessagehandlercouldnotreturntheSOAPresponsegeneratedbya
SOAPprocessorontheIntegrationServerbecausethemessageviolatestheSOAP
messageschema.
Response: ExaminethelogicintheSOAPprocessorandseewhetheritusesthe
stringToSoapDataorstreamToSoapDataservicetogenerateaSOAPobject.Ifso,determine
whethertheStringorstreamfromwhichtheSOAPobjectisgeneratedrepresentsavalid
SOAPmessage.Examinethelogicthatproducedthemessageandseewhetheritusesthe
stringToSoapDataorstreamToSoapDataservicetomanuallygenerateaSOAPobjectinsteadof
usingthemessagecompositionservices(e.g.,createSoapData,addHeaderEntry,addBodyEntry).If
so,determinewhethertheStringorstreamfromwhichtheSOAPobjectisgenerated
representsavalidSOAPmessage.AlsocheckwhethertheSOAPprocessororclientused
anyofthedataremovalutilities(suchasremoveHeaderEntryorremoveBodyEntry)andmight
haveinadvertentlyremovedrequiredportionsoftheSOAPobject(forexample,theentire
Bodyelement).
[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: TheSOAPmessagehandlercouldnotprocessthemessagebecausethemessageis
notfromaversionofSOAPthattheIntegrationServersupports.TheIntegrationServer
supportstheversionindicatedinsvrNamespace.
Response: Fromtheclientside,resubmitthemessageusingaversionofSOAPthatthe
IntegrationServersupports.
92
[ISS.0088.9129] Comparison requires an rvalue

Cause: TherequestedSOAPutility(e.g.,addHeaderEntry,addBodyEntry)failedto
executebecauseitreceivedanodethatdoesnotrepresentanenclosedXMLelement.
Response: Thiserrorcanoccurifthenodeismissingopeningandclosingtags(e.g.,the
nodecontainshelloinsteadof<a>hello</a>).Examinetheprocessthatcalledthe
failingutilityandmakesurethatitpassesavalidnodeobjecttotheSOAPutility.
[ISS.0088.9130] Comparison righthand operand evaluates to more than one value
executebecauseitreceivedanodethatdoesnothavearootelement.
Response: ThiserrorcanoccurifthenodecontainsanXMLfragmentthatrepresents
uncontainedelements(e.g.,thenodecontains<b>hello</b> <c>world</c>insteadof
<a> <b>hello</b> <c>world</c> </a> ).Examinethelogicthatcalledthefailing
utilityandmakesurethatitpassesanodecontainingonlyonetoplevelXMLelement.
[ISS.0088.9131] Comparison operator is missing.
executebecauseitreceivedanodethatdoesnotrepresentawellformedXMLdocument.
Response: Thiserrorcanoccurifthenodecontainsoverlappingormissingtags(e.g.,a
nodethatcontains<b>helloor<a> <b>hello <c>world</b></c> </a>).Examine
thelogicthatcalledthefailingutilityandmakesurethatitpassesanodecontainingwell
formedXML.
[ISS.0088.9132] Failed to register SOAP Handler directiveName, illegal characters in directive name
Cause: TheIntegrationServerwasnotabletosuccessfullyregistertheSOAPprocessor,
becausedirectiveNamecontainscharactersthatarenotallowedinadirectivename.
Response: RegistertheSOAPprocessorunderanamethatiscomposedonlyofletters,
digits,orthecharacters -_.!~*'( ).
[ISS.0088.9133] Error while encoding RPC output.
Cause: ThemessagecodercouldnotXMLencodetheparametersassociatedwithaSOAP
remoteprocedurecall.
Response: SeethedetailelementintheSOAPfaultforinformationaboutthespecific
failurethatoccurred.
[ISS.0088.9134] Exception occurred while processing the body of the message.
Cause: TheIntegrationServer,theSOAPprocessor,oroneoftheservicesprocessingthe
SOAPmessagehasthrownanexception.
93
Response: SeethedetailelementintheSOAPfaulttodeterminetheexceptionthatwas
thrownandwhichprocessitwasthrownby.
[ISS.0088.9135] A WMDocument Exception was thrown in the server, usually because an XML block
was not well-formed.
Cause: TheSOAPmessagehandler,thesoapHTTPservice,orthesoapRPCservicehas
receivedaSOAPmessagethatcontainsinvalidXML.
Response: ChecktheprocessthatsubmittedtheSOAPmessagetotheIntegrationServer
andmakesurethatitisproducingvalidXML.Thiserrorusuallyoccursbecauseofabasic
errorintheXMLdocument,suchasmissingtagsoroverlappingelements.
[ISS.0088.9136] A WattEvaluationException was thrown by the XQL Query engine.
Cause: TheXQLqueryprocessorencounteredaseriousinternalerror.
[ISS.0088.9137] Invalid input parameter; paramName must be a Document (IData).
Cause: TherequestedSOAPutilityfailedtoexecutebecausetheobjectpassedin
paramNameisnotanIDataobject.
Response: CheckthelogicintheSOAPprocessororclienttomakesurethatitpassesan
IDatainparamName.
[ISS.0088.9138] Input parameters do not conform to targetInputSignature: validationDetails.
Cause: Thepub.client:soapRPC servicecouldnotsubmittheremoteprocedurecallbecause
theinputparametersdidnotpassthedatavalidationprocess.
Response: Thiserroristhrownwhenaclientsuppliesaninvalidsetofinputparameters
foraSOAPremoteprocedurecall.Specifically,itindicatesthattheparameterssubmitted
topub.client:soapRPCinreqParmsdonotmatchthestructureandconstraintsofthe
documenttypespecifiedintargetInputSignature.
Generally,youwillwanttocodeyourclienttodetectthiskindoferrorandtakesometype
ofcorrectiveactionwhenitoccurs.
[ISS.0088.9139] Output parameters do not conform to targetOutputSignature: validationDetails.
Cause: TheSOAPRPCclientcouldnotsubmittheremoteprocedurecallbecausethe
outputparametersreturnedbytheremoteserverdidnotpassthedatavalidationprocess.
Response: Thiserroristhrownwhenaclientreceivesaninvalidsetofoutputparameters
(results)fromaSOAPremoteprocedurecall.Specifically,itindicatesthattheparameters
returnedtopub.client:soapRPCinrespParmsdonotmatchthestructureandconstraintsofthe
documenttypespecifiedintargetOutputSignature.
94
Generally,youwillwanttocodeyourclienttodetectthiskindoferrorandtakesometype
ofcorrectiveactionwhenitoccurs.
[ISS.0088.9140] Invalid target signature docTypeName, must be a Document Type
Cause: TheSOAPRPCclientcouldnotprocesstheremoteprocedurecallbecauseitwas
notabletovalidatetheinputoroutputparametersassociatedwiththerequest.The
signatureitwasgivenforvalidationisnotadocumenttype.
Response: ExaminethelogicintheSOAPRPCclientandmakesurethattheobjectit
specifiesintargetInputSignatureand/ortargetOutputSignatureisadocumenttype.Thatis,
theseparameters,ifused,specifythefullyqualifiednameofadocumenttypethatexists
ontheIntegrationServer.
[ISS.0088.9141] Invalid target signature docTypeName, Document Type does not exist
Cause: TheSOAPRPCclientcouldnotprocesstheremoteprocedurecallbecauseitwas
notabletovalidatetheinputoroutputparametersassociatedwiththerequest.The
specifieddocumenttypedoesnotexistontheIntegrationServer.
Response: ExaminethelogicintheSOAPRPCclientandmakesurethat
targetOutputSignatureand/ortargetOutputSignaturearecorrectlyspecified.(Remember
thatthenamesofdocumenttypesarecasesensitive.).Alsoverifythatthespecified
documenttypeexistsontheserverandthepackageinwhichitresidesisloadedand
enabled.
[ISS.0088.9142] attribute() incorrect attribute name \"{0}\"
Cause: Thepub.soap.util:addBodyEntryservicefailedbecauseitwasgivenanXMLnodethat
wasnotnamespacequalified.
Response: ExaminethelogicintheSOAPclientortargetservice(dependingonwhich
entityissuedtheerror)andverifythattheXMLnodethattheaddBodyEntryserviceis
attemptingtoaddisnamespacequalified(thatis,thatitincludesthexmlnsattributeand
thattheelementnamehasthepropernamespaceprefix).
Note: ThiserroroccursonlyifnamespacecheckingisenabledontheIntegrationServer.
Seewatt.server.SOAP.enforceMsgPartNSonpage 115.
[ISS.0088.9143] count() takes a query parameter

Cause: Thepub.soap.util:addHeaderEntryservicefailedbecauseitwasgivenanXMLnodethat
wasnotnamespacequalified.
Response: ExaminethelogicintheSOAPclientortargetservice(dependingonwhich
entityissuedtheerror)andverifythattheXMLnodethattheaddHeaderEntryserviceis
attemptingtoaddisnamespacequalified(thatis,thatitincludesthexmlnsattributeand
thattheelementnamehasthepropernamespaceprefix).
95
Note: ThiserroroccursonlyifnamespacecheckingisenabledontheIntegrationServer.
Seewatt.server.SOAP.enforceMsgPartNSonpage 115.
[ISS.0088.9144] This SOAPEnvelope object already contains a valid SOAPHeader object.

Cause: AnattemptwasmadetoaddaSOAPHeaderobjecttotheSOAPEnvelopeofa
SOAPMessagethatalreadycontainsaSOAPHeaderobject.
Response: AnySOAPEnvelopeobjectmustcontainamaximumofoneSOAPHeader
objects.
[ISS.0088.9145] This SOAPEnvelope object does not contain a valid SOAPHeader object.
Cause: AnattemptwasmadetoaccesstheSOAPHeaderobject,buttheSOAPEnvelopeof
theSOAPMessagedoesnotcontainaSOAPHeaderobject.
Response: AddaSOAPHeaderobjecttotheSOAPEnvelopebeforeaccessingit.
[ISS.0088.9146] This SOAPEnvelope object already contains a valid SOAPBody object.
Cause: AnattemptwasmadetoaddaSOAPBodyobjecttotheSOAPEnvelopeofa
SOAPMessagethatalreadycontainsaSOAPBodyobject.
Response: AnySOAPEnvelopeobjectmustcontainexactlyoneSOAPBodyobject.
[ISS.0088.9147] This SOAPEnvelope object does not contain a valid SOAPBody object.
Cause: AnattemptwasmadetoaccesstheSOAPBodyobject,buttheSOAPEnvelopeof
theSOAPMessagedoesnotcontainaSOAPBodyobject.
Response: AddaSOAPBodyobjecttotheSOAPEnvelopebeforeaccessingit.
[ISS.0088.9148] Exception occurred while retrieving SOAPHeader object.
Cause: ThespecifiedexceptionoccurredwhileattemptingtoaccesstheSOAPHeader
object.
Response: Correcttheerrorandretry.
[ISS.0088.9149] Exception occurred while retrieving SOAPBody object.
Cause: ThespecifiedexceptionoccurredwhileattemptingtoaccesstheSOAPBodyobject.
96
[ISS.0088.9150] Exception occurred while retrieving SOAPHeaderElement objects.

Cause: Thespecifiedexceptionoccurredwhileattemptingtoaccessthe
SOAPHeaderElementobject.
[ISS.0088.9151] Exception occurred while retrieving SOAPBody Element objects.
Cause: Thespecifiedexceptionoccurredwhileattemptingtoaccessthe
SOAPBodyElementobject.
[ISS.0088.9152] The property <property> is unknown.
Cause: AnattemptwasmadetoeithergetorsetapropertyofthespecifiedSOAPMessage,
unknown.TheonlyvalidSOAPMessagepropertynamesare
javax.xml.soap.WRITE_XML_DECLARATIONand
javax.xml.soap.CHARACTER_SET_ENCODING.
Response: Correctthenameofthepropertytouseoneofthevalidpropertynames.
[ISS.0088.9153] This SOAPMessage object already contains a valid Detail object.
Cause: AnattemptwasmadetoaddaDetailobjecttotheSOAPBodyofthis
SOAPMessage,buttheSOAPBodyalreadycontainsaDetailobject.TheSOAPBodycan
containoneandonlyoneDetailobject.
Response: RemovetheexistingDetailobjectbeforeaddingthenewone.
[ISS.0088.9154] This SOAPMessage object already contains a valid Fault object.
Cause: AnattemptwasmadetoaddaFaultobjecttotheSOAPBodyofthisSOAPMessage,
buttheSOAPBodyalreadycontainsaFaultobject.TheSOAPBodycancontainoneand
oneonlyFaultobject.
Response: RemovetheexistingFaultobjectbeforeaddinganewone.
[ISS.0088.9155] This SOAPMessage does not contain a valid Envelope object.
Cause: ThespecifiedSOAPMessagedoesnotcontainavalidSOAPEnvelopeobject.
Response: CreateanewSOAPMessagethatcontainsavalidSOAPEnvelopeobject.
[ISS.0088.9156] JAX Handler <handler> already registered.
Cause: AnattemptwasmadetoregistertheJAXRPChandler,butthehandlerisalready
registered.
97
Response: Noactionisrequired.
[ISS.0088.9157] Error initializing JAX Handler <handler>:<errorMessage>
Cause: AnerroroccurredwhileinitializingtheJAXRPChandler.Theerrormessageis
specifiedfollowingthecolon.
Response: Correcttheerrorindicatedbytheerrormessageandretry.
[ISS.0088.9158] Error destroying JAX Handler <handler>:<errorMessage>
Cause: AnerroroccurredwhiledestroyingtheJAXRPChandler.Theerrormessageis
specifiedfollowingthecolon.
Response: Correcttheerrorindicatedbytheerrormessageandretry.
[ISS.0088.9159] Failed to register JAX Handler <handler>.
Cause: AnattempttoregistertheJAXRPChandlerfailed.
Response: SearchtheIntegrationServerlogforerrorsindicatingwhytheJAXRPChandler
couldnotberegistered.Correctanyerrorsandretry.
[ISS.0088.9160] Failed to unregister JAX Handler <handler> - Not Registered.
Cause: AnattempttounregistertheJAXRPChandlerfailed.Thehandlerwasnot
registered.
Response: Noactionisrequired.
[ISS.0088.9161] Failed to find JAX Handler <handler> - Not Registered.
Cause: ThespecifiedJAXRPChandlercouldnotbelocatedbecauseitisnotregistered.
Response: RegisterthespecifiedJAXRPChandlerandretry.
[ISS.0088.9162] Failed to find JAX Handler for header <header>
Cause: TheJAXRPChandlerforthespecifiedheaderwasnotfound.
Response: CorrectthenameoftheJAXRPChandlerandretry.
[ISS.0088.9163] Could not retrieve WSDL for service <service>; WSD not found
Cause: AnattempttoretrievetheWSDLforthespecifiedservicefailsbecausetheWeb
servicedescriptordoesnotexist.
Response: CorrectthenameofthewebserviceandverifythattheWebservicedescriptor
exists.
98
[ISS.0088.9164] Access to Web service descriptor <Web service descriptor> denied.

Cause: TheuserisnotauthorizedtoaccessthespecifiedWebservicedescriptor.
Response: SpecifyausernamethatisauthorizedtoaccessthespecificWebservice
descriptor.
[ISS.0088.9251] JAX-RPC Handler failed to process the message.
Cause: TheJAXRPCHandlerwasinvokedtoprocessthemessage.Eitherthe
handleRequest()orhandleResponse()methodreturnedfalse,indicatingafailure.
Response: ChecktheIntegrationServerlogforerrormessagesgeneratedbytheJAXRPC
handler.
[ISS.0088.9252] An exception has been caught: <errorMessage>
Cause: AnexceptionwascaughtwhileattemptingtoprocessaSOAPMessage.
Response: Correcttheproblemindicatedbytheerrormessage.
[ISS.0088.9253] Could not add Text element to Reason element, locale is null.
Cause: AnattempttoaddaTextelementtotheexistingReasonelementfailedbecausethe
localewasnotspecified.
Response: SpecifythelocalewhenaddingtheTextelement.
[ISS.0088.9254] The System property, javax.xml.soap.MetaFactory must be set to
com.wm.app.b2b.server.saaj.SAAJMetaFactory
Cause: Thejavax.xml.soap.MetaFactoryisnotsetproperly.
Response: Setthejavax.xml.soap.MetaFactorypropertyto
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: TheWebservicedescriptoridentifiedbythepartofrequestURL(forprovider)or
passedWebservicedescriptorname(forconsumer)asparameter,doesnotexist.
Response: CorrecttheURLorcorrectthepassedWebservicedescriptornameorcreatea
properWebservicedescriptor.
99
Package; base64Binary encoded data is not in the Canonical Lexical form.
Cause: Base64BinaryencodeddataisnotinCanonicalLexicalform;itcontainslinebreak
charactersortabs.
Response: ConverttheBase64BinarydataintoCanonicalLexicalform.
Package; invalid SOAP Message.
Cause: TheSOAPMessageisinvalid;eitheritisnotwellformedoritdoesnotcontain
validnamespacedeclarations.
Response: CheckthestructureandcontentoftheSOAPmessage.
Package; I/O Error occurred.
Cause: ConvertingSOAPMessagetoXOPpackagehasbeeninterruptedbyanother
thread.
Response: Retrytheactionthatcausedit.
[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: OneormoreattachmentsdoesnotcontaintheContentIdfield.Thisfieldis
requiredtoputthecontentoftheattachmentbackintotheSOAPmessage.
Response: VerifythattheserializationofXOPPackagetoMIMEstreamhadContentId
presentinthecorrespondingMIMEpart.
[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: TheconversionofSOAPStringtobytearrayusingtheencodingspecifiedforSOAP
Messagehasfailed.
Response: CorrectthecontentencodingspecifiedfortheSOAPmessage.
[ISS.0088.9326] MTOM Attachments Processing Failed: Cannot serialize the XOP Message; MIME
serialization has failed.
Cause: SerializationofXOPPackagetoMIMEStreamhasfailed.
Response: VerifythestructureofSOAPMessageiscorrect,particularlytheelementswhich
containsbase64Binarydata.
100
[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: ValuefortheContentTypeheaderfieldoftheMIMEMessageisnotequalto
multipart/related.
Response: VerifythatyouhavepassedthecorrectvalueforContenttypewhile
serializingtheMIMEMessage.
value of the type parameter of the Content-Type header of the MIME message is not equal to
application/xop+xml
Cause: ValueforthetypeparameteroftheContentTypeheaderfieldoftheMIME
messageisnotequaltoapplication/xop+xml.
Response: Verifythatyouhavepassedthecorrectvaluefortypeparameterwhile
serializingtheMIMEmessage.
value of the start-info parameter of the Content-Type header of the MIME message is not equal to
application/xop+xml
Cause: ValueforthestartinfoparameteroftheContentTypeheaderfieldofthe
MIMEmessageisnotequaltoapplication/xop+xml.
Response: Checkifyouhavepassedthecorrectvalueforstartinfoparameterwhile
serializingtheMIMEmessageotherwisepassthecorrectvalueforit.
Content-Type header of the Root MIME Part is invalid.
Cause: InvalidcontenttypeforRootMIMEpart.
Response: VerifythatyouhavepassedthecorrectvalueforContentTypeheaderfieldof
theRootMIMEPartwhileserializingtheMIMEmessage.
Content-Type header of the Root MIME Part does not match with the type parameter of the MIME
message.
Cause: ThevalueoftheContentTypeheaderoftheRootMIMEPartisnotequaltothe
valueofthetypeparameteroftheContentTypeheaderoftheMIMEmessage.
Response: Verifythatyouhavepassedthecorrectvalueforthesefield(s)/parameter(s)
whileserializingtheMIMEmessages.
101
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: ThevalueofthetypeparameteroftheContentTypeheaderoftheRootMIME
PartisnotequaltothevalueofthestartinfoparameteroftheContentTypeheaderof
MIMEmessage.
Response: Verifythatyouhavepassedthecorrectvalueforthesefield(s)/parameter(s)
whileserializingtheMIME.
SOAP Message in the Root MIME Part is not of version 1.2.
Cause: TheversionoftheSOAPMessageisnotequalto1.2.
Response: EdittheversionoftheSOAPMessageto1.2andsendtheSOAP1.2message.
Root MIME Part contains invalid SOAP Message.
Cause: TheSOAPmessageintheRootMIMEPartisinvalid;eitheritisnotwellformedor
itdoesnotcontainvalidnamespacedeclarations.
Response: CheckthestructureandcontentoftheSOAPmessageintheRootMIMEPart.
input stream is not a valid MIME stream.
Cause: MIMEStreamdoesnotcontainthevaliddataaspertheMIMEspecifications.
Response: VerifythattheMIMEstreamcontainsavalidMIMEmessage.
102
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
103
B. Encoding/Decoding Data-Type Mapping
XML-to-Java Mappings (Decoding)

ThefollowingtablesdescribetheJavaobjectsthatthemessagecodercreatesforthe
variousXMLSchemadatatypes.
Note: Themessagecodergeneratestheobjectslistedbelowonlywhenaparameteris
declaredasanObjectintheaccompanyingsignature.Thislistdoesnotapplyto
parametersthatthesignaturedeclaresasStrings.Ifthesignaturedefinesaparameterasa
Stringorifaparameterisnotdefinedinasignature,themessagecoderalwaysrendersit
asaString.
Data types from http://schemas.xmlsoap.org/soap/encoding/

ThefollowingdescribestheJavaobjectstowhichSimpleObjectAccessProtocol(SOAP)1.1
W3CNote08May2000typesareconverted(thatis,typesfromnamespace
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
104
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
105
Data types from http://www.w3.org/1999/XMLSchema

ThefollowingdescribestheJavaobjectstowhichthetypesdefinedinXMLSchema
DatatypesW3CLastCallDraftApril72000areconverted(thatis,typesfromnamespace
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
negativeInteger
BigInteger
nonNegativeInteger
BigInteger
106
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/2000/10/XMLSchema

ThefollowingdescribestheJavaobjectstowhichXMLSchemaDatatypesW3CCandidate
RecommendationOct242000typesareconverted(thatis,typesfromnamespace
http://www.w3.org/2000/10/XMLSchema):
CDATA
String
ENTITIES
String
ENTITY
String
ID
String
IDREF
String
IDREFS
String
hexBinary
byte[]
107
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
negativeInteger
BigInteger
nonNegativeInteger
BigInteger
nonPositiveInteger
BigInteger
positiveInteger
BigInteger
recurringDate
String
recurringDay
String
recurringDuration
String
short
Short
string
String
time
GregorianCalendar
timeDuration
String
108
timeInstant
String
timePeriod
String
token
String
unsignedByte
Short
unsignedInt
Long
unsignedLong
BigInteger
unsignedShort
Integer
uriReference
String
year
String
Data types from http://www.w3.org/2001/XMLSchema

ThefollowingdescribestheJavaobjectstowhichXMLSchemaDatatypesW3C
RecommendationMay22001typesareconverted(thatis,typesfromnamespace
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
109
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
negativeInteger
BigInteger
nonNegativeInteger
BigInteger
nonPositiveInteger
BigInteger
normalizedString
String
positiveInteger
BigInteger
short
Short
string
String
time
GregorianCalendar
token
String
unsignedByte
Short
unsignedInt
Long
unsignedLong
BigInteger
unsignedShort
Integer
110
Java-to-XML Mappings (Encoding)

ThefollowingdescribeshowJavaobjectsareencodedasXMLschemadatatypes.
Note: Thefollowingdatatypesareusedonlywhenmessagecoderisencodingaparameter
thatisdefinedasanObjectintheaccompanyingsignatureorisencodingaparameterthat
isnotdeclaredinasignature.WhenaparameterisdefinedasaStringinthe
accompanyingsignature,itisalwaysencodedaccordingtoitsContent typeconstraint.
Object of type
Is encoded as
type
From namespace
BigDecimal
decimal
http://www.w3.org/2001/XMLSchema
BigInteger
integer
Boolean
boolean
Byte
byte
byte[]
base64
http://schemas.xmlsoap.org/soap/encoding/
Date
date
Document
string
Double
double
ElementNode
string
Float
float
GregorianCalendar
datetime
Hashtable
Hashtable
http://www.webmethods.com/2001/10/soap/encoding
IData*
data
Integer
int
Long
long
MBoolean
boolean
MByte
byte
MDouble
double
MFloat
float
MInteger
int
MLong
long
MShort
short
111
Object of type
Is encoded as
type
From namespace
QName
QName
Short
short
String
string
Vector
Vector
webMethods to XML Mappings (Encoding & Decoding)

Data types from
ThefollowingJavaobjectsareencodedwithwebMethodsspecificdatatypes(thatis,
typesfromnamespacehttp://www.webmethods.com/2001/10/soap/encoding).
Java Object
XML type
Hashtable
Hashtable
Vector
Vector
IData*
data
com.wm.util.Table
dataarray
*OranyclassthatimplementstheIDatainterface(forexample,BasicData,
IDataCodable,Values).
112
Appendix C. SOAP-Related Server Parameters
SOAP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
113
C. SOAP-Related Server Parameters
SOAP Parameters
Thefollowingdescribestheserverparametersthatyoucanusetoconfigurethewayin
whichSOAPoperatesontheIntegrationServer.Forinformationabouthowtosetserver
parameters,seethewebMethodsIntegrationServerAdministratorsGuide.
watt.server.SOAP.directive
SpecifiesthedirectivethatrepresentstheSOAPmessagehandler.Thedefaultissoap.This
parameterdeterminestheURLthatisusedtoaccessSOAPprocessorsontheIntegration
Server.
http://hostName:portNum/soap/[processDirective]
This parameter specifies this segment of the SOAP
processor URL
watt.server.SOAP.defaultProtocol
SpecifiesthedefaultprotocolthatIntegrationServerusesfornewSOAPmessages.
SpecifySOAP1.1ProtocolorSOAP1.2Protocol.ThedefaultisSOAP1.1Protocol.
watt.server.SOAP.MTOMThreshold
Specifiesthefieldsize,inkilobytes,thatdetermineswhetherIntegrationServerhandles
base64binaryencodeddatainaSOAPrequestasaMIMEattachmentorwhetheritsends
itinlineintheSOAPmessage.IftheWebservicedescriptorfortheSOAPmessageenables
attachmentsfortheSOAPrequest,IntegrationServerpassesasMIMEattachmentsany
base64fieldsinaSOAPmessagethatarelargerthanthethreshold.Thisonlyappliesto
SOAP1.2messages.Thedefaultis0.
watt.server.SOAP.validateSOAPMessage
SpecifieswhethertheSOAPmessagehandlerwillvalidatemessagesthatitreceivesand
sends.Settotrueorfalse.Defaultistrue.
Whenwatt.server.SOAP.validateSOAPMessageistrue,themessagehandlervalidates
messagesagainsttheSOAPschema.Beawarethatthethisvalidationprocesschecksonly
thatthemessageenvelopeisstructuredcorrectlyforexample,itchecksthemessagehas
atleastonebodyelementandthereisatmostoneheaderelement.Itdoesnotvalidateany
ofthedatacarriedbythemessage.
Ifyouareoperatinginaproductionenvironmentwherethevalidityofthemessages
submittedtotheserverisassured,youmightset
watt.server.SOAP.validateSOAPMessagetofalsetooptimizeperformance.
Note: ThisparameterisoverriddenbyanindividualSOAPprocessors
validateSOAPMessagesetting.Consequently,theservers
watt.server.SOAP.validateSOAPMessagesettingisusedonlywhenaSOAPprocessors
validateSOAPMessageparameterhasnotbeenset.Formoreinformationaboutsettingthe
validateSOAPMessageparameter,seethepub.soap.processor:registerProcessorserviceinthe
webMethodsIntegrationServerBuiltInServicesReference.
114
watt.server.SOAP.useMultiReference
Specifieshowthemessagecoderistoencodeparametersthatpointtothesame
underlyingdataobjectinthepipeline.Settotrueorfalse.Defaultistrue.
Forexample,iftwooutputparameterscDateandoDatepointtothesameunderlyingdata
inthepipeline,themessagecoderencodestheparameterslikethisif
watt.server.SOAP.useMultiReferenceistrue:
.
.
.
.
.
.
The oDate parameter is encoded as a reference
Andlikethisifwatt.server.SOAP.useMultiReferenceisfalse:
.
.
.
<amt>300</amt>
<acct>cash</acct>
.
.
.
The oDate parameter is encoded as an

independent element
Note: Thisparameteraffectsonlythewayinwhichmultireferencedparametersare
encoded.Itdoesnotaffectthewayinwhichtheyaredecoded.Themessagecoderalways
recognizesanddecodesmultireferencedelementsregardlessofhow
watt.server.SOAP.useMultiReferenceisset.
watt.server.SOAP.enforceMsgPartNS
Specifieswhethertheserverallowsnonnamespacequalifiedheaderandbodyentriesto
beaddedtoaSOAPmessage.Settotrueorfalse.Defaultistrue.
Ifwatt.server.SOAP.enforceMsgPartNS=true,theserverwillthrowanexceptionifthe
pub.soap.utils:addHeaderEntryorpub.soap.utils:addBodyEntryservice(ortheirunderlying
methods)attemptstoinsertanonnamespacequalifiedelementintoaSOAPmessage.If
false,nonnamespacequalifiedelementsarepermitted.
ForinteroperatbilitywithotherSOAPimplementations,werecommendthatyourun
yourserverwiththisparameterenabled(thedefaultsetting).Thisensuresthatyour
serverwillnotgenerateandtransmitSOAPmessagesthathavenonnamespacequalified
headerorbodyentries.
115
116
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
117
D. Using the SOAP RPC Processor
What is the RPC Processor?

TheRPCprocessoristhesubsystemthattheIntegrationServerusestoreceiveandprocess
SOAPremoteprocedurecalls(RPCs).TheRPCprocessorisinvokedwhenthemessage
handlerreceivesaURLwithaprocessdirectivesettorpc,asshownbelow:
http://rubicon:5555/soap/rpc
To submit a SOAP RPC message to the Integration

Server, specify the rpc directive in the URL
Note: TheRPCProcessorisdeprecatedforIntegrationServer7.1.
What Does a SOAP RPC Message Look Like?

ASOAPRPCmessageisanordinarySOAPmessagewhosebodyconveysaremote
procedurecall.ThebodyofanRPCmessagehasastandardstructurethatspecifiesthe
nameoftherequestedprocedureanditsinputparameters.
The qualified name (QName) of the first elementwithinthebodyidentifiestheprocedure
thattheclientiscalling.OntheIntegrationServer,theQNamespecifiestheuniversal
nameoftheservicetobeexecuted.
The children within the first elementrepresenttheinputparametersfortherequested
procedure.
Forexample,thefollowingmessagebodycontainsacalltoaprocedurenamed
GL:journalEntry.Italsoconveysfourinputparameterstothisprocedure:Id,date,amt,
andacct.
Basic structure of a SOAP remote procedure call
The QName of the first

element specifies the
requested procedure...
...and its children

supply the input
parameters.
.
.
.
<SOAP-ENV:Body>
GL:journalEntry xmlns:GL="http://www.expt.com/GL">
<GL:journalEntry
<Id>2398</Id>
<date>03/15/2000</date>
<amt>237.50</amt>
<acct>Cash</acct>
</GL:journalEntry>
</SOAP-ENV:Body>
.
.
.
118
FormoreinformationaboutthestructureofaSOAPRPCmessage,seetheSimpleObject
AccessProtocol(SOAP)1.1W3CNote08May2000athttp://www.w3.org/TR/SOAP/.
QNames and Input Parameters

WhenanRPCprocessorreceivesaSOAPremoteprocedurecall,itmust:
ResolvetheQNameinthebodyinthemessagewiththenameofaprocedureinthe
localenvironment,and
Rendertheinputparametersinaformthatthetargetprocedurecanuse.
OntheIntegrationServer,theRPCprocessorperformsthisworkby:
MatchingtheQNametotheuniversalnameofaservice,and
EngagingthemessagecodertoconverttheXMLencodedinputparameterstoasetof
Javaobjectsthattheservicecanconsume.
Note: TheIntegrationServerexpectstheQNameintheincomingSOAPmessagetobe
normalizedaccordingtoUnicodeNormalizationFormC.Normalizationensuresthat
characters)arerepresentedinastandardway.IftheclienthasnotnormalizedtheQName,
theIntegrationServermightnotbeabletomatchitwithauniversalnameinitsregistry.
What Does a Results Message Look Like?

Resultsarealsocarriedinthebodyofthemessageandareformattedinastandardway.
The qualified name (QName)ofthefirstelementwithinthebodyofthemessageisthe
sameastheQNameofthefirstintheoriginalrequest,exceptthatthesuffix
Responseisappendedtoit.
The children of this elementcontaintheoutputvaluesfromtherequestedprocedure.
Thefollowingisanexampleofaresponsemessagethatcontainstwooutputparameters:
statusandbalance.
119
Basic structure of a SOAP RPC results message

.
.
.
The QName of the first

element has the
Response suffix...
<SOAP-ENV:Body>
<ser-root:journalEntryResponse
ser-root:journalEntryResponse xmlns:ser-root="http://www.expt.com/GL">
<status xsi:type="xsd:string">closed</status>
<balance xsi:type="xsd:int">0</balance>
</ser-root:journalEntryResponse>
</SOAP-ENV:Body>
...and its children

contain the output
parameters
.
.
.
Theresultsusethesamenamespaceastheoriginalrequest.Bydefault,thewebMethods
IntegrationServerusestheprefixserrootforthisnamespace.
FormoreinformationaboutthestructureofaSOAPRPCresponse,seetheSimpleObject
AccessProtocol(SOAP)1.1W3CNote08May2000athttp://www.w3.org/TR/SOAP/.
Behavior of the RPC Processor

WhentheRPCprocessorreceivesaSOAPmessage,thefollowingoccurs:
1
The processor searches for the target service.Theprocessorlocatestheservicewhose

universalname(explicitorimplicit)matchestheQNameofthefirstelementinthe
bodyofthemessage.
Forexample,iftheRPCprocessorreceivedthefollowingrequest,itwouldfetchthe
servicewhoseuniversalnamematchesthenamespacenamehttp://www/expt.com/GL/and
thelocalnamejournalEntry.
.
.
.
<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>
.
.
.
Iftheprocessorcannotlocatethetargetservice,itreturnsaSOAPfaultthatcontains
thefollowingerrormessage:
[ISS.0088.9122] Service namespaceName:localName does not exist
Formoreinformationaboutthiserror,seeAppendix A,SOAPFaultsReturnedby
theIntegrationServer.
120
If the processor finds the requested service, the message coder decodes the input parameters.
ThemessagecoderextractstheXMLencodedinputparametersfromthebodyofthe
messageandconvertsthemintoJavaobjects.Formoreinformationaboutthe
decodingprocess,seeDecodingtheInputParametersonpage 126.
The processor invokes the target serviceandpassesthedecodedparameterstotheservice

viathepipeline.
When the service ends, the message coder encodes the results.Themessagecoderconverts
theparametersnamedintheoutputsignaturetoasetofXMLencodedvalues.For
moreinformationaboutencoding,seeEncodingtheOutputParameterson
page 130.
The processor assembles the SOAP response messageandpassesitbacktothemessage

handler.
Building Target Services for the RPC Processor

AnyserviceontheIntegrationServercanfunctionasatargetserviceofaSOAPremote
procedurecall,providingitsatisfiesthefollowingcriteria:
TheservicesimplicitorexplicituniversalnamematchestheQNamethattheclient
willsubmitintheremoteprocedurecall.Forinformationaboutassigninguniversal
namestoservices,seeToassign,edit,orviewanexplicituniversalnameon
page 36.
Thenamesoftheparametersinthetargetservicesinputsignaturematchthenames
oftheparametersthattheclientwillpassintheremoteprocedurecall.(Keepinmind
thatthesenamesarecasesensitive.)
Theservicesoutputsignaturedefinesallofthevaluesthataretobereturnedtothe
client.
TheservicesACLspecifiesthegroupsofuserswhoareauthorizedtoexecuteit.
Toensurethatparametersareproperlyencoded,decoded,andvalidated,youshouldalso
ensurethat:
TheContent typepropertyforeachStringbasedparameterintheoutputsignature
specifiesthedatatypethatistobeassignedwhentheyareXMLencoded.(SeeThe
MessageCoderandtheRPCProcessoronpage 125forinformationabouthowthe
Content type propertyisusedtoencodeanddecodeparametervalues.)
TheservicesValidate inputand/orValidate outputpropertiesareenabledifyouwantthe
inputand/oroutputvaluestobevalidatedatruntime.
121
Error Handling
Ifatargetservicethrowsanexceptionwhileitisprocessing,themessagehandler
automaticallyreturnsaSOAPfaulttotheclient.Dependingonthetypeoferrorthat
occurs,theSOAPfaultmayincludeadetailelement,whichprovidesspecific
informationabouttheexception.ThiselementwillincludeastackTraceelementifthe
clientisamemberoftheDevelopersorAdministratorsusergroup.
<SOAP-ENV:Envelope
When the target
service throws an
exception, the
<SOAP-ENV:Body>
message handler
<SOAP-ENV:Fault>
returns a SOAP
<faultcode>
fault...
SOAP-ENV:Client
</faultcode>
<faultstring>
[ISS.0088.9134] Exception occurred while processing the body of message
</faultstring>
...containing the error
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>
IntegrationServer.
122
ExampleTarget Service for the RPC Processor

Thefollowingisanexampleofaverysimpletargetservicethatissuitableforcallingwith
SOAPRPC.ThisservicetakesthreeStringparameters(acct,amt,andloc)andreturnsone
Stringparameter(authCode).
Thisserviceislocatedinsample.soap:targetSvc_rpcProcSimple.YoucancallitviaSOAPRPCby
executingtheclientservice,sample.soap:buildRPC_SendHTTPSimple,fromDeveloper.When
youruntheclientserviceinDeveloper,itwillpromptyouforthefollowingvalues:
For this input parameter...
Enter...
acct
amt
Adecimalvalue,suchas150.75or15.00.(Omitcommasfrom
largevalues;otherwise,thevaluewillfailvalidation.)
loc
userName
AusernamethatbelongstotheDevelopersACL.
password
ThepasswordfortheusernamethatyouenteredinuserName.
A simple target service
Thisflowsimulatesaservicethatissuesanauthorizationcodebasedonthevalueinthe
inputparameteramt.BecauseaSOAPRPCtargetdoesnotrequireanyspeciallogic,the
servicedoesnotperformanyworkthatisSOAPspecific.Youcouldcallthisservicefrom
anytypeofclient.ItcontainsnothingthatrestrictsitsusetoSOAPremoteprocedurecalls.
ThecharacteristicsthataresignificantifthisserviceistobeusedasaSOAPRPCtargetare
itssignatureanditsuniversalname.
The Signature. Thesignatureforthisservicedefinesthreeinputvariables(acct,amt,and
loc)andoneoutputvariable(authCode).NotethattheValidate inputandValidate output
settingsareenabledinthisexampletoensurethattheinputandoutputvaluesare
validatedatruntime.
123
Signature for the sample target service
Thesignatureiscriticalbecauseitdetermineshowvariablesaredecodedandencoded
atruntime.Inthisexample,theinputvariablesaredeclaredasStrings,whichmeans
thatthemessagecoderwillrenderthemasStringsregardlessofthedatatypes
specifiedintheXML.
IfyouexaminethepropertiesfortheseparameterswiththeDeveloper,youwillsee
thattheContent typeandRequiredpropertiesarespecified.Thesewillbeusedto
validatethevaluesthattheclientprovides.
ThesignaturedeclaresoneoutputvariablecalledauthCode.Becausethisistheonly
variabledeclaredintheoutputsignature,itwillbetheonlyparameterreturnedtothe
client.
IfyouexaminethepropertiesforauthCode,youwillseethatitsContent type issetto
string {http://www.w3.org/2001/XMLSchema}.Thistellsthemessagecodertoset
thetypeattributetoxsd:stringwhenitencodesthisparameter.
The Universal name. Anexplicituniversalnamehasbeenspecifiedforthisserviceinthe
Universal namecategoryofthePropertiespanel.Theuniversalnamedeterminesthe
QNamethatcausesthisservicetoexecute.Inthisexample,theservicewillbe
triggeredwhenaclientsubmitsaSOAPremoteprocedurecallwhoseQNameis
composedofthenamespacenamehttp://www.expt.com/AUTHandthelocalname
getAuthCode.
124
Properties for the sample target service
Universal name is
specified on the
Properties panel
The Message Coder and the RPC Processor

Themessagecoderisthesubsystemthatdecodesandencodestheinputandoutput
parametersassociatedwithaSOAPremoteprocedurecall.ItsroleistoturnasetofXML
encodedvaluesintoapipelineoftheappropriatedatatypes(thedecodingprocess)and,
conversely,toturnobjectsinthepipelinetoasetofXMLencodedvalues(theencoding
process).
Note: Theencodinganddecodingprocessesaresometimesreferredtoasserializingand
deserializingormarshallingandunmarshalling.
Encoding/Decoding Rules
ToencodeanddecodetheparametersinaSOAPRPCmessage,themessagecoderfollows
theSOAP1.1encodingstyle,whichisspecifiedbythefollowingSOAPencodingStyle
attribute:
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
Thisattributespecifiesthesetofrulesthatgovernhowtheinputandoutputparameters
ofaSOAPRPCmessagearetoberepresentedinXML.Theserulesaredefinedinthe
SOAPEncodingsectionoftheSimpleObjectAccessProtocol(SOAP)1.1W3CNote08
May2000athttp://www.w3.org/TR/SOAP/.
125
Note: Currently,theIntegrationServersupportsonlytheSOAP1.1.encodingstyle.
However,theabilitytoaccommodatedifferentencodingstylesisdesignedintothe
product,soasadditionalstylesbecomeavailable,supportforthemcaneasilybeaddedto
theIntegrationServer.
Decoding the Input Parameters

ThedecodingprocessistheprocessofconvertingasetofXMLencodedvaluestoanIData
object(apipeline).
WhentheRPCprocessorreceivesavalidprocedurecall,itengagesthemessagecoder,
whichdecodestheinputparametersandproducesthepipelinethatispassedtothetarget
service.
Note: ThemessagecoderisalsoengagedbytheSOAPRPCclienttodecodetheoutput
parametersreturnedbyaSOAPremoteprocedurecall.Forinformationaboutthisuseof
themessagecoder,seeTheMessageCoderandtheRPCClientonpage 73.
Transforming Input Parameters into a Pipeline

Toproduceapipelineforthetargetservice,themessagecoderusestheinputparameters
fromthebodyofthemessageandtheinputsignaturefromthetargetservice.
126
Producing a pipeline from the input parameters in a remote procedure call
The message coder takes the

encodingStyle and the input
parameters from the SOAP RPC
message
and the input signature from the

target service
Message Coder
and produces a pipeline for the

target service
Duringthedecodingprocess,themessagecodermatchesthenamesoftheparameters
passedbytheclientwiththenamesoftheparametersdefinedintheinputsignature.It
usestheinputsignaturetodeterminehowtorendertheparametersinthepipeline.
If the input signature declares a parameter as a String,theparameterisrenderedasaJava
If the input signature declares a parameter as an Object,thevalueisrenderedaccordingto
thedatatypedeclaredintheXML.(ForalistofXMLdatatypesandtheJavaclassesto
whichtheyareconverted,seeAppendix B,Encoding/DecodingDataType
Mapping.)IfanXMLelementdoesnotdeclareitstype,theparameterisrenderedas
aString.
Thefollowingtableshowshowthemessagecoderwoulddecodeaninputparameter
namedamtgivenvariousdatatypedeclarationsandinputsignatures.Notethatwhenthe
inputsignaturedefinestheparameterasaString,themessagecoderalwaysproducesa
127
When XML data type is...
and Input
Signature is...
The Message Coder

produces...
of class java.math.BigDecimal
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

Themessagecoderdecodeseveryinputparameterthataclientsubmits,eventhosethat
donotappearintheinputsignature.Whenaclientsubmitsparametersthatarenot
declaredintheinputsignature,themessagecoderrendersthemasStrings.
Decoding Complex Structures and Arrays

Forcomplexdatatypes(XMLelementsthatcontainchildelements),themessagecoder
producesdocuments(IDataobjects)inthepipeline.
Themessagecodercreatesarraysofelements(thatis,StringLists,DocumentLists,Object
lists)forelementsthatareproperlyencodedasSOAParraysintheSOAPmessage.For
moreinformationabouthowthearraysareencodedinaSOAPmessage,seetheArrays
sectionintheSimpleObjectAccessProtocol(SOAP)1.1W3CNote08May2000at
Decoding Multi-Referenced Parameters

Themessagecodercanresolveparametersthatarereferencedthroughthehrefattributeas
longasthereferencedvalueappearswithinthebodyoftheSOAPmessage.Themessage
codercannotresolveexternalreferences(referencesthatpointtoresourcesoutsideofthe
message)orreferencesthatpointtoelementsoutsidetheBodyelement.
WithintheBodyelement,thehrefattributemayappearbeforeorafterthevaluethatit
references.Themessagecodercansuccessfullyresolveeithertype.
128
Example of a Backward Reference

In a backwards reference,
a referenced value
appears before the point
where it is referenced.
.
.
.
.
.
.
Example of a Forward Reference
In a forward reference, a
after the point where it is
referenced.
.
.
.
<amt id="id2">300</amt?
.
Forreferencedelements,themessagecoderputsasinglecopyofthevalueinthepipeline
andgeneratesreferencestoit.
Note: Ifthemessagecodercannotresolveareference,itgeneratesanullobjectforthat
parameter.Italsoreportstheproblemintheserverlogiftheserverisrunningatdebug
level5orhigher.
Decoding and Validation

Beawarethatthemessagecoderdoesnotvalidatetheinputparametersthatitdecodes.
Forexample,itdoesnotverifythatanelementoftype xsi:type=decimalactually
containsanumericvalue.Itsimplyrenderstheelementasa java.lang.Stringobjectora
java.math.BigDecimal object,dependingonthedatatypespecifiedinthesignatureofthe
targetservice.
Additionally,themessagecoderdoesnotverifythatthesetofparametersitreceivesfrom
theclientmatchestheparametersintheinputsignatureinnameornumber.Ifaclient
includesparametersthatarenotintheinputsignature,themessagecoderincludesthem
inthepipelineanyway(asStrings).Ifaparameterisdeclaredintheinputsignature,butis
notsuppliedbytheclient,thatparameterisomittedfromthepipeline.
Validating Input Parameters

IfyouwanttovalidatetheinputparametersthataclientsubmitsviaSOAPRPC,youuse
theserversnormalvalidationmechanismstoimposedatavalidationonthetargetservice.
129
Forexample,toensurethatclientsprovideanonnegativeintegerforaparameternamed
hours,youwould:
ConstrainthehoursparameterbysettingitsContent type propertyto:
nonNegativeInteger {http://www.w3.org/2001/XMLSchema}
EnabletheparametersRequiredproperty,and
Setthe Validate input optiononthetargetservices Input/Output tab.
Thesesettingswouldcausetheservertothrowanexceptioniftheclientomittedthehours
parameterorsubmittedavaluesuchas.5ortwentyratherthananonnegativeinteger.
Formoreinformationaboutvalidatingdataatruntime,seethewebMethodsDeveloper
UsersGuide.
Encoding the Output Parameters

TheencodingprocessistheprocessofconvertingaJavaobjecttoanXMLencodedvalue.
TheSOAPRPCprocessorengagesthemessagecodertoencodetheresultsofservicesthat
areinvokedviaaSOAPremoteprocedurecall.
Note: ThemessagecoderisalsoengagedbytheSOAPRPCclienttoencodetheinput
parametersforanoutboundremoteprocedurecall.Forinformationaboutthisuseofthe
messagecoder,seeTheMessageCoderandtheRPCClientonpage 73.
Transforming Output Parameters to XML

Whenthemessagecoderencodestheresultsofaremoteprocedurecall,itusesboththe
valuesinthepipelineandtheoutputsignatureofthetargetservice.
130
Encoding the output parameters from a remote procedure call
The message coder uses the

pipeline
and the output signature of the

target service
Message Coder
to produce the XML-encoded

results
Duringtheencodingprocess,themessagecoderconvertstheparametersdefinedinthe
outputsignaturetoXMLencodedvalues.
If the output signature declares a parameter as a String,thevalueoftheparameteris
encodedaccordingtoitsContent typeproperty.Forexample,ifContent typewere
nonNegativeInteger {http://www.w3.org/2001/XMLSchema},thevaluewouldbe
encodedasanxsi:type="xsd:nonNegativeInteger".IfContent typeisnotspecified,
themessagecoderencodesthevalueasastring(asiftheparameterwereContent type
string{http://www.w3.org/2001/XMLSchema}).
If the output signature declares a parameter as an Object,thevalueoftheparameteris
encodedaccordingtoitsunderlyingJavaclass.Forexample,iftheobjectwerea
java.lang.Boolean,themessagecoderwoulddeclareitas xsi:type="xsd:boolean"
intheresultingXML.ForalistofrecognizedJavaclassesandtheXMLSchemadata
typestowhichtheyareconverted,seeAppendix B,Encoding/DecodingDataType
Mapping.Ifthemessagecoderdoesnotrecognizetheunderlyingclass,itencodes
theparameterasastring(itusestheobjectstoString()methodtoproducethe
parametersvalue).
131
Important! Itisimportanttounderstandthatthemessagecoderencodesonlythose
parametersdefinedintheservicesoutputsignature.Itdoesnotencodetheentirepipeline.
Therefore,ifaservicehasnooutputsignature,novaluesarereturnedtotheclient.
Additionally,thismeansthatifanyoftheoriginalinputvaluesneedtobereturnedtothe
client,thosevaluesmustbeincludedintheoutputsignature.
Encoding Complex Structures and Arrays

Themessagecoderencodesdocuments(IDataobjects)ascomplexdatatypes.
ThemessagecoderencodesDocumentLists,StringLists,andObjectListsasSOAParrays.
FormoreinformationabouthowthearraysareencodedinSOAPmessages,seethe
ArrayssectionintheSimpleObjectAccessProtocol(SOAP)1.1W3CNote08May2000at
Encoding Multi-Referenced Elements

Bydefault,themessagecodergeneratesreferenceswhenencodingparametersthat
referencethesameunderlyingdatainthepipeline.However,thisbehaviorcanbe
modifiedwiththewatt.server.SOAP.useMultiReferenceparameter.
Whenwatt.server.SOAP.useMultiReferenceistrue,themessagecodergeneratesthe
appropriateidandhrefattributesforparametersthatreferencethesameunderlyingdata.
Forexample,iftheparameterscDateandoDaterefertothesameobject,themessagecoder
encodesthemlikethisifwatt.server.SOAP.useMultiReference=true(orisnotset,
whichistheserversinstalledbehavior):
.
.
.
.
.
.
The oDate parameter is

encoded as a reference
132
Andencodesthemlikethisifwatt.server.SOAP.useMultiReference=false:
.
.
.
<amt>300</amt>
<acct>cash</acct>
.
.
.
The oDate parameter is encoded

as an independent element
Formoreinformationaboutwatt.server.SOAP.useMultiReferenceandotherSOAP
relatedserverparameters,seeAppendix C,SOAPRelatedServerParameters.Formore
informationaboutsettingserverparameters,seethewebMethodsIntegrationServer
AdministratorsOnlineHelp.
133
134
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
135
E. Creating Custom SOAP Processors
What is a Custom SOAP Processor?

IfthedefaultprocessorprovidedbywebMethodsIntegrationServerdoesnotsuityour
needs,youcancreateyourowncustomizedSOAPprocessorandregisteritonthe
IntegrationServer.Forexample,youmightcreateacustomprocessorthatdelegates
messagesbasedonthevalueofaparticularheaderentry,oryoumightcreateacustomer
processorthatdropsmessagesintoqueuesbasedonthetypeofdocumentstheycarry.
ImplementingacustomSOAPprocessorontheIntegrationServerinvolvestwobasic
steps:
1
First, you must build a service that acts as a SOAP processor. Youcancodethisserviceto
operateonSOAPmessagesinwhatevermanneryoursolutionrequires.However,it
mustacceptasoapRequestDataobjectandasoapResponseDataobjectasinput,andmust
returnasoapResponseDataobjectasoutput.Forinformationaboutthisstep,see
BuildingaCustomSOAPProcessoronpage 137.
Second, you must register the service on the Integration Server as a SOAP processor. Youdo
thistoassociatetheservicewithaspecificprocessdirective(anamethatisunique
amongallSOAPprocessorsontheserver)andmakeitaccessibletotheSOAP
messagehandler.ForinformationaboutregisteringaserviceasaSOAPprocessor,see
RegisteringaSOAPProcessoronpage 145.
Important! ThecreationofcustomprocessorsisdeprecatedforIntegrationServer7.1.
Customprocessorscreatedinearlierreleasesarestillsupported.
Accessing a Custom SOAP Processor

Todirectamessagetoacustomprocessor,aclientspecifiestheprocessorsprocess
directiveintheURL.Theprocessdirectiveisthenameunderwhichthecustom
processorisregisteredwiththeSOAPmessagehandler.Forexample,thefollowingURL
wouldinvokethecustomprocessorregisteredasinbox.
http://rubicon:5555/soap/inbox
This URL directs the message to the SOAP

processor registered as inbox
ThefollowingURLwouldinvokethecustomprocessorregisteredassvcRq.
http://rubicon:5555/soap/svcRq
This URL directs the message to the SOAP

processor registered as svcRq
Important! Processdirectivesarecasesensitive.ThedirectivespecifiedintheURLmust
matchexactlytheprocessdirectiveasitisdefinedonthewebMethodsIntegrationServer.
136
IftheURLspecifiesaprocessdirectivethatisnotregisteredontheserver,theSOAP
messagehandlerreturnsaSOAPfaultcontainingthefollowingerrormessage:
[ISS.0088.9123] Requested SOAP processor directiveName is not
registered on this server.
ForinformationaboutSOAPfaults,seeAppendix A,SOAPFaultsReturnedbythe
IntegrationServer.
Building a Custom SOAP Processor

ASOAPprocessorisaservicethatoperatesonSOAPmessages.Itcanbeanytypeof
serviceandcancontainanykindoflogicthatyoursolutionrequires.
Inputs and Outputs

WhentheSOAPmessagehandlerinvokesacustomprocessor,itpassestwoinput
parameterstothatprocessor:
soapRequestData,anobjectcontainingtheentireSOAPmessage
soapResponseData,anobjectcontaininganemptySOAPmessage
Whenthecustomprocessorendsorexits,theSOAPmessagehandlerreturnsthecontents
ofsoapResponseDatatotheclient(unlesstheprocessorthrowsanexception,inwhichcase
theSOAPmessagehandlergeneratesaSOAPfaultandreturnsittotheclient).
How to Create a Custom SOAP Processor

Thefollowingdescribesthegeneralstepsyoutaketocreateacustomprocessor.
1
Create a new service that has the following signature:

Inputs:
soapRequestData(oftypeObject)
Outputs:
Youcanusepub.soap.utils:requestResponseSpectospecifytheinputsandoutputsforthe
service.
2
Code the service to process SOAP messages in the way you need. Thefollowingdescribes
severaltasksthatacustomprocessortypicallyexecutes.However,thebehaviorof
yourprocessorwilldependentirelyontheneedsofyoursolution.Itmightincludeall,
some,ornoneofthefollowing:
Extracting data from the SOAP request message.ToextractinformationfromaSOAP
message,youusethedataretrievalutilitiessuchasgetBodyandgetHeader.(Fora
completelistofthedataretrievalservices,seepage 60.)Theseservicesretrievea
137
specifiedelementfromthesoapRequestDataandreturntherequestedelementas
anXMLnode(oranarrayofXMLnodes).Toextractdatafromthereturnednode,
youqueryitwiththepub.xml:queryXMLNodeservice.
Important! BeawarethatyoucannotquerythesoapRequestDataobjectdirectly.To
extractinformationfromsoapRequestData(orsimilarSOAPobjects,suchas
soapDataandsoapResponseData),youmustuseoneofthedataretrievalservicesto
extractanelementofthemessage(forexample,theheader,thebody,ortheentire
envelope)andquerytheresultingXMLnode.
Invoking services to process the data extracted from the message.Afterextractingthe
datawithwhichyouwanttowork,youcanmapittotheappropriatevariables(if
necessary)andpassittoservicesthatprocessitinsomeway.(Toensurethatthe
datayouhaveextractedisinthecorrectformat,youmightwanttovalidateit
againstaschemausingpub.schema:validateormakesurethattheservicetowhich
youpassthedataperformsdatavalidationonitsinputparameters.)
Invoking services based on a particular QName in the SOAP request message.Ifyour
SOAPmessagesuseaqualifiedname(QName)tospecifyatargetserviceonthe
webMethodsIntegrationServer,youcanusepub.soap.utils:getQName(whichresides
intheWmPublicpackage)toextracttheelementsQNamefromthemessageand
thenusepub.universalName:find(whichresidesintheWmPublicpackage)tolocate
theserviceassociatedwiththatname.
Note: ToinvoketheserviceassociatedwithaQName,youwillneedtocreatea
JavaservicethatperformsadoInvokeoftheservicereturnedby
pub.universalName:find.Seethecom.wm.app.b2b.server packageinthewebMethods
IntegrationServerJavaAPIReferenceforinformationaboutthedoInvokemethod.
ThismethodisamemberoftheServiceclass.
3
Use the SOAP message-composition services to populate soapResponseData. Themessage

compositionservicesareservices(suchasaddHeaderEntryandaddBodyEntry)thatyouuse
toaddcontenttotheemptymessageinsoapResponseData.(Foracompletelistof
messagecompositionservices,seepage 53.)
ThemessagecompositionservicesrequireanXMLnoderepresentationoftheheader
entryorbodyentrythatyouwanttoaddtothemessage.YoucangenerateanXML
nodeusingservicessuchaspub.xml:documentToXMLStringandpub.xml:xmlStringToXMLNode.
Foranexampleofhowtodothis,seeStep 3inthesamplecodeshownonpage 141.
When you finish coding the service, register it as a SOAP processor. Thisstepassociatesthe
servicewithaspecificprocessdirectiveandmakesitaccessibletotheSOAPmessage
handler.ForinformationaboutregisteringaserviceasaSOAPprocessor,see
RegisteringaSOAPProcessoronpage 145.
138
Error Handling
IfyourSOAPprocessor(oranyservicethatitcalls)throwsanexception,theSOAP
messagehandlerautomaticallyreturnsthefollowingSOAPfaulttotheclient.Thefault
includesadetailelementthatprovidesspecificinformationabouttheexception.This
elementwillincludeastackTraceelementiftheclientisamemberoftheDevelopersor
Administratorsusergroup.
When a custom
processor throws an
exception, the
message handler
returns a SOAP fault...
...containing an error
message...
...and details
about the error.
<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>
SOAP-ENV:Client
</faultcode>
<faultstring>
[ISS.0088.9134] Exception occurred while processing the body of the message
</faultstring>
<faultactor>
</faultactor>
<exception>
<message xml:lang="en-US">detailedMessageIssuedbyException</message>
<stackTrace>textFromStackTrace</stackTrace>
</exception>
</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Note: TheSOAPmessagereturnedtotheclientwhenanexceptionoccurscontainsonlythe
SOAPfault.Itdoesnotincludeanymessagecontent(forexample,headerentries,body
entries)thatthetargetservicemayhaveinsertedintosoapResponseDatabeforethe
exceptionoccurred.
Returning Your Own SOAP Faults

AlthoughtheSOAPmessagehandlerautomaticallyreturnsaSOAPfaultwhenacustom
processorthrowsanexception,theremaybetimeswhenyouwantyourcustomprocessor
toreturnaSOAPfault.Forexample,youmightwanttoreturnafaultiftheclientomitsa
requiredpieceofdataorifarequestedresourceisnotavailable.Inthesesituations,you
canchoosetodoeitherofthefollowing:
Codeyourprocessortodetecttheerrorconditionandthrowanexception.Thiswill
causethemessagehandlertoreturnthestandardSOAPfaultcodeshownabove.If
youincludeadetailederrormessagewhenyouthrowtheexception,thatmessage
willbeincludedinthedetailelementwithintheSOAPfault.
139
OR
Codetheprocessortodetecttheerror,butinsteadofthrowinganexception,compose
yourownSOAPfaultinsoapResponseDataandthenexitnormally.Thiswillcausethe
messagehandlertosimplyreturnthecontentsofsoapResponseData(whichcontains
theSOAPfaultthatyourprocessorgenerated)totheclient.Ifyouchoosethis
approach,youmustbethoroughlyfamiliarwiththeSOAPspecificationregarding
faultcodes.
Important! TheSOAPspecificationstatesexplicitlythattherecipientofaSOAPmessage
mustreturnaSOAPfaultanytimeitfailstoprocessthesubmittedmessagesuccessfully.
IntegrationServerofthisdocumentandtheSimpleObjectAccessProtocol(SOAP)1.1
W3CNote08May2000athttp://www.w3.org/TR/SOAP/#_Toc478383507forSOAP1.1and
theSOAP1.2W3CRecommendation27April2007athttp://www.w3c.org/TR/soap12part1/
forSOAP1.2.
ExampleCustom Processor
ThefollowingisanexampleofaSOAPprocessorthatdropsthebodyofthemessage
(alongwithseveralotherpiecesofcontrolinformationthatitextractsfromtheheader)
intoaqueuebasedonthevalueofacertainheaderentry.Ifthedocumentissuccessfully
loggedintothequeue,theprocessorreturnsanacknowledgment.Otherwise,itgenerates
anerrormessageandthrowsanexceptionsothattheclientreceivesaSOAPfault.
Thisexampleislocatedinsample.soap:customProc_msgQueueintheWmSamplespackage.
YoucanfindtheWmSamplespackageinthecertifiedsamplesareaoftheKnowledgeBase
ontheAdvantageWebSite.YoumightwanttoopenthisexamplewithDevelopertosee
howthepipelineismappedbetweensteps.
Note: IfyouwanttoexecutethisservicefromDeveloper,enabletheacquireSOAPMessage
stepatthetopoftheflow.ThisstepgeneratessoapRequestDataandsoapResponseData
objects,whichsimulatethepipelinethatthisservicewouldreceivefromtheSOAP
messagehandler.IfyouwanttoexecutethisserviceviatheSOAPmessagehandler(that
is,fromaclient),disableacquireSOAPMessage.
140
Custom processor that drops messages into queues
Description
Step 1
Extract data from SOAP request message.Thissequenceretrievesrequiredpieces

ofinformationfromthemessagebyextractingtheheaderandbodyelements
fromsoapRequestDataandqueryingtheresults.Thisexampleexpectsa
SOAPmessagethatisstructuredasfollows:
141
Description
<SOAP-ENV:Envelope
This service
pulls certain
control
information
from the
header...
<SOAP-ENV:Header>
<EXP:postmark xmlns:EXP="http://www.exprint.com/inbox">
<docType>RFQ</docType>
<priority>05</priority>
<sender>http://www.polymfg.com/PURCH/A30155G</sender>
<tStamp>20011129.161434206</tStamp>
</EXP:postmark>
</SOAP-ENV:Header>
...and extracts
the document
carried in the
body of the
message and
drops it in a
queue
<SOAP-ENV:Body>
<RFQ:quoteReq xmlns:RFQ="http://www.exprint.com/orderSys">
<acct>1417-A199-0404-5POLY</acct>
<jobSpecs>
<ink>P440</ink>
</jobSpecs>
</RFQ:quoteReq>
</SOAP-ENV:Body>
Toextractinformationfromthemessage,thisserviceexecutesthefollowing
steps:
Step
Description
1.1
getHeaderThisstepretrievestheheaderfromsoapRequestData.It
returnsanXMLnodethatrepresentstheentireheaderelement(thatis,
from<Header>to</Header>).
1.2
queryXMLNodeThisstepextractsspecificpiecesofcontrol
informationfromtheheaderbyexecutingthefollowingXQLqueries
againsttheXMLnodereturnedbyStep 1.1.
Var Name
XQL Query
QU_docType
/PMK:postmark/docType/text()
QU_priority
/PMK:postmark/priority/text()
QU_sender
/PMK:postmark/sender/text()
142
Description
QU_timeSen
t
/PMK:postmark/tStamp/text()
IfyouexaminethequeryXMLNodestepwithDeveloper,youwillseethat
italsoexecutesthefollowingquery,whichextractstheentireHeader
nodeasaString:
Var Name
XQL Query
wholeNode
/source()
Thisqueryisincludedfordebuggingpurposes.Itallowsyouto
examinetherawXMLassociatedwiththeHeadernode.Ifyouwereto
putthisserviceintoproduction,youwouldomitthisquery.
Step 2
1.3
getBodyThisstepretrievesthebodyfromsoapRequestData.Itreturns
anXMLnodethatrepresentstheentirebodyelement(thatis,from
<Body>to</Body>).
1.4
queryXMLNodeThisstepextractsthecontentsofthebodyelementby
executingthefollowingXQLqueryagainsttheXMLnodereturnedin
Step 1.3.
Var Name
XQL Query
QU_doc
//source()
Log extracted data in a queue. Thissequencegeneratesatimestampanddrops

theinformationextractedbyStep 1intoaqueue(inthisexample,thisactionis
simulatedbyaMAPstep).Itproducesareceiptthatreportsthenameof
thequeueintowhichthemessagewasdropped.Ifthemessageisrejectedby
thequeue,thereceiptwillcontainanerrormessage.
143
Description
Step 3
Compose SOAP Response Message.Thissequencecheckstheresultgenerated

byStep 2.IfStep 2returnsanerror,thisstepgeneratesanerrormessageand
throwsanexception(whichcausesaSOAPfaulttobereturnedtotheclient).
Otherwise,itgeneratesaresponsemessagethatisstructuredasfollows:
The receipt
from the
queue is
returned in
the body of
the SOAP
response
message

<SOAP-ENV:Envelope
<SOAP-ENV:Body>
<EXP:QU_receipt xmlns:EXP="http://www.exprint.com/orderSys">
<msg>Document RFQ.20030217.160828.837.A8F7 successfully placed in
queue RFQ</msg>
<entryTime>20030217.160828.837</entryTime>
<qID>RFQ.20030217.160828.837.A8F7</qID>
</EXP:QU_receipt>
</SOAP-ENV:Body>
Toproducetheresponsemessage,thisserviceexecutesthefollowingsteps:
Step 4
Step
Description
3.1.1
documentToXMLStringThisserviceconvertsthereceiptdocumentto
anXMLString.
3.1.2
xmlStringToXMLNodeThisstepconvertstheXMLStringtoanXML
node.(RecallthattoaddabodyentrytosoapResponseData,youmust
placetheentryinthepipelineasanXMLnode.)
3.1.3
addBodyEntryThisstepaddsthebodyentrytosoapResponseData.
FOR DEBUG ONLY. ThisstepconvertsthecontentsofsoapResponseDatatoa

StringusingthesoapDataToStringservice.Thisallowsyoutoexaminethe
finishedmessagewithDeveloper,whichisusefulduringtestingand
debugging.Youwouldnotincludethisstepinaproductionservice.
144
Description
IfyouexecutethisserviceandexaminethecontentsoffinishedMessageonthe
Resultspanel,youwillseeaSOAPmessagesimilartothefollowing:
Registering a SOAP Processor

TomakeacustomSOAPprocessoravailableforuse,youmustregisteritonthe
IntegrationServer.Thisactionassociatesyourprocessorwithaparticulardirectiveand
makesitknowntotheSOAPmessagehandler.(Ifyourserverrunsinacluster,besureto
registeritoneveryserverinthecluster.)
ToregisteraSOAPprocessor,youexecutetheservice,pub.soap.processor:registerProcessor.To
ensurethatyourSOAPprocessorisregisteredwhenevertheserverisrestarted,we
recommendthatyouincludepub.soap.processor:registerProcessorinastartupservice.
Note: IfyouregisteryourSOAPprocessorusingastartupservice,makesurethatthe
packageinwhichthestartupserviceresidesdesignatestheWmPublicpackageasa
dependency.ThiswillinstructtheservertoloadWmPublicbeforeitloadsyourpackage
andensurethatpub.soap.processor:registerProcessorisavailablewhenyourstartupservice
executes.
145
How to Register a SOAP Processor

ThefollowingdescribesthegeneralstepsyoutaketoregisteraSOAPprocessor.
1
Create a flow service that invokes pub.soap.processor:registerProcessor.Setthefollowing

inputvariablesforthisservice:
Set...
To...
directive
AStringspecifyingtheprocessdirectivethatyouwantto
assigntotheprocessor.
Note: Useonlyletters,digits,orthecharacters-_.!~*'( ) in
thenameyouspecifyindirective.
svcName
AStringspecifyingthefullyqualifiednameoftheservice
thatyouareregisteringasaSOAPprocessor.
descriptiveName
Optional.AStringthatcontainsadescriptivecommentfor
thisSOAPprocessor.Thiscommentisshownwhenyourun
theutilityservicepub.soap.processor:listtogetalistofthe
registeredSOAPprocessors.
validateSoapMessage
Optional.AStringindicatingwhethertheSOAPmessage
handleristovalidatetheSOAPmessagesthatthisprocessor
sendsandreceives.Thissettingoverridestheserversglobal
watt.server.SOAP.validateSOAPMessage setting.
Run the flow service that you just created and verify that it executed successfully.Ifaprocessor
isalreadyregisteredunderthenameyouspecifiedindirective,theservicewillthrow
anexception.Inthiscase,youmusteitherregisterthenewprocessorunderadifferent
name,or,ifyouwantthenewprocessortoreplacethecurrentone,youmust
unregisterthecurrentprocessor(withpub.soap.processor:unregisterProcessor)andthen
registerthenewone.
Add the flow service to the startup list. Toensurethatyourprocessorisautomatically

registeredwiththeSOAPmessagehandlerwhenevertheserverisstarted,wesuggest
thatyoumakeitastartupservice.
Viewing the List of Registered SOAP Processors

IfyouwanttoviewthelistofcurrentlyregisteredSOAPprocessors,execute
pub.soap.processor:listfromDeveloper.Thisservicereturnsadocumentlistcalledlistthat
containsadocument(anIDataobject)foreachSOAPprocessorregisteredontheserver.
146
List of registered SOAP processors
Eachdocumentinlistwillcontainthefollowingkeys:
Key
Value
directive
AStringcontainingtheprocessdirectivethatisassignedtothe
SOAPprocessor.
svcName
AStringcontainingthefullyqualifiednameoftheservicethat
functionsastheSOAPprocessor.
descriptiveName
AStringcontainingthedescriptivecommentthatwasgiventothe
SOAPprocessorwhenitwasregistered.Thiselementwillbeempty
iftheprocessorwasnotregisteredwithadescriptivecomment.
validateSoapData
AStringindicatingwhethertheSOAPmessagehandlervalidates
theSOAPmessagesthatthisprocessorsendsandreceives.
Deactivating a Registered SOAP Processor

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

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

decoding String parameters, RPC processor 127
decoding structures and arrays 77, 128
decoding undeclared parameters, RPC processor 128
encoding Object parameters, RPC client 75
encoding Object parameters, RPC processor 131
encoding RPC parameters, RPC client 74
encoding RPC parameters, RPC processor 130
encoding String parameters, RPC client 74
encoding String parameters, RPC processor 131
encoding structures and arrays 75, 132
multi-referenced parameters 75, 77, 128, 132
usage by RPC client 73
usage by RPC processor 125
validating parameters, RPC client 74
validating parameters, RPC processor 129
message element 81
message handler
relationship to SOAP processors 24
response generated by 25
role in overall architecture 23, 24
validation performed by 24
message-composition services
using in a custom processor 138, 144
using in target service 43, 48
using to compose a new message 53
messages
Body element 15
building solutions that receive messages 32
building solutions that send messages 37
composing 52
Envelope element 11
extracting data from 42, 46, 63, 73, 137, 141
Header element 12
payload 15
posting to the webMethods Integration Server 23
receiving 22
sending 25, 57
sending RPC 27, 66
testing for Faults 63, 73
validation of 24
multi-referenced parameters
configuring encoding behavior 115

decoding 77, 128
encoding 75, 132
mustUnderstand attribute 14
causing addHeaderEntry utility to fail 89
N
namespace names 33
namespaces
enforcing in header and body entries 53, 115
for SOAP elements 11
usage in Envelope 11
usage in the Header 12
usage in universal names 33
nodes
adding to SOAP messages 43, 49, 53, 55, 138, 144
extracting data by querying 42, 46, 60, 137, 142, 143
generating 43, 49, 53, 55, 138, 144
returned by data-retrieval services 42, 46, 60, 137, 142, 143
validating contents of 43, 138
normalization
expected of QNames 41, 119
universal names 34
O
overview of SOAP 10
P
parameters, watt.server.SOAP 114
payload 15
posting SOAP messages to the webMethods Integration Server
23
process directive
assigning to custom processor 145
deactivating 147
description of 32
for custom processor 136
for default processor 40
for RPC processor 118
modifying 147
position in URL 23
processor:list service 146
processor:registerProcessor service 145
151
Index
decoding parameters. See message coder

encoding parameters. See message coder
receiving a SOAP message 120
target service criteria 121
processor:unregisterProcessor service 147

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

soapRequestData
creation by message handler 24
passed from default processor 41
passed to custom processors 136, 137
soapResponseData
composing 43, 48, 138, 144
creation by message handler 24
passed from default processor 41
passed to cusom processors 136, 137
soapRPC client
composing the remote procedure call 72
invoking 66
processing output values 69
stackTrace element 81, 122
submitting a remote procedure call 70
local portion of name 34

namespace portion of name 33
overview of 33
removing from a service 36
Universal Name Registry 37
usage by default processor 40
viewing name assigned to service 36
universalName:find service 37, 138
universalName:list service 37
unregistering a SOAP processor 147
unregisterProcessor service 146, 147
URLs
for custom SOAP processors 136
for the default SOAP processor 40
for the RPC SOAP processor 118
format of 23
used to address SOAP processors 23
useMultiReference parameter 75, 115, 132
target services
assigning universal names to 43
example of 44, 123
how to build 42
returning errors from 43, 122
selection process 40
signature requirements 42
using with RPC processor 121
trailers
example of 18
usage 18
troubleshooting information 7
typographical conventions in this document 7
watt.server.SOAP.directive 114
watt.server.SOAP.enforceMsgPartNS 115
watt.server.SOAP.useMultiReference 75, 115, 132
watt.server.SOAP.validateSOAPMessage 114
Universal Name Registry

finding services in 37
overview of 37
services that operate on 37
viewing contents of 37
universal names
assigning to a service 36
assigning, editing, and viewing 36
finding service name for 37, 138
implicit vs explicit 34
validate service 43, 138

validateSOAPMessage parameter 114
validating
application data 43, 138
SOAP Envelope 24
SOAP RPC parameters 129
VersionMismatch fault code 24
viewing
list of registered processors 145, 146
list of universal names 37
X
XML data types 103
XML nodes. See nodes
XML, encoding and decoding. See message coder
xmlStringToXMLNode service 43, 49, 53, 138, 144
XML-to-Java data type mapping 104
153
Index
154

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

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

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

Загружено:

Авторское право:

Доступные форматы

TitlePage

SOAP Developers Guide

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

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

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

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

SOAP Developers Guide Version 7.1

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

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

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

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

SOAP Developers Guide Version 7.1

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

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

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

SOAP Developers Guide Version 7.1

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

SOAP Developers Guide Version 7.1

About This Guide

About This Guide

SOAP Developers Guide Version 7.1

About This Guide

SOAP Developers Guide Version 7.1

Chapter 1. Overview of SOAP

SOAP Developers Guide Version 7.1

What Does a SOAP Message Look Like?

SOAP Developers Guide Version 7.1

The SOAP Namespace Declaration

SOAP Developers Guide Version 7.1

The SOAP namespace

...and is used to qualify

SOAP Developers Guide Version 7.1

This message has a

Soap 1.2 message with single header entry

SOAP Developers Guide Version 7.1

SOAP 1.1 Header Attributes

SOAP 1.2 Header Attributes

SOAP Developers Guide Version 7.1

This header entry...

...uses both the role

SOAP Developers Guide Version 7.1

A body containing one entry

A body containing two body entries

SOAP Developers Guide Version 7.1

SOAP Fault Elements

SOAP Developers Guide Version 7.1

A fault is returned in the

SOAP Developers Guide Version 7.1

A SOAP 1.1 message containing two trailers

SOAP Developers Guide Version 7.1

SOAP Developers Guide Version 7.1

Chapter 2. SOAP Support on the webMethods Integration

SOAP Developers Guide Version 7.1

2. SOAP Support on the webMethods Integration Server

SOAP Versions Supported by webMethods Integration Server

Receiving SOAP Messages with the Integration Server

SOAP Developers Guide Version 7.1

2. SOAP Support on the webMethods Integration Server

Processing and receiving a SOAP request

webMethods Integration Server

The HTTP Client Posts a SOAP Document to the Integration Server

SOAP Developers Guide Version 7.1

2. SOAP Support on the webMethods Integration Server

The SOAP Message Handler Invokes the Appropriate SOAP Processor

WebMethods SOAP Developer's Guide - Software AG Documentation

WebMethods SOAP Developer's Guide - Software AG Documentation