7 1-1 soap-developers_guide
Upcoming SlideShare
Loading in...5
×

Like this? Share it with your network

Share

7 1-1 soap-developers_guide

  • 1,642 views
Uploaded on

simple object access protocol.. what, how to use it

simple object access protocol.. what, how to use it

More in: Education
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
1,642
On Slideshare
1,642
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
44
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. SOAP Developer’s Guide Version 7.1.1 January 2008 webMethods Title Page
  • 2. This document applies to webMethods Developer Version 7.1.1  and to all subsequent releases.  Specifications contained herein are subject to change and these changes will be reported in subsequent release notes or new editions. © Copyright Software AG 2007. All rights reserved. The name Software AG and/or all Software AG product names are either trademarks or registered trademarks of Software AG. Other  company and product names mentioned herein may be trademarks of their respective owners. Document ID: DEV-SOAP-DG-711-20080128 Copyright &  Docu‐ ment ID
  • 3. SOAP Developer’s Guide Version 7.1.1 3 Table of Contents About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 1. Overview of SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 What is SOAP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 What Does a SOAP Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 The Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 The SOAP Namespace Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 The Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 SOAP 1.1 Header Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 SOAP 1.2 Header Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 The Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 SOAP Fault Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Trailers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2. SOAP Support on the webMethods Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . 19 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 SOAP Versions Supported by webMethods Integration Server . . . . . . . . . . . . . . . . . . 20 Receiving SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Sending SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Sending SOAP RPC Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . 24 3. Building Solutions with SOAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Building Solutions that Receive SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 What is a SOAP Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 SOAP Processors Provided by the Integration Server . . . . . . . . . . . . . . . . . . . . . 31 Universal Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Implicit and Explicit Universal Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 The Universal Name Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Services You Use to Interact with the Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Building Solutions that Send SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 4. Using the Default SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Accessing the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Behavior of the Default SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 How the Processor Selects the Target Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 What if the Requested Service Does Not Exist? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Processor Inputs and Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
  • 4. Table of Contents 4 SOAP Developer’s Guide Version 7.1.1 Building Target Services for the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 How to Create a Target Service for the Default Processor . . . . . . . . . . . . . . . . . . . . . . 40 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Example—Target Service for Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 5. Composing and Sending SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Composing a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 How to Compose a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Example—Composing a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Sending a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 How to Send a SOAP Message via HTTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Example—Sending a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 6. Using the SOAP RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Using pub.client:soapRPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Example—Submitting a Remote Procedure Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 The Message Coder and the RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Encoding the Input Parameters for the Remote Procedure Call . . . . . . . . . . . . . . . . . . 71 Encoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Encoding Multi-Referenced Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Decoding the Output Parameters from a Remote Procedure Call . . . . . . . . . . . . . . . . 73 Decoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Decoding Multi-Referenced Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 A. SOAP Faults Returned by the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Basic Structure of a SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Elements of a SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Example—Unknown SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Example—Exception While Processing Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 webMethods SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 B. Encoding/Decoding Data-Type Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 XML-to-Java Mappings (Decoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Data types from http://schemas.xmlsoap.org/soap/encoding/ . . . . . . . . . . . . . . . . . . . 102 Data types from http://www.w3.org/1999/XMLSchema . . . . . . . . . . . . . . . . . . . . . . . . 104 Data types from http://www.w3.org/2000/10/XMLSchema . . . . . . . . . . . . . . . . . . . . . . 105 Data types from http://www.w3.org/2001/XMLSchema . . . . . . . . . . . . . . . . . . . . . . . . 107 Java-to-XML Mappings (Encoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 webMethods to XML Mappings (Encoding & Decoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Data types from http://www.webmethods.com/2001/10/soap/encoding . . . . . . . . . . . . 110
  • 5. SOAP Developer’s Guide Version 7.1.1 5 Table of Contents C. SOAP-Related Server Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 SOAP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 D. Using the SOAP RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 What is the RPC Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 What Does a SOAP RPC Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 QNames and Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 What Does a Results Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Behavior of the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Building Target Services for the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Example—Target Service for the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 The Message Coder and the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Encoding/Decoding Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Decoding the Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Transforming Input Parameters into a Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Parameters that are Not in the Input Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Decoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Decoding Multi-Referenced Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Decoding and Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Validating Input Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Encoding the Output Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Transforming Output Parameters to XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Encoding Complex Structures and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Encoding Multi-Referenced Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 E. Creating Custom SOAP Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 What is a Custom SOAP Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Accessing a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Building a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Inputs and Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 How to Create a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Returning Your Own SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Example—Custom Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 Registering a SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 How to Register a SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Viewing the List of Registered SOAP Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Deactivating a Registered SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
  • 6. Table of Contents 6 SOAP Developer’s Guide Version 7.1.1
  • 7. SOAP Developer’s Guide Version 7.1.1 7 About This Guide Welcome to the SOAP Developer’s Guide. This guide describes how to use the webMethods  Integration Server to exchange SOAP messages over the Internet.  It is for solution developers who need to understand: How to receive and process SOAP messages and SOAP remote procedure calls with  the webMethods Integration Server. How to submit SOAP messages and SOAP remote procedure calls to other servers. Document Conventions Convention Description Bold Identifies elements on a screen. Italic Identifies variable information that you must supply or change based  on your specific situation or environment. Identifies terms the first  time they are defined in text. Also identifies service input and output  variables. Narrow font Identifies storage locations for services on the webMethods  Integration Server using the convention folder.subfolder:service. Typewriter font Identifies characters and values that you must type exactly or  messages that the system displays on the console. UPPERCASE Identifies keyboard keys. Keys that you must press simultaneously  are joined with the “+” symbol. Directory paths use the “” directory delimiter unless the subject is  UNIX‐specific. [ ] Optional keywords or values are enclosed in [ ]. Do not type the [ ]  symbols in your own code.
  • 8. About This Guide 8 SOAP Developer’s Guide Version 7.1.1 Additional Information The webMethods Advantage Web site at http://advantage.webmethods.com provides  you with important sources of information about webMethods products: Troubleshooting Information. The webMethods Knowledge Base provides  troubleshooting information for many webMethods products. Documentation Feedback. To provide feedback on webMethods documentation, go to  the Documentation Feedback Form on the webMethods Bookshelf. Additional Documentation. Starting with 7.0, you have the option of downloading the  documentation during product installation to a single directory called  “_documentation,” located by default under the webMethods installation directory.  In addition, you can find documentation for all webMethods products on the  webMethods Bookshelf.
  • 9. SOAP Developer’s Guide Version 7.1.1 9 1 Overview of SOAP What is SOAP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 What Does a SOAP Message Look Like? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
  • 10. 1 Overview of SOAP 10 SOAP Developer’s Guide Version 7.1.1 What is SOAP? The Simple Object Access Protocol (SOAP) is a standard, lightweight protocol for  exchanging messages across the Internet. It uses XML to define a basic message packet  that can be used to convey an arbitrary XML document or a remote procedure call (RPC). What Does a SOAP Message Look Like? A SOAP message uses XML to form a simple message packet. The packet consists of an  envelope that encloses two elements: an optional header and a mandatory body. A simple SOAP message packet The Envelope The envelope is the top‐level element in a SOAP message. It is the “container” that holds  the entire message. The envelope must be the first (that is, the outermost) element in a  SOAP message. It has the name Envelope. The envelope may contain a header element. When a SOAP message contains a  header, the header element must be the first child within the envelope. For additional  information about the header element, see “The Header” on page 12. Note: Although not shown in the example above, SOAP 1.1 also allows additional,  implementation‐specific elements to follow the body of a SOAP message. In this  book, such elements are referred to as trailers. For more information about trailers, see  “Trailers” on page 17. Trailers are not supported with SOAP 1.2. SOAP Header (optional) SOAP Envelope 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: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:Header> <MSG:priority xmlns:MSG="http://www.gsx.com/gl/">9</MSG:priority> </SOAP-ENV:Header> </SOAP-ENV:Envelope>
  • 11. SOAP Developer’s Guide Version 7.1.1 11 1 Overview of SOAP The envelope must contain a body element. The body carries the content of the  message. For more information about the body element see “The Body” on page 14. The envelope must be associated with a SOAP namespace. The SOAP namespace  serves as the qualifier for the message’s SOAP‐related elements and attributes. It also  specifies the XML schema to which the message conforms. For additional information  about the SOAP namespace, see “The SOAP Namespace Declaration” below. The envelope may include other implementation‐specific namespace declarations. The envelope may contain the encodingStyle attribute, which specifies the way in which  the elements within the envelope are serialized and deserialized. The envelope may contain additional implementation‐specific attributes, but if it  does, these attributes must be namespace qualified. The envelope may contain additional implementation‐specific children besides the  header and body elements; however, if it does, the additional elements must be  namespace qualified and must follow the body element. The SOAP Namespace Declaration The primary purpose of the SOAP namespace is to distinguish SOAP‐related elements  and attributes from the application‐specific elements and attributes conveyed in the  message. The SOAP namespace also serves another purpose; it specifies the schema to  which the SOAP message conforms.  A SOAP 1.1 message uses the namespace http://schemas.xmlsoap.org/soap/envelope/ to qualify  the elements and attributes that make up the SOAP message packet. A SOAP 1.2 message  uses the namespace http://www.w3.org/2003/05/soap-envelope/. A SOAP message must declare  this namespace in the SOAP envelope. By convention, the prefix SOAP-ENV (for SOAP 1.1) and env (for SOAP 1.2) is given to the SOAP namespace; however, a message may use any  prefix to represent the SOAP namespace. Messages that conform to the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May  2000 use the namespace http://schemas.xmlsoap.org/soap/envelope/ and those that conform to  ...and is used to qualify the elements and attributes that make up the SOAP packet. The SOAP namespace is declared in the envelope element... <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> . . . </SOAP-ENV:Header> <SOAP-ENV:Body> . . . </SOAP-ENV:Body>
  • 12. 1 Overview of SOAP 12 SOAP Developer’s Guide Version 7.1.1 the SOAP 1.2 W3C Recommendation 27 April 2007 specification use the namespace  http://www.w3.org/2003/05/soap-envelope/. Messages whose envelopes declare a different namespace, or no namespace, are  considered invalid and are rejected by Integration Server. The Header A SOAP message can include an optional header component to store additional  information. The header element provides a place where a sender can pass auxiliary,  implementation‐specific information such as authorization codes, routing information,  version numbers, or message IDs. For example, if your solution routes invoices through  one or more approval steps before passing it to an accounts‐payable processor, the header  could hold the document’s routing information. When a header is included in a SOAP message, it must appear as the first child element  within the envelope and must have the name Header. A header may contain one or more  child elements. Each child is referred to as a header entry. All header entries must be  namespace qualified. The following example shows a SOAP envelope containing a single header entry called  <MSG:priority>. Note that the entry is namespace qualified, which is a requirement of all  header entries in a SOAP message. Soap 1.1 message with single header entry  Note: Unless otherwise noted, when the namespace prefix SOAP-ENV appears in this  book, it represents the namespace http://schemas.xmlsoap.org/soap/envelope/. Important! The inclusion of a header component and the information it stores are  implementation‐specific. The SOAP specification does not define any standard  header entries. It simply provides the header as a container that implementers can  use as needed. The parties exchanging SOAP messages are responsible for defining  header entries for processing them. <SOAP-ENV:Header> <MSG:priority xmlns:MSG="http://www.gsx.com/">9</MSG:priority> </SOAP-ENV:Header> This message has a header... ...containing one entry <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- <SOAP-ENV:Body> . . . </SOAP-ENV:Body> </SOAP-ENV:Envelope> <MSG:priority xmlns:MSG="http://www.gsx.com/">9</MSG:priority>
  • 13. SOAP Developer’s Guide Version 7.1.1 13 1 Overview of SOAP Soap 1.2 message with single header entry  SOAP 1.1 Header Attributes The SOAP 1.1 specification defines the following optional attributes for a header entry.  These attributes allow an entry to specify its intended recipient and to indicate whether  the recipient is required to process the entry. The following example shows a SOAP 1.1 header entry that uses both the actor and  mustUnderstand attributes.  Message that uses the “actor” and “mustUnderstand” attributes Attribute Description actor Identifies the intended recipient of the header entry. This attribute  allows a sender to direct a header entry to a specific process. mustUnderstand Indicates whether processing of the header entry is mandatory.  Recipients that do not recognize an entry whose mustUnderstand  attribute is set to 1 must reject the message and return a fault to the  client. <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"> > </SOAP-ENV:Header> <?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:Body> . . . </SOAP-ENV:Body> </SOAP-ENV:Envelope> <MSG:priority xmlns:MSG="http://www.gsx.com/">9</MSG:priority> <MSG:nextDest xmlns=MSG:"http://www.gsx.com/" SOAP-ENV:actor="http://www.gsx.com/msgRouter" SOAP-ENV:mustUnderstand="1"> rubicon:5555 </MSG:nextDest> . . . <SOAP-ENV:Header> </SOAP-ENV:Header> . . . SOAP-ENV:actor="http://www.gsx.com/msgRouter" SOAP-ENV:mustUnderstand="1"
  • 14. 1 Overview of SOAP 14 SOAP Developer’s Guide Version 7.1.1 For more information about using the actor and mustUnderstand attributes, see the Simple  Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at  http://www.w3.org/TR/SOAP/#_Toc478383498. SOAP 1.2 Header Attributes The SOAP 1.2 specification defines the optional attributes for a header entry. The following example shows a SOAP 1.2 header entry that uses both the role and  mustUnderstand attributes. Message that uses the “role” and “mustUnderstand” attributes  For more information about using the role and mustUnderstand attributes, see the SOAP 1.2  W3C Recommendation 27 April 2007 at http://www.w3.org/TR/2003/REC‐soap12‐part1. The Body When a SOAP message conveys an arbitrary XML document (sometimes referred to as  application data or the business payload), the document is carried in the body of the  message. When SOAP is used as an RPC protocol, the body specifies the method name  that the client is calling and carries the method’s input values. Attribute Description encodingStyle Identifies the encoding used to serialize parts of a SOAP message.  role Identifies the SOAP node to which a particular SOAP header entry is  targeted. mustUnderstand Identifies whether processing of the header entry is mandatory.  Recipients that do not recognize an entry whose mustUnderstand  attribute is set to 1 must reject the message and return a fault to the  client. relay Identifies whether a header entry targeted at a SOAP receiver must  be relayed, if it is not processed. <<MSG:nextDest> xmlns:hb1="http://example.org/hb1" SOAP-ENV:actor="http://www.gsx.com/msgRouter" SOAP-ENV:mustUnderstand="1"> </MSG:nextDest> This header entry... ...uses both the role and mustUnderstand attributes . . . <SOAP-ENV:Header> </SOAP-ENV:Header> . . SOAP-ENV:role="http://example.org/Qos" SOAP-ENV:mustUnderstand="1"> rubicon:5555
  • 15. SOAP Developer’s Guide Version 7.1.1 15 1 Overview of SOAP A SOAP message must contain a body element. This element must be named Body. If a  SOAP message contains a header, the Body element must appear immediately after the  header. Otherwise, the body must be the first element in the SOAP envelope.  Each immediate child of the Body element is referred to as a body entry. A body containing one entry A body containing two body entries Note: Although a SOAP message must contain a body, the body does not have to  contain data. A message that has an empty Body element is a valid SOAP message. . . . <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> . . . . . . <SOAP-ENV:Body> <RQ:addr xmlns:RQ="http://www.gsx.com/rfq/"> <street1>1501 Bridger Hwy<street1> <street2></street2> <city>Laurel</city> <state>MN</state> </RQ:addr> <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> </SOAP-ENV:Body> . . .
  • 16. 1 Overview of SOAP 16 SOAP Developer’s Guide Version 7.1.1 SOAP Fault Elements The SOAP specification defines one body element, whose name is Fault. A recipient must  return the Fault element if it cannot process a SOAP message successfully. SOAP 1.2  faults are structured differently than SOAP 1.1. The SOAP 1.1 fault element contains the following child elements:  The SOAP 1.2 fault element contains the following child elements: Element Value <faultcode> A qualified name indicating the type of error that occurred. The  SOAP specification defines several standard error codes (for  example, SOAP-ENV:Server, SOAP-ENV:Client). See  http://www.w3.org/TR/2000/NOTE‐SOAP‐20000508/ for details. <faultstring> A string describing the fault that occurred. <faultactor> Optional. A URI indicating which process or application produced  the fault. <detail> Optional. An element containing implementation‐specific details  about the error. This element must be present if the error occurs  while processing the body of the message. For a description of the  detail element returned by Integration Server, see Appendix A,  “SOAP Faults Returned by the Integration Server”. Element Value Code An element containing the child value <env:Value> with value of  Version Mismatch, mustUnderstand, dataEncodingUnknown,  Sender, Receiver, and the optional sub elements <env:Subcode> and  <env:Value>. Reason An element intended to provide a human readable explanation of  the fault. The value is in the form of a string. Node Optional. A URI for the SOAP node that generated the fault. Role Optional. The role played by the node that generated the fault. Detail Optional. An element containing implementation‐specific details  about the error. This element must be present if the error occurs  while processing the body of the message. For a description of the  detail element returned by the webMethods Integration Server, see  Appendix A, “SOAP Faults Returned by the Integration Server”. Note: Faults must be namespace‐qualified with the namespace   http://www.w3.org/2003/05/soap‐envelope.
  • 17. SOAP Developer’s Guide Version 7.1.1 17 1 Overview of SOAP The following shows an example of the SOAP 1.1 fault that the Integration Server returns  when a sender submits a message to a non‐existent SOAP processor. A SOAP message returning a fault When you write clients that submit SOAP messages to the Integration Server, your client  code should test for the presence of a fault code and process the response appropriately.  For information about when and how the Integration Server returns a SOAP fault, see  Appendix A, “SOAP Faults Returned by the Integration Server”. Trailers The SOAP 1.1 specification permits additional implementation‐specific elements  (elements besides a header and a body) to reside in a SOAP envelope. The Integration  Server refers to these elements as trailers. If a SOAP envelope carries trailers, they must  appear after the body and they must be namespace qualified.  Important! SOAP 1.2 does not support trailers. If you are designing a new solution,  Software AG recommends against the use of trailers. However, if you exchange SOAP  messages with older systems that use trailers, Integration Server provides services  that allow them to work.  <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:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <SOAP-ENV:Body> </SOAP-ENV:Body> </SOAP-ENV:Envelope> A fault is returned in the body of a message
  • 18. 1 Overview of SOAP 18 SOAP Developer’s Guide Version 7.1.1 A SOAP 1.1 message containing two trailers  Trailers allow you to transmit information in a SOAP message without placing it in the  body or the header of the message. Although used infrequently, they are permitted by the  SOAP 1.1 specification and they provide a mechanism that you can use to deliver  information to a pre‐processor, a message handler or some other intermediate process  without trespassing on the message’s header or body. <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 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> </SOAP-ENV:Envelope> <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> trailer trailer
  • 19. SOAP Developer’s Guide Version 7.1.1 19 2 SOAP Support on the webMethods Integration Server Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Receiving SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Sending SOAP Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Sending SOAP RPC Messages with the Integration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
  • 20. 2 SOAP Support on the webMethods Integration Server 20 SOAP Developer’s Guide Version 7.1.1 Overview Support for SOAP is delivered by a SOAP message handler and a set of built‐in services.  These facilities allow you to: Receive and process SOAP messages via HTTP or HTTPS. Submit SOAP messages to other servers via HTTP or HTTPS. Compose and decompose SOAP messages using a set of built‐in services. Use RPC‐Encoded, RPC‐Literal or Document‐Literal messaging for SOAP 1.1  requests and Document‐Literal messaging for SOAP 1.2 requests. Make Integration Server services available to clients via RPC‐Encoded or Document‐ Literal bindings. For more information about bindings, see the Web Services  Developerʹs Guide. SOAP Versions Supported by webMethods Integration Server The webMethods Integration Server supports SOAP 1.1 as described in Simple Object  Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/ and  SOAP 1.2 as described in SOAP 1.2 W3C Recommendation 27 April 2007 at  http://www.w3c.org/TR/soap12‐part1/. Receiving SOAP Messages with the Integration Server The following diagram illustrates the process by which Integration Server receives and  processes SOAP messages. Processing and receiving a SOAP request HTTP Client HTTP Listener- Dispatcher 21 3 webMethods Integration Server SOAP Message Handler SOAP Default Processor Service Service Service Service Service Service Service Service Service Service Service 4 HTTP Client HTTP Listener- Dispatcher 21 3 webMethods Integration Server SOAP Message Handler SOAP Default Processor Service Service Service Service Service Service Service Service Service Service Service 4
  • 21. SOAP Developer’s Guide Version 7.1.1 21 2 SOAP Support on the webMethods Integration Server An HTTP client submits a SOAP message by posting it to the URL for a SOAP processor  on the Integration Server. A SOAP processor is a special service that operates on SOAP  messages. The URL for a SOAP processor has the following format: http://hostName:portNum/soap/[processDirective] When the Integration Server receives a message for a SOAP processor, it passes the  message to the SOAP message handler, which does the following: Verifies that the requested SOAP processor is registered on the server. If the SOAP  processor does not exist or is not available, the message handler returns a SOAP fault  containing the ISS.0088.9123 or ISS.0088.9111 error. (For a description of these error  messages, see Appendix A, “SOAP Faults Returned by the Integration Server”.) Verifies that the message declares the appropriate SOAP namespace. If the message  does not declare a namespace or declares a namespace other than  http://schemas.xmlsoap.org/soap/envelope/ (SOAP 1.1) or http://www.w3.org/2003/05/soap- envelope/ (SOAP 1.2), the message handler returns a SOAP fault containing the  ISS.0088.9128 error. Validates the structure of the message against the SOAP schema (if the SOAP  processor requests message validation). If the message violates the SOAP schema, the  message handler returns a SOAP fault containing the ISS.0088.91125 error. Stage 1Stage 1 The HTTP Client Posts a SOAP Document to the Integration Server Where... Is... hostName The numeric IP address or name of the webMethods Integration  Server. portNum The number of a port on which hostName accepts HTTP or HTTPS  requests.  processDirective The process directive associated with the requested SOAP  processor. The process directive is a unique name that you assign to  a SOAP processor when you register it on the Integration Server. If  processDirective is omitted or set to “default,” the message is passed  to the default SOAP processor. The Web Services processor is the  default processor; provided with webMethods Integration Server. Stage 2 The SOAP Message Handler Invokes the Appropriate SOAP Processor Note: Any binding other than SOAP 1.1 or SOAP 1.2, as well as any extensions to  SOAP, will produce an error message. Integration Server does not support  extensions to SOAP (such as stk:binding, for example). 
  • 22. 2 SOAP Support on the webMethods Integration Server 22 SOAP Developer’s Guide Version 7.1.1 During the validation step, the message handler validates the structure of the SOAP  envelope only. For example, it ensures that the message has at least one body element  and only one header element. After the message handler establishes that the SOAP processor is available and has  received a valid SOAP message, the message handler does the following: Transforms the message into a soapRequestData object. This object contains the entire  SOAP envelope in addition to other operational values that the Integration Server  uses to manage the message internally. Creates an empty soapResponseData object. This object is used to compose the message  to be returned to the client. Invokes the requested SOAP processor and passes the soapRequestData and  soapResponseData objects to it. The selected SOAP processor handles the message in soapRequestData (usually by calling  other services on the webMethods Integration Server) and composes a response message  in soapResponseData. When the SOAP processor ends or exits, the message handler generates an HTTP  response from the message contained in soapResponseData and returns it to the client. Important! Validating the application data that is carried inside the SOAP envelope is  the responsibility of the processor or application that consumes the SOAP message. Stage 3 The SOAP Processor Performs Work and Generates a Response Note: For Integration Server 7.1, the RPC processor and the use of custom SOAP  processors is deprecated. Processors built with prior versions of Integration Server  are still supported. Stage 4 The Message Handler Returns the Response to the Client Note: If the SOAP processor or one of the services it calls throws an exception, the  message handler automatically returns a SOAP fault to the client.
  • 23. SOAP Developer’s Guide Version 7.1.1 23 2 SOAP Support on the webMethods Integration Server Sending SOAP Messages with the Integration Server Besides receiving and processing SOAP messages, the Integration Server can send SOAP  messages to remote servers via HTTP.  To send a SOAP message, execute pub.client:soapHTTP with the following input parameters: Input Parameter Description soapRequestData The soapRequestData object containing the message that you want to  send. You construct and populate this object using the server’s  message composition services (for example, createSoapData,  addHeaderEntry, addBodyEntry). address The URL where the SOAP message is to be sent. Example: http://servername:5555/soap/rpc auth Optional. The user name and password that the Integration Server  must supply when it connects to the target server. validateSOAP Optional. Indicates whether the response message will be validated  against the SOAP schema.  Set to ...    To ...  true Validate the response message and throw an exception  if the response does not conform to the SOAP schema. false Bypass the validation process (default). SOAPAction Optional. Value to which you want to set the SOAPAction HTTP  header. Note: The SOAPAction header was required by the initial SOAP  specification but has since been deprecated as per SOAP specification  1.2. The Integration Server does not use the SOAPAction header and  accepts SOAP messages that omit it. If you are designing a  completely new solution, we recommend that you avoid using the  SOAPAction header. However, if you exchange SOAP messages with  systems that require a SOAPAction header, this parameter allows you  to set it.  Important! If you are designing a Web service descriptor with multiple  binders that contain the same operation name,  Developer cannot  calculate a unique QName from the first element in the SOAP body  in order to identify the correct operation. In that case, you must  specify a unique SOAPAction parameter for every request, as  described in the “Modifying the SOAP Action for an Operation”  section of the Web Services Developer’s Guide.  contentType Optional. Specifies the value of Content‐Type in the HTTP header. 
  • 24. 2 SOAP Support on the webMethods Integration Server 24 SOAP Developer’s Guide Version 7.1.1 This service returns a soapResponseData object that contains the response document  returned by the target server. You use the server’s data‐retrieval services (for example,  getHeaderEntries, getBody) to retrieve information from the message.  For more information about sending SOAP messages from the Integration Server, see  “Composing and Sending SOAP Messages” on page 49. Sending SOAP RPC Messages with the Integration Server The Integration Server supports SOAP RPC, which allows you to make remote procedure  calls to other servers with SOAP.  To submit a remote procedure call, you execute pub.client:soapRPC with the following basic  set of parameters: loadAs Optional. Specifies the format of the soapResponseData. Default is  stream for an HTTP service and byteArrayStream for an HTTPS  service.  Set to... To... stream Return the response body as a java.io.InputStream object.  Use this setting to invoke an HTTP Web service. bytes Return the response body as a byte array. Use this setting  if the message body will be used as input to a service that  operates on entire HTML or XML documents. byteArray Stream Read the response stream fully and convert to a  java.io.ByteArrayStream object. This setting prevents  data loss or a truncated SOAP response if the connection  closes prematurely. Use this setting to invoke an HTTPS  Web service. timeout Optional. Time (in milliseconds) to wait for a response from the  remote server before timing out and terminating the request. The  default value is to wait forever. Note: SOAP RPC is supported only by SOAP 1.1. Input Parameter Description address A string specifying the HTTP address of the server on which the  remote procedure resides. (If you are submitting the request to a  webMethods Integration Server, remember to direct it to the  RPC processor as shown in the following example.) Example: http://servername:5555/soap/rpc Input Parameter Description
  • 25. SOAP Developer’s Guide Version 7.1.1 25 2 SOAP Support on the webMethods Integration Server reqParms A document (an IData object) whose elements represent the  input parameters that are to be passed to the remote procedure.  For example, if you were to pass three string parameters, acct,  amt, and org, containing the values, Cash, 150.00 and Sales,  reqParms would contain the following: Key Value acct Cash amt 150.00 org Sales At run time, the values in reqParms are XML‐encoded by the  message coder. For a description of this process, see “Encoding  the Input Parameters for the Remote Procedure Call” on  page 71. method A document (an IData object) specifying the QName of the  requested procedure, where: Key Description namespaceName A string specifying the namespace portion  of the procedure’s QName. localName A string specifying the local portion of the  procedure’s QName. auth A document (an IData object) specifying the user name and  password that are to be submitted to the server specified in  address, where: Key Description type A string specifying the type of  authentication that the server uses. Set type  to basic. user A string specifying the user name that is to  be presented to the server. pass A string specifying the password for the  user name specified in user. Input Parameter Description
  • 26. 2 SOAP Support on the webMethods Integration Server 26 SOAP Developer’s Guide Version 7.1.1 targetInputSignature Optional. A string specifying the fully qualified name of the  document type that is to be used to validate and encode the  contents of reqParms. For a description of how the message  coder uses targetInputSignature, see “Encoding the Input  Parameters for the Remote Procedure Call” on page 71. targetOutputSignature Optional. A string specifying the fully qualified name of the  document type that is to be used to validate and decode the  output value returned by the remote procedure. For a  description of how the message coder uses targetInputSignature,  see “Decoding the Output Parameters from a Remote Procedure  Call” on page 73. SOAPAction Optional. A string specifying the value to which you want the  SOAPAction HTTP header set. Note: The SOAPAction header was required by the initial SOAP  specification, but has since been deprecated as per SOAP  specification 1.2. The Integration Server does not use the  SOAPAction header and accepts SOAP messages that omit it. If you are designing a completely new solution, we recommend  that you avoid using the SOAPAction header. However, if you  exchange SOAP messages with systems that require a  SOAPAction header, this parameter allows you to set it. Important!  If you are designing a Web service descriptor with  multiple binders that contain the same operation name,   Developer cannot calculate a unique QName from the first  element in the SOAP body in order to identify the correct  operation. In that case, you must specify a unique SOAPAction  parameter for every request, as described in the “Modifying the  SOAP Action for an Operation” section of the Web Services  Developer’s Guide.  contentType  Optional. A string that specifies the value of Content‐Type in the  HTTP header.  Set to... To... text/xml; charset=”utf-8” Default. Specify the content type as XML  and the character encoding of the text as  UTF‐8.  text/xml Specify the content type as XML. Since the  charset parameter is not specified, the  character encoding of the text defaults to  US‐ASCII.  Input Parameter Description
  • 27. SOAP Developer’s Guide Version 7.1.1 27 2 SOAP Support on the webMethods Integration Server This service returns a document (an IData object) called respParms, which contains the  results from the remote procedure. For information about submitting SOAP remote procedure calls from the Integration  Server, see “Using the SOAP RPC Client” on page 63. encoding Optional. Specifies the encoding method. Default value is UTF‐ 8.  loadAs Optional. Specifies the format of the soapResponseData. Default  value is stream for an HTTP service and byteArrayStream for an  HTTPS service.  Set to... To... stream Return the response body as a  java.io.InputStream object. Use this option  to invoke an HTTP Web service. byteArrayStream Read the response stream fully and convert  to a java.io.ByteArrayStream object. This  setting prevents data loss or a truncated  SOAP response if the connection closes  prematurely. Use this setting to invoke an  HTTPS Web service. timeout Optional. Time (in milliseconds) to wait for a response from the  remote server before timing out and terminating the request.  The default value is to wait forever. Input Parameter Description
  • 28. 2 SOAP Support on the webMethods Integration Server 28 SOAP Developer’s Guide Version 7.1.1
  • 29. SOAP Developer’s Guide Version 7.1.1 29 3 Building Solutions with SOAP Building Solutions that Receive SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Building Solutions that Send SOAP Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  • 30. 3 Building Solutions with SOAP 30 SOAP Developer’s Guide Version 7.1.1 Building Solutions that Receive SOAP Messages If you are building a solution that receives and processes SOAP messages, you must: Understand the structure of the SOAP message that clients will submit to your  Integration Server. Define the work that you want the Integration Server to perform when it receives the  SOAP message. Determine whether the SOAP processor provided by the Integration Server will  satisfy the needs of your solution or whether you will need to build and register a  “custom” SOAP processor. What is a SOAP Processor? A SOAP processor is a service that acts upon SOAP messages that the Integration Server  receives. When the SOAP message handler receives a SOAP message, it invokes the  SOAP processor based on the process directive specified in the URL requested by the client.  The process directive is the last segment of the URL for the SOAP message handler on a  webMethods Integration Server. For example, if a client submits a SOAP request to the  following URL, the SOAP message handler would invoke the SOAP processor registered  as “genLedger.” Note: The SOAP processors that were provided with previous versions of Integration  Server are deprecated, but are still supported. Custom SOAP processors created for  previous versions of Integration Server are also deprecated. The process directive determines the SOAP processor to which the message is passedhttp://rubicon:5555/soap/genLedger
  • 31. SOAP Developer’s Guide Version 7.1.1 31 3 Building Solutions with SOAP SOAP Processors Provided by the Integration Server The Integration Server is installed with the following SOAP processors: Universal Names A universal name is a unique public identifier that external protocols use to reference a  service on a webMethods Integration Server. A QName is a qualified name, made up of a  namespace URI, a local part, and a prefix. The SOAP processor routes messages to services based on a qualified name (QName). If  the SOAP message includes an HTTP header, the QName is derived from the  SOAPAction (SOAP 1.1) or ActionHTTP (SOAP 1.2) field of the header. If the SOAP  message does not include an HTTP header, the QName is derived from the first element  in the SOAP body.  The structure of a universal name is the same as the structure of a QName in an XML  namespace and consists of two parts: a namespace name and a local name.  The namespace name is a qualifier that distinguishes a webMethods Integration Server  service from other resources on the Internet. For example, there might be many  resources with the name AcctInfo. A namespace name distinguishes one AcctInfo  resource from another by specifying the name of the collection to which it belongs  (similar to the way in which a state or province name serves to distinguish cities with  the same name—for example, Springfield, Illinois, versus Springfield, Ontario). Like namespaces in XML, the namespace portion of a universal name is expressed as  a URI. This serves to assure uniqueness, because URIs are based on globally unique  domain names. SOAP Processor Description default This is a basic processor that invokes a service based on the QName.  This processor passes the entire envelope to the services that it  invokes.  The Web Services processor is the default processor  provided with Integration Server 7.1. For information about the default processor, see “Using the Default  SOAP Processor” on page 37. RPC This processor processes SOAP remote procedure calls (messages  that conform to the remote procedure call (RPC) section of the SOAP  specification). For information about the RPC processor, see Appendix D, “Using  the SOAP RPC Processor”. Note: The SOAP RPC Processor is deprecated for Integration Server  7.1. It is supported only for Web service connectors created in earlier  versions of Integration Server.
  • 32. 3 Building Solutions with SOAP 32 SOAP Developer’s Guide Version 7.1.1 The namespace portion of the universal name can consist of any combination of  characters that form a valid absolute URI (relative URIs are not supported). For  example, the following are all valid namespace names: http://www.gsx.com http://www.gsx.com/gl/journals http://www.ugmed.ch/résumè For a complete description of what makes up a valid URI, see RFC 3986 Uniform  Resource Identifiers (URI): Generic Syntax at http://www.ietf.org/rfc/rfc3986.txt.  The local name uniquely identifies a service within a particular namespace. Many  webMethods users use a serviceʹs unqualified name as its local name. Under this  scheme, a service named gl.journals:closeGL would have a local name of closeGL.  Local names follow the same construction rules as NCNames in XML. Basically, a  local name can be composed of any combination of letters, digits, or the period (.),  dash (‐), and underscore (_) characters. Additionally, it must begin with a letter or an underscore character (the _ character).  The following are examples of valid local names: addCustOrder authorize-Level1 générent For specific rules relating to NCNames, see the “NCName” definition in the  Namespaces in XML specification at http://www.w3.org/TR/1999/REC‐xml‐names‐ 19990114. Note: The server normalizes Universal Names according to Unicode Normalization  Form C, as recommended by the Character Model, SOAP, and XML standards. This  ensures that names containing non‐ASCII characters (particularly those with  accented or combining characters) are represented in a standard way. For information about normalization, see http://www.unicode.org/reports/tr15/  (Unicode Standard Annex #15) and http://www.w3.org/TR/charmod/ (Character  Model for the World Wide Web).
  • 33. SOAP Developer’s Guide Version 7.1.1 33 3 Building Solutions with SOAP Implicit and Explicit Universal Names Every service that exists on a webMethods Integration Server has an explicit or an implicit  universal name. An explicit universal name is a universal name that you specifically assign to a service  with Developer. When you assign an explicit universal name, you must specify both  the namespace name and the local name. Specifying explicit universal names in Developer An implicit universal name is automatically derived from the name of the service itself.  The implicit name acts as the universal name when a service does not have an explicit  universal name. The server derives an implicit name as follows: The namespace name is the literal string http://localhost/ followed by the fully  qualified name of the folder in which the service resides on the Integration Server. The local name is the unqualified name of the service. The following table shows the implicit names for a variety of service names: The service’s implicit universal name is... Fully qualified service name Namespace name Local name gl.journals:jrnlEntry http://localhost/gl.journals jrnlEntry gl.journals.query:viewJournals http://localhost/gl.journals.query viewJournals orders:postPO http://localhost/orders postPO Important! To ensure interoperability with other vendor’s implementations of SOAP,  we recommend that you always assign explicit universal names to those services that  you want to make available to SOAP clients. Note:  Earlier versions of the webMethods SOAP implementation did not include the     http://localhost/ prefix as part of an implicit name. However, the server is  backward compatible. It will resolve QNames that clients submit in either the old  form (without the http prefix) or the new form (with the http prefix).  You assign an explicit universal name on the Properties panel in Developer
  • 34. 3 Building Solutions with SOAP 34 SOAP Developer’s Guide Version 7.1.1 1 Start Developer and connect to the server on which the service resides. 2 From the Navigation panel, open the service whose universal name you want to  assign, edit, or view. 3 If you want to assign or edit the service’s universal name, specify the following in the  Universal name category of the service’s Properties panel: 4 On the File menu, click Save to save the new settings. Note:  It is possible for an implicit name to match the explicit name of another service.  When this condition exists, the explicit name takes precedence. That is, when a  universal name is requested, the Integration Server searches its registry of explicit  names first. If it does not find the requested name there, it looks for a matching  implicit name. To assign, edit, or view an explicit universal name In this field... Specify... Namespace name The URI that will qualify the local name of this service. The  name can be composed of any sequence of characters except  leading and trailing white‐space characters Local name A name that uniquely identifies the service within the  collection encompassed by Namespace name. The name can be  composed of any combination of letters, digits, or the period  (.), dash (‐), and underscore (_) characters. Additionally, it  must begin with a letter or the underscore character. Note: Many webMethods users use the unqualified portion of  the service name as the local name. Important!  When you assign an explicit universal name to a service, you must enter  values in both the Namespace name and Local name fields. If you specify one field but  not the other, you will receive an error message when you attempt to save the service.  You will not be permitted to save the service until you specify both parts of the  universal name.  Note: If you move a service, or a folder containing a service, Developer retains the  service’s explicit universal name. If you copy a service or a folder containing a service,  Developer does not retain the service’s explicit universal name. You must restore the  universal name for the copied service by editing the service’s properties.
  • 35. SOAP Developer’s Guide Version 7.1.1 35 3 Building Solutions with SOAP 1 Start Developer and connect to the server on which the service resides. 2 From the Navigation Panel, open the service whose universal name you want to  delete. 3 In the Universal name category of the service’s Properties panel, remove the current  settings from the Namespace name and Local name fields.  4 On the File menu, click Save to save the new settings. The Universal Name Registry The webMethods Integration Server maintains a registry, called the Universal Name  Registry, which maps explicit universal names to the services that they represent. The  registry is generated each time the Integration Server is started and is maintained in  memory while the server is running. When you use the Developer to assign, modify, or delete a service’s universal name, you  update the Universal Name Registry. To view the contents of the registry, you can execute  the service pub.universalName:list in Developer and view the contents of the names variable  on the Results panel. (This service resides in the WmPublic package.) Services You Use to Interact with the Registry The following services can be used to display the Universal Name Registry or locate the  name of a service associated with an explicit universal name. For more information about  these services, see the webMethods Integration Server Built‐In Services Reference. Building Solutions that Send SOAP Messages To build a solution that sends a SOAP message to a SOAP‐compliant server, you need to  do the following: Define the structure of the SOAP message that you want to send. Determine where the SOAP message will be submitted for processing (get the URL of  the server that will process the message). To delete an explicit universal name Service Description pub.universalName:list Returns a document list containing the entries in the current  registry. Each document in the list represents an entry in the  registry and contains a service’s fully qualified webMethods  name and both parts of its explicit universal name. pub.universalName:find Returns the fully qualified service name for a specified explicit  universal name.
  • 36. 3 Building Solutions with SOAP 36 SOAP Developer’s Guide Version 7.1.1 Understand the structure of the SOAP message that the server will return in response  to the SOAP message that you send. Build a service that composes the SOAP message, submits it via HTTP to the  appropriate server, and processes the response. For information about building services that compose and send SOAP messages, see  “Composing and Sending SOAP Messages” on page 49. For information about building a services that submit SOAP RPC messages to remote  servers, see “Using the SOAP RPC Client” on page 63.    Note: SOAP RPC messages are only supported by SOAP 1.1.
  • 37. SOAP Developer’s Guide Version 7.1.1 37 4 Using the Default SOAP Processor Accessing the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Behavior of the Default SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Building Target Services for the Default Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
  • 38. 4 Using the Default SOAP Processor 38 SOAP Developer’s Guide Version 7.1.1 Accessing the Default Processor The Integration Server provides a default SOAP processor registered under the name  Web Services processor. The SOAP message handler invokes this SOAP processor when  the process directive is omitted or when the specified process directive is undefined in  Integration Server. The following examples illustrate the two types of URLs that invoke the default  processor: Behavior of the Default SOAP Processor The default SOAP processor acts as a dispatcher that delegates messages to other services  on the Integration Server. It does this by invoking the service whose universal name  matches the qualified name (QName) of the message body’s first element or of the action  field in the message header. This service is referred to as the target service.  How the Processor Selects the Target Service The default SOAP processor selects a target service by matching the fully expanded  QName to a universal name (implicit or explicit) of a service on the webMethods  Integration Server. For example, if the default processor were to receive a SOAP message with the body  shown below, it would invoke the service whose universal name is made up of the  namespace name http://www/exprint.com/GL/ and the local name JournalEntry. If the default processor received a message with the body shown below, it would invoke  the service whose implicit universal name is made up of the namespace name  You can specify the “ws” process directive... ...or omit the process directive http://rubicon:5555/soap/ws/example:calculator —OR— http://rubicon:5555/soap/ . . . <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> . . .
  • 39. SOAP Developer’s Guide Version 7.1.1 39 4 Using the Default SOAP Processor GL.journals.queries and the local name viewJournal. (Recall that an implicit name is derived by  combining a service’s fully qualified service name with the prefix string  http://localhost/.) What if the Requested Service Does Not Exist? If the default processor cannot locate the service whose universal name matches the  QName of the body’s first element or of the action field in the message header, it returns a  SOAP fault to the client with the following error: [ISS.0088.9122] Service namespaceName:localName does not exist. See Appendix A, “SOAP Faults Returned by  the Integration Server” for information about this error. Processor Inputs and Outputs When the default SOAP processor calls a target service, it passes two input parameters to  the service:  soapRequestData, an object containing the entire SOAP message soapResponseData, an object containing an empty SOAP message. When the target service exits, the default SOAP processor returns soapResponseData to the  SOAP message handler. The message handler extracts the SOAP message from  soapResponseData and returns the message to the client.  Be aware that neither the default processor nor the SOAP message handler adds any  content to the response message in soapResponseData. It is the responsibility of the target  service to populate soapResponseData with message content.  Note:  The Integration Server expects the QName in the incoming SOAP message to be  normalized according to Unicode Normalization Form C. Normalization assures that  names containing non‐ASCII characters (particularly those with accented or  combining characters) are represented in a standard way. If the client has not  normalized the QName, the Integration Server might not be able to properly match it  with a universal name in its registry.  . . . <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> . . .
  • 40. 4 Using the Default SOAP Processor 40 SOAP Developer’s Guide Version 7.1.1 Building Target Services for the Default Processor To use the default SOAP processor, you must build target services that process incoming  SOAP messages. A target service can be any type of service: a flow service, a Java service,  a C/C++ service. However, it must accept a soapRequestData object and a soapResponseData  object as input. Additionally, the target service must produce a soapResponseData object  that is populated with the data that is to be returned to the client. A target service can contain any sort of logic. A target service usually performs three  basic tasks:  It extracts the pertinent information from the incoming SOAP message. It processes the information (usually by passing it to one or more services that  perform some type of business logic). It composes the response SOAP message to be returned to the client. How to Create a Target Service for the Default Processor The following describes the general steps you take to create a target service for the  default processor. 1 Create a new service that has the following signature: You can use pub.soap.utils:requestResponseSpec to specify the inputs and outputs for the  service.  2 Use the SOAP data-retrieval utilities to extract information from the message. The data‐ retrieval utilities are services such as getBody and getHeaderEntries, which you use to  fetch elements from SOAP message objects. These services return the requested  element as an XML node (or an array of XML nodes). To extract data from the  returned node, you query it using the pub.xml:queryXMLNode service.  3 Invoke services to perform work on the extracted data. After extracting the data with which  you want to work, you can pass it to services that contain your business logic. (To  ensure that the data you have extracted is in the correct format, you might want to  validate it with pub.schema:validate or make sure that the service to which you pass the  data performs data validation on its input parameters.) Inputs: soapRequestData   (of type Object) soapResponseData   (of type Object) Outputs: soapResponseData   (of type Object) Important! Be aware that you cannot query a soapRequestData object directly. To  extract information from soapRequestData (or similar SOAP objects, such as  soapData and soapResponseData), you must use one of the data‐retrieval services to  extract an element of the message (for example, the header, the body, or the entire  envelope) and query the resulting XML node.
  • 41. SOAP Developer’s Guide Version 7.1.1 41 4 Using the Default SOAP Processor 4 Use the SOAP message-composition utilities to populate soapResponseData. The message‐ composition utilities are services such as addHeaderEntry and addBodyEntry that you use  to add content to the empty message in soapResponseData.  The message‐composition services require an XML node representation of the header  entry, body entry, or trailer that you want to add to the message. You can generate an  XML node using the services pub.xml:documentToXMLString and  pub.xml:xmlStringToXMLNode. For an example of how to do this, see Step 3.1 in the sample  code shown on page 43. 5 Assign the appropriate universal name to the service. When you finish building a target  service, you must ensure that its universal name matches the QName that clients will  use to direct SOAP messages to it. In other words, the service’s universal name must  match the QName of the first element in the body or the action field in the header of  the client’s SOAP message. For information about setting a universal name, see “To  assign, edit, or view an explicit universal name” on page 34.  Error Handling If a target service throws an exception while it is processing, the message handler  automatically returns a SOAP fault to the client. Depending on the type of error that  occurs, the SOAP fault may include a “detail” element, which provides specific  information about the exception. This element will include a stackTrace element if the  client is a member of the Developers or Administrators user group. Note: By default, nodes that you add to a soapResponseData must be namespace  qualified. If you attempt to add a header entry or body entry that is not  namespace qualified, the server will throw an exception. For additional  information, see the pub.soap.utils:addHeaderEntry and pub.soap.utils:addBodyEntry entries  in the webMethods Integration Server Built‐In Services Reference. Note:  As a best practice, we recommend that you always assign explicit universal  names to target services. 
  • 42. 4 Using the Default SOAP Processor 42 SOAP Developer’s Guide Version 7.1.1 For more information about SOAP faults, see Appendix A, “SOAP Faults Returned by  the Integration Server”. Example—Target Service for Default Processor The following is an example of a target service that takes a SOAP message, extracts  information from the body of the message, passes the information to a set of business  services, and composes a SOAP response containing the results of the services.  This example is located in sample.soap:targetSvc_defaultProc in the WmSamples package. You  can find the WmSamples package in the certified samples area of the Knowledge Base on  the Advantage Web Site. You may want to open this example with Developer to see how  the pipeline is mapped between steps. Note: The SOAP message returned to the client when an exception occurs contains  only the SOAP fault. It does not include any message content (for example, header  entries, body entries) that the target service may have inserted into soapResponseData  before the exception occurred. Note: If you want to execute this service from Developer, enable the  acquireSOAPMessage step at the top of the flow. This service generates a test  soapRequestData and soapResponseData object, which simulates the pipeline that this  service would receive from the default SOAP processor. If you want to execute this  service as a target of the default processor, disable the acquireSOAPMessage step. <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode> SOAP-ENV:Client </faultcode> <faultstring> [ISS.088.9134] Exception occurred while processing body of the message </faultstring> <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> <stackTrace xml:lang="en-US">textFromStackTrace</stackTrace> </exception> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope> ...containing an error message... When the target service throws an exception, the message handler returns a SOAP fault... ...and details about the error.
  • 43. SOAP Developer’s Guide Version 7.1.1 43 4 Using the Default SOAP Processor Target service that extracts data from a SOAP message and composes a response # Description Step 1 Extract data from SOAP Request Message. This sequence retrieves several specific  pieces of business data by extracting the body of the message from  soapRequestData and querying the result. This example expects a SOAP  message structured as follows: <?xml version="1.0" encoding="UTF-8"?> <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> </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> </SOAP-ENV:Envelope>
  • 44. 4 Using the Default SOAP Processor 44 SOAP Developer’s Guide Version 7.1.1 To extract the business data from the message, this service executes the  following steps: Step Description 1.1 getBody—This step retrieves the body of the message from  soapRequestData. It returns an XML node that represents the entire  Body element. 1.2 queryXMLNode—This step extracts the business data by executing the  following XQL queries against the XML node returned in Step 1.1. Var Name XQL Query acct /RFQ:quoteReq/acct/text() stock /RFQ:quoteReq/jobSpecs/stock/text() copies /RFQ:quoteReq/jobSpecs/copies/text() ink /RFQ:quoteReq/jobSpecs/ink/text() If you examine the queryXMLNode step with Developer, you will see  that it also executes the following query, which extracts the entire  Body node to a String: Var Name XQL Query wholeNode /source() This query is included for debugging purposes. It allows you to  examine the raw XML associated with the Body node. If you were to  put this service into production, you would omit this query. 1.3 MAP—This step maps the results from Step 1.2 to a document that will  be processed by the business services in the next step. It also cleans up  the pipeline by dropping unneeded variables. Step 2 Perform business logic. This sequence invokes business services that process the  data extracted by Step 1. In this example, the business services use the data to  calculate the cost of a printing job. They return the cost in a variable named  qCost. # Description
  • 45. SOAP Developer’s Guide Version 7.1.1 45 4 Using the Default SOAP Processor Step 3 Compose SOAP response message. This sequence generates the response  message that carries the results back to the client. It produces a SOAP  message structured as follows: To produce this response message, the service executes the following steps: Step Description 3.1 This sequence executes the following services to add a body entry to  soapResponseData.  Step Description 3.1.1 documentToXMLString—This service generates a  document called RFQ:quoteResp, which describes the  body entry to be inserted into soapResponseData. Then it  converts that document to XML. Note that the document  includes a field called @xmlns:RFQ, which sets the  namespace attribute in the resulting XML. 3.1.2 xmlStringToXMLNode—This step converts the XML String  to an XML node object. (Recall that to add a body entry  to soapResponseData, you must place the entry in the  pipeline as an XML node.) # Description <?xml version="1.0" encoding="UTF-8"?> <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> <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> <stock>30F-SIL</stock> <ink>P440</ink> <copies>5000</copies> </jobSpecs> <qCost>2850</qCost> </RFQ:quoteResp> </SOAP-ENV:Body> </SOAP-ENV:Envelope> The service generates a header entry called “msgInfo”.. ...and a body entry called “quoteResp”
  • 46. 4 Using the Default SOAP Processor 46 SOAP Developer’s Guide Version 7.1.1 3.1.3 addBodyEntry—This step adds the body entry to  soapResponseData.  3.2 This sequence executes the following services to add a header entry to  soapResponseData. Step Description 3.2.1 documentToXMLString—This step creates a document  called AUDIT:msgInfo, which describes the header entry  to be inserted into soapResponseData and converts the  document to an XML String. Note that the document  contains a field called @xmlns:AUDIT, which sets the  namespace attribute in the resulting XML. 3.2.2 xmlStringToXMLNode—This step converts the XML String  to an XML node. (Recall that to add a header entry to  soapResponseData, you must place the entry in the  pipeline as an XML node.) 3.2.3 addHeaderEntry—This step adds the header entry to  soapResponseData. 3.3 FOR DEBUG ONLY. This step converts the contents of soapResponseData  to a String using the soapDataToString service. This allows you to  examine the finished message with Developer, which is useful during  testing and debugging. You would not include this step in a  production service. # Description
  • 47. SOAP Developer’s Guide Version 7.1.1 47 4 Using the Default SOAP Processor If you examine the contents of finishedMessage on the Results panel,  you will see a SOAP message similar to the one below. If this service  were invoked through the default processor, the message handler  would send this message to the client. # Description
  • 48. 4 Using the Default SOAP Processor 48 SOAP Developer’s Guide Version 7.1.1
  • 49. SOAP Developer’s Guide Version 7.1.1 49 5 Composing and Sending SOAP Messages Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Composing a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Sending a SOAP Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
  • 50. 5 Composing and Sending SOAP Messages 50 SOAP Developer’s Guide Version 7.1.1 Overview The Integration Server provides a set of services that allow you to generate SOAP  messages and send them across the network via HTTP. Composing a SOAP Message To compose a SOAP message, you first create an “empty” SOAP object with the  createSoapData service. Then you use the message‐composition services (for example,  addHeaderEntry and addBodyEntry) to add content to it. How to Compose a SOAP Message The following describes the general steps you take to code a service that composes a  SOAP message. 1 Create an empty SOAP object using pub.soap.utils:createSoapData. You must provide the  following input parameters. The result is an empty SOAP object named soapData in  the pipeline. Important! If you want to use SOAP to submit remote procedure calls, you compose  those messages with SOAP RPC client. For information about sending SOAP 1.1 RPC  messages, see “Using the SOAP RPC Client” on page 63.  Note: Although Integration Server supports incoming SOAP messages in any  encoding, SOAP messages sent from Integration Server always use the UTF‐8  character encoding. Name Description encoding Optional. Specifies the encoding method. Default value is UTF‐8. soapProtocol Optional. Indicates the SOAP protocol that the empty SOAP object  complies with. The default value is read from the  watt.server.SOAP.defaultProtocol property. Set to... To... SOAP 1.1  protocol Indicate the SOAP object complies with SOAP 1.1. SOAP 1.2 Indicate the SOAP object complies with SOAP 1.2.
  • 51. SOAP Developer’s Guide Version 7.1.1 51 5 Composing and Sending SOAP Messages 2 Add content to soapData using any of the following message-composition services. You can  execute these services in any order. The message‐composition services require two inputs: the soapData object to which you  are adding content and an XML node representation of the element that you want to add.  An XML node is an object that contains a parsed representation of an XML element. You  can generate an XML node, using the pub.xml:documentToXMLString and  pub.xml:xmlStringToXMLNode services. For an example of how to create an XML node, see  Step 2 and Step 3 in the sample shown on page 52. When you finish populating the soapData object, you use pub.client:soapHTTP to send the  SOAP message to a server via HTTP. For a detailed procedure, see “Sending a SOAP  Message” on page 55. Use this service... To... pub.soap.utils:addHeaderEntry Add a single header entry to the message. If your  message includes multiple header entries, execute  addHeaderEntry once for each entry that you want to  add.  pub.soap.utils:addBodyEntry Add a single body entry to the message. If your  message includes multiple body entries, execute  addBodyEntry once for each entry that you want to add. pub.soap.utils:addTrailer Add a trailer to the message. If your message includes  multiple trailers, execute addTrailer once for each trailer  that you want to add.  Note: This service is only available with SOAP 1.1. Note: Because most SOAP implementations require namespace‐qualified header and  body entries, the addHeaderEntry and addBodyEntry services will, by default, throw  exceptions if the XML node you pass to them is not namespace qualified. This  prevents you from generating and transmitting SOAP messages that are likely to be  rejected by their recipients.  Earlier versions of the Integration Server did not enforce namespace checking. If you  have a solution that produces unqualified nodes, you can suppress the server’s  default namespace checking behavior. For information, see the  watt.server.SOAP.enforceMsgPartNS parameter description in Appendix C, “SOAP‐ Related Server Parameters”.
  • 52. 5 Composing and Sending SOAP Messages 52 SOAP Developer’s Guide Version 7.1.1 Example—Composing a SOAP Message The following flow service generates a SOAP message that contains two header entries  and one body entry. This example is located in sample.soap:buildMsg_sendHTTP in the  WmSamples package. You can find the WmSamples package in the certified samples area  of the Knowledge Base on the Advantage Web Site. You may want to open this example  with Developer to see how the pipeline is mapped between steps. Composing a SOAP message Note: The following is a two‐part example. The first part illustrates how to compose a  SOAP message. This part is explained below. The second part illustrates how to send  the SOAP message. It is explained in “Sending a SOAP Message” on page 71. # Description Step 1 Create empty SOAP object. This step creates an empty SOAP object. You must  provide the following input parameters. The result is an empty SOAP object  named soapData in the pipeline. Name Description encoding Optional. Specifies the encoding method. Default value is  UTF‐8. soapProtocol Optional. Indicates the SOAP protocol that the empty SOAP  object complies with. The default value is read from the  watt.server.SOAP.defaultProtocol property. Set to... To... SOAP 1.1  protocol Indicate the SOAP object complies with  SOAP 1.1.
  • 53. SOAP Developer’s Guide Version 7.1.1 53 5 Composing and Sending SOAP Messages SOAP 1.2 Indicate the SOAP object complies with  SOAP 1.2. Step 2 Add header entries. This sequence builds the following header entries and adds  them to soapData: <AUDIT:keyCode xmlns:AUDIT="http://www.accumon.com/tracker">3</AUDIT:keyCode> <EXP:postmark xmlns:EXP="http://www.exprint.com/inbox"> <docType>GL</docType> <priority>09</priority> <sender>http://www.exprint.com/acct/AP</sender> <tStamp>20010716.0307340941</tStamp> </EXP:postmark> Note that both entries are namespace qualified, as required by the SOAP  specification.  Note: Instead of building header entries manually, you can use the Integration  Server’s enhanced Web service descriptor capabilities. To accomplish this, the service executes the following steps: Step Description 2.1 generateAuditHeader—This helper service converts a document  representation (an IData object) of the first header entry to an  XML node. (Recall that to add a header entry to a soapData  object, you must place the entry in the pipeline as an XML  node.) You can examine the helper service to understand how  this is accomplished. 2.2 addHeaderEntry—This step adds the first header entry to  soapData. 2.3 currentDate—This service generates a timestamp, which will be  inserted into the second header entry in the next step. 2.4 generatePostmarkHeader—This helper service converts a  document representation of the second header entry to an  XML node. You can examine the helper service to understand  how this is accomplished. 2.5 addHeaderEntry—This step adds the second header entry to  soapData. # Description
  • 54. 5 Composing and Sending SOAP Messages 54 SOAP Developer’s Guide Version 7.1.1 Step 3 Add body entry. This step generates the following body entry and adds it to  soapData: <GL:journalEntry xmlns:GL="http://www.exprint.com/GL/"> <entry> <ID>23209</ID> <acct>cash</acct> <amt>450.00</amt> </entry> <entry> <ID>23209</ID> <acct>AR</acct> <amt>-450.00</amt> </entry> </GL:journalEntry> To accomplish this, the service executes the following steps: Step Description 3.1 generateBodyEntry_GL—This helper service converts a  document representation of the body entry to an XML node.  (Recall that to add a body entry to a soapData object, you must  place the entry in the pipeline as an XML node.) You can  examine the helper service to understand how this is  accomplished. 3.2 addBodyEntry—This step adds the body entry to soapData. Step 4 FOR DEBUG ONLY. This step converts the contents of soapData to a String using  the soapDataToString service. This allows you to examine the finished SOAP  message with Developer, which is useful during testing and debugging. You  would not include this step in a production service. # Description
  • 55. SOAP Developer’s Guide Version 7.1.1 55 5 Composing and Sending SOAP Messages Sending a SOAP Message To use the Integration Server to send a SOAP message to a remote server, you compose  the SOAP message in a soapData object as described in the previous section (“Composing  a SOAP Message” on page 50), and then you pass that object to pub.client:soapHTTP, which  submits it to a server that you specify. SOAP messages that you send via soapHTTP elicit a response, which, if the target server is  SOAP compliant, will be a SOAP response document. Therefore, your service must also  include logic to process the response that the target server returns. If you examine the contents of string on the Results panel, you will see a  SOAP message similar to the following: # Description
  • 56. 5 Composing and Sending SOAP Messages 56 SOAP Developer’s Guide Version 7.1.1 How to Send a SOAP Message via HTTP The following describes the general steps you take to code a service that sends a SOAP  message to a remote server via HTTP. 1 Compose a SOAP message in a soapData object. For information about composing SOAP  messages, see “Composing a SOAP Message” on page 50. 2 Send the SOAP message to the server using pub.client:soapHTTP. This service takes the  SOAP message from the soapData object produced by step 1 and posts it to the URL  that you specify.  Note that the soapHTTP service expects to find the SOAP message in an object named  soapRequestData. If you are building a flow service, you will need to use the Pipeline  tab to map the soapData produced in step 1 to soapRequestData.) Besides the soapData object from step 1, you must provide the following parameters to  soapHTTP: Name Description address A string specifying the HTTP address to which you want the  message posted. Example: http://servername:5555/soap/rpc auth A document (an IData object) specifying the user name and  password that the service will submit to the target server: Name Description type A string specifying the type of authentication that the  service will perform. Set type to basic. user A string specifying the user name that this service  will use to access a protected resource. password A string specifying the password that this service  will use to access a protected resource.
  • 57. SOAP Developer’s Guide Version 7.1.1 57 5 Composing and Sending SOAP Messages You may also provide the following optional parameters: Name Description validateSoap A string indicating whether or not you want the request and  response envelope to be validated against the SOAP schema. Set to... To... true Validate the SOAP envelope generated by  soapHTTP and the one received by soapHTTP.  When validateSoap is true, the service will  throw an exception if the request or  response does not conform to the SOAP  schema. false Bypass the validation process. SOAPAction A string specifying the value of the SOAPAction HTTP header. Note: The SOAPAction header was required by the initial SOAP  specification, but has since been deprecated. The Integration  Server does not use the SOAPAction header and accepts SOAP  messages that omit it. If you are designing a completely new solution, we recommend  that you avoid using the SOAPAction header. However, if you  exchange SOAP messages with systems that require a SOAPAction  header, this parameter allows you to set it.  Important! If you are designing a Web service descriptor with  multiple binders that contain the same operation name,   Developer cannot calculate a unique QName from the first  element in the SOAP body in order to identify the correct  operation. In that case, you must specify a unique SOAPAction  parameter for every request, as described in the “Modifying the  SOAP Action for an Operation” section of the Web Services  Developer’s Guide.  contentType  A string specifying the value of Content‐Type in the HTTP  header.  Set to... To... text/xml; charset=”utf-8” Default. Specify the content type as XML  and the character encoding of the message  text as UTF‐8.  text/xml Specify the content type as XML. Since the  charset parameter is not specified, the  character encoding of the message text  defaults to US‐ASCII.
  • 58. 5 Composing and Sending SOAP Messages 58 SOAP Developer’s Guide Version 7.1.1 3 Use the data-retrieval services to fetch information from the response message. If the server  returns a SOAP message, soapHTTP returns the message in a SOAP object called  soapResponseData. To retrieve the data in soapResponseData, you use any of the  following data‐retrieval services. The data‐retrieval services return an XML node (or an array of XML nodes) as output.  To extract information from an XML node, you can query it with the  timeout Optional. Time (in milliseconds) to wait for a response from the  server hosting the remote procedure before timing out and  terminating the request. The default value is to wait forever.  loadAs Optional. Specifies the format of the soapResponseData. Default is  stream for HTTP and byteArrayStream for HTTPS. Set to... To... stream Return the response body as a  java.io.InputStream object. Use this option  to invoke an HTTP Web service. bytes Return the response body as a byte array.  Use this setting if the message body will be  used as input to a service that operates on  entire HTML or XML documents. byteArrayStream Read the response stream fully and convert  to a java.io.ByteArrayStream object. This  setting prevents data loss or a truncated  SOAP response if the connection closes  prematurely. Use this service... To... pub.soap.utils:getBody Retrieve the body as a single XML node.  pub.soap.utils:getBodyEntries Retrieve the contents of the body as an array of XML  nodes, where each element in the array represents a  single body entry. pub.soap.utils:getDocument Retrieve the SOAP envelope as an XML node. pub.soap.utils:getHeader Retrieve the header as a single XML node.  pub.soap.utils:getHeaderEntries Retrieve the contents of the header as an array of  XML nodes, where each element in the array  represents a single header entry. pub.soap.utils:getTrailers Retrieve the trailers as an array of XML nodes, where  each element in the array represents a single trailer. Name Description
  • 59. SOAP Developer’s Guide Version 7.1.1 59 5 Composing and Sending SOAP Messages pub.xml:queryXMLNode service. See Step 2 in the sample flow shown on page 60 for an  example of how to do this. The soapHTTP service also returns a status parameter, which you can use to test the  results before processing them. For an example of how to test these values, see Step 2 in the following example. Example—Sending a SOAP Message The following flow service composes a SOAP message and then sends it to a SOAP  processor at http://localhost:5555/soap/inbox.  If you want to execute this example from Developer, you must first execute  sample.soap:registerCustomProcessor to register the customProc_msgQueue service with the  SOAP message handler (it will be registered under the inbox process directive). If you are  not running the Integration Server on your local machine, modify the URL in the address  parameter in Step 1 to point to the machine where your server is running. This example will prompt you for a user name and password when you execute it. To run  this sample successfully, you must provide a user name and password that belongs to the  Developers ACL on your Integration Server. Output Parameter Description soapStatus A string indicating whether the SOAP request message was  processed successfully, where: A value of... Indicates that... 0 The remote server successfully processed the  SOAP request message and returned a SOAP  response message. 1 The remote server returned a SOAP fault,  indicating that the SOAP request message was  received, but was not processed successfully. 2 The server returned an error that was not a SOAP  fault. This indicates that some type of HTTP error  occurred (often, an HTTP 404). You can check the  status element in header to determine what type of  HTTP error occurred. Note: The following example is broken into two parts. The first part illustrates how to  compose a SOAP message. This part is explained in “Composing a SOAP Message”  on page 50. The second part illustrates how to send the SOAP message. This part is  explained below.
  • 60. 5 Composing and Sending SOAP Messages 60 SOAP Developer’s Guide Version 7.1.1 Sending a SOAP message and processing the response # Description Step 1 Submit SOAP message to server via HTTP. This step sends the SOAP message to  the SOAP processor registered under the name inbox. Note that the soapData  object created in Part 1 is mapped to the soapRequestData that this step takes as  input. This step also sets the following input values: Name Description address This parameter is set to: http://localhost:5555/soap/inbox This URL assumes that the Integration Server is running on  your local machine and is listening for HTTP requests on  port 5555. If your server is running on a different machine  or port, modify the host name and port portions of this  URL. auth This document specifies the user name and password that  this service will use to connect to the Integration Server.  These values are mapped from the userName and password  parameters that this service takes as input. (When you  execute this service from Developer, you are prompted for  these values.) This example submits its message to the  customProc_MsgQueue processor, which is controlled by  the Developers ACL. To submit a message to this processor,  you must provide a user name and password that belongs  to the Developers ACL.
  • 61. SOAP Developer’s Guide Version 7.1.1 61 5 Composing and Sending SOAP Messages Step 2 Process response from server. This sequence processes the results from Step 1. To  determine whether the request was processed successfully, it checks the state  of the soapStatus variable: If soapStatus is... The service... 2 Composes an error message and throws an exception. A  value of 2 indicates that an HTTP failure occurred. 1 Extracts error information from the returned message and  throws an exception. A value of 1 indicates that the remote  server returned a SOAP fault. 0 Processes the contents of soapResponseData. A value of 0  indicates that the remote server received and successfully  processed the SOAP message. Step 3 FOR DEBUG ONLY. This step converts the contents of soapResponseData to a  String using soapDataToString. This allows you to examine the SOAP response  message with Developer, which is useful during testing and debugging. You  would not include it in a production service. If you examine the contents of string on the Results panel, you will see a SOAP  message similar to the following: # Description
  • 62. 5 Composing and Sending SOAP Messages 62 SOAP Developer’s Guide Version 7.1.1
  • 63. SOAP Developer’s Guide Version 7.1.1 63 6 Using the SOAP RPC Client Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Using pub.client:soapRPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 The Message Coder and the RPC Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
  • 64. 6 Using the SOAP RPC Client 64 SOAP Developer’s Guide Version 7.1.1 Overview The SOAP RPC client (pub.client:soapRPC) allows you to call procedures on remote, SOAP‐ enabled servers. To use the SOAP RPC client successfully, you need to have the following information  about the procedure that you are calling: The HTTP address of the server on which it resides. The credentials (user name and password), if any, that are required to access it. The qualified name (QName) associated with the procedure. The names and data types of the parameters that the procedure expects as input and  returns as output. Using pub.client:soapRPC The following describes the general steps you take to submit a SOAP remote procedure  call from the webMethods Integration Server. 1 Invoke pub.client:soapRPC with the following input parameters: Input Parameter Description address A string specifying the HTTP address of the server on which  the remote procedure resides. (If you are submitting the  request to a webMethods Integration Server, be sure to direct  it to the RPC processor as shown in the following example.) Example: http://rubicon:5555/soap/rpc reqParms A document (an IData object) whose elements represent the  input parameters that are to be passed to the remote  procedure.  For example, if you were to pass three string parameters, acct,  amt, and org, containing the values, Cash, 150.00 and Sales,  reqParms would contain the following: Key Value acct Cash amt 150.00 org Sales At run time, the values in reqParms are XML‐encoded by the  message coder. For a description of this process, see  “Encoding the Input Parameters for the Remote Procedure  Call” on page 71.
  • 65. SOAP Developer’s Guide Version 7.1.1 65 6 Using the SOAP RPC Client method A document (an IData object) specifying the QName of the  requested procedure, where: Key Description namespaceName A string specifying the namespace  portion of the procedure’s QName. localName A string specifying the local portion of  the procedure’s QName. auth A document (an IData object) specifying the user name and  password that are to be submitted to the server specified in  address, where: Key Description type A string specifying the type of  authentication that the server uses. Set  type to basic. user A string specifying the user name that is  to be presented to the server. pass A string specifying the password for the  user name specified in user. targetInputSignature Optional. A string specifying the fully qualified name of the  document type that is to be used to validate and encode the  contents of reqParms. For a description of how the message  coder uses targetInputSignature, see “Encoding the Input  Parameters for the Remote Procedure Call” on page 71. targetOutputSignature Optional. A string specifying the fully qualified name of the  document type that is to be used to validate and decode the  output value returned by the remote procedure. For a  description of how the message coder uses  targetInputSignature, see “Decoding the Output Parameters  from a Remote Procedure Call” on page 73. Input Parameter Description
  • 66. 6 Using the SOAP RPC Client 66 SOAP Developer’s Guide Version 7.1.1 SOAPAction Optional. A String specifying the value to which you want  the SOAPAction HTTP header set. Note: The SOAPAction header was required by the initial SOAP  specification, but has since been deprecated. The Integration  Server does not use the SOAPAction header and accepts SOAP  messages that omit it. If you are designing a completely new solution, we  recommend that you avoid using the SOAPAction header.  However, if you exchange SOAP messages with systems that  require a SOAPAction header, this parameter allows you to set  it.  Important! If you are designing a Web service descriptor with  multiple binders that contain the same operation name,   Developer cannot calculate a unique QName from the first  element in the SOAP body in order to identify the correct  operation. In that case, you must specify a unique  SOAPAction parameter for every request, as described in the  “Modifying the SOAP Action for an Operation” section of the  Web Services Developer’s Guide.  contentType   Optional. A string that specifies the value of Content‐Type in  the HTTP header. Set to... To... text/xml; charset=”utf-8” Default. Specify the content type as  XML and the character encoding of the  text as UTF‐8.  text/xml Specify the content type as XML. Since  the charset parameter is not specified,  the character encoding of the text  defaults to US‐ASCII.  encoding Optional. Specifies the encoding method. Default value is  UTF‐8.  loadAs Optional. Specifies the format of the soapResponseData.  Default value is stream for an HTTP service and  byteArrayStream for an HTTPS service.  Set to... To... stream Return the response body as a  java.io.InputStream object. Use this  option to invoke an HTTP Web service. Input Parameter Description
  • 67. SOAP Developer’s Guide Version 7.1.1 67 6 Using the SOAP RPC Client 2 Process the results returned by pub.client:soapRPC. If the remote procedure returns  output values, those values are decoded by the message coder and placed in an IData  object called respParms. For example, if the procedure returned two string parameters,  status and balance, whose values were closed and –4.95, respParms would contain the  following:  When decoding the results, the message coder uses the document type named in  targetOutputSignature (if one was specified) to validate the values in respParms. For a  description of the decoding process, see “Decoding the Output Parameters from a  Remote Procedure Call” on page 73. Besides respParms, pub.client:soapRPC returns the following values, which you can use  to determine whether the request was processed successfully: byteArrayStream Read the response stream fully and  convert to a java.io.ByteArrayStream  object. This setting prevents data loss or  a truncated SOAP response if the  connection closes prematurely. Use this  setting to invoke an HTTPS Web  service. timeout Optional. Time (in milliseconds) to wait for a response from  the server hosting the remote procedure before timing out  and terminating the request. The default value is to wait  forever. Key Value status closed balance -4.95 Output Parameter Description soapStatus A String indicating whether the remote procedure call was  processed successfully, where: A value of... Indicates that... 0 The remote server successfully returned the  results of the remote procedure call. 1 The remote server returned a SOAP fault,  indicating that the remote procedure call was  received, but was not processed successfully. Input Parameter Description
  • 68. 6 Using the SOAP RPC Client 68 SOAP Developer’s Guide Version 7.1.1 Example—Submitting a Remote Procedure Call The following flow service calls a remote procedure that takes three String parameters  (acct, amt, and loc) and returns one String parameter (authCode).  This example is located in sample.soap:buildRPC_SendHTTPSimple. You may want to examine  it with webMethods Developer to understand how its parameters are set.  The service calls a remote procedure whose QName is made up of the namespace name,  http://www.expt.com/AUTH/, and local name, getAuthCode. On a webMethods Integration  Server (version 4.6 or later) this name is registered to sample.soap:targetSvc_rpcProcSimple.  (This service resides in the WmSamples package and is described in “Example—Target  Service for the RPC Processor” on page 120. You can find this package in the certified  samples area of the Knowledge Base on the Advantage Web Site.) To execute this example from Developer, modify the URL in the address parameter in  Step 1 to point to the machine where your Integration Server is running.  2 The server returned an error that was not a  SOAP fault. This indicates that some type of  HTTP error occurred (often, an HTTP 404). You  can check the status element in header (below) to  determine what type of HTTP error occurred. header A document (an IData object) containing information from the  HTTP header returned by the remote server. header contains the  following elements: Key Value lines A document (an IData object) in which each  entry represents a field (line) of the response  header. Key names represent the names of the  header fields and key values are Strings  containing the values of the header fields. status A String containing the status code from the  HTTP response. For example, if the server  returns a HTTP 404 error, status will contain 404. statusMessage A String containing the status message from the  HTTP response. soapResponseData A SOAP object containing the entire SOAP response message.  You can extract data from this object using the data‐retrieval  services such as getBody and getHeaderEntries. (For a complete list  of data‐retrieval services, see page 58.) Output Parameter Description
  • 69. SOAP Developer’s Guide Version 7.1.1 69 6 Using the SOAP RPC Client When you execute this example, you will be prompted for the following values: Example of a service that submits a remote procedure call and processes the response For this input parameter... Enter... acct Any string of characters. amt A decimal value, such as 150.75 or 15.00. (Omit commas from  large values; otherwise, the value will fail validation.) loc Any string of characters. userName A user name that belongs to the Developers ACL. password The password for the user name that you entered in  userName. # Description Step 1 Submit remote procedure call. This step composes the remote procedure call and  submits it to the server specified in address. If you examine the pipeline, you will  see that its input parameters are set as follows: Name Description address This parameter is set to: http://localhost:5555/soap/rpc This directs the request to the RPC processor on a  webMethods Integration Server. This URL assumes that  the Integration Server is running on your local machine  and is listening for HTTP requests on port 5555. If your  server is running on a different machine or port, modify  the host name and port portions of this URL.
  • 70. 6 Using the SOAP RPC Client 70 SOAP Developer’s Guide Version 7.1.1 auth This document specifies the user name and password  that this service will use to connect to the webMethods  Integration Server. These values are mapped from the  userName and password parameters that this service  takes as input. (When you execute this service from  webMethods Developer, you are prompted for these  values.) Note: When you submit a SOAP remote procedure call  to an Integration Server, your credentials are verified  against the ACL for the target service. method This document specifies the QName of the remote  procedure. In this example, method is set as follows: Key Value namespaceName http://www.expt.com/AUTH/ localName getAuthCode On the webMethods Integration Server, this QName  represents the universal name assigned to the service  sample.soap:targetSvc_rpcProcSimple. reqParms This document contains the input parameters that are to  be passed to the remote procedure. Note that  authCodeReq, a document that is part of the input  signature for this example, is mapped to reqParms. targetInputSignature This parameter is set to: sample.soap.helpers.docTypes:docType_authCodeReq which is the name of a document type. This parameter  tells the message coder to validate the contents of  reqParms (the input parameters for the remote  procedure) against this document type at run time. It  also instructs the message coder to encode the contents  of reqParms according to the data types specified in this  document type. # Description
  • 71. SOAP Developer’s Guide Version 7.1.1 71 6 Using the SOAP RPC Client The Message Coder and the RPC Client The SOAP RPC client engages the message coder to convert the input and output  parameters to and from XML. Encoding the Input Parameters for the Remote Procedure Call At run time, the parameters in reqParms are converted to XML by the message coder. This  process is known as encoding. The way in which the message coder encodes the  parameters in reqParms depends on whether targetInputSignature is set. If targetInputSignature is not set, the message coder encodes the elements in reqParms  according to their underlying Java classes. For example, if a parameter were of class  java.lang.Boolean, the message coder would encode it as xsi:type="xsd:boolean" in the  resulting XML. If the message coder does not recognize the underlying class, it  encodes the parameter as a string (it uses the object’s toString( ) method to produce  the parameter’s value). targetOutputSignature This parameter is set to: sample.soap.helpers.docTypes:docType_authCodeResp which is the name of a document type. This parameter  tells the message coder to validate the contents of  respParms (the results from the remote procedure)  against this document type at run time. It also instructs  the message coder to decode the contents of respParms  according to the data types specified in this document  type. Step 2 Process response from server. This sequence processes the results from Step 1. To determine whether the request was processed successfully, this step first  checks the state of the soapStatus parameter: If soapStatus is... The service... 2 Composes an error message and throws an exception. A  value of 2 indicates that an HTTP failure occurred. 1 Extracts error information from the returned message  and throws an exception. A value of 1 indicates that the  remote server returned a SOAP fault. 0 Processes the contents of respParms. A value of 0  indicates that the remote server returned the results of  the requested procedure. # Description
  • 72. 6 Using the SOAP RPC Client 72 SOAP Developer’s Guide Version 7.1.1 The following table shows how the message coder would encode a parameter amt  (with a value of 500.00) depending on its Java class. For a list of recognized Java classes and the XML data types to which they are  converted, see Appendix B, “Encoding/Decoding Data‐Type Mapping”. If targetInputSignature is set, the message coder first validates the contents of reqParms  against the document type specified in targetInputSignature. If the parameters in  reqParms violate the specified document type, (for example, if a required parameter is  missing or a value is not of the correct type), the message coder throws an exception. If the parameters are valid, the message coder encodes them as follows: If the parameter is a String, the value of the parameter is encoded according to its  Content type property. For example, if its Content type is nonNegativeInteger  {http://www.w3.org/2001/XMLSchema}, the value is encoded as an  xsi:type="xsd:nonNegativeInteger". If the Content type property is not specified,  the message coder encodes the value as a string (as though its Content type were  string {http://www.w3.org/2001/XMLSchema}). The following table shows how the message coder would encode a String  parameter amt (with a value of 500.00) for different Content Type values. If the parameter is an Object, the value of the parameter is encoded according to its  underlying Java class.  Encoding Complex Structures and Arrays The message coder encodes documents (IData objects) as complex data types.  The message coder encodes Document Lists, String Lists, and Object Lists as SOAP  arrays. For more information about how the arrays are encoded in SOAP messages, see  the “Arrays” section in the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May  2000 at http://www.w3.org/TR/SOAP/#_Toc478383522. 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> 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>
  • 73. SOAP Developer’s Guide Version 7.1.1 73 6 Using the SOAP RPC Client Encoding Multi-Referenced Elements By default, the message coder generates references when encoding parameters that  reference the same underlying data in the pipeline. However, this behavior can be  modified with the watt.server.SOAP.useMultiReference parameter. When watt.server.SOAP.useMultiReference is true, the message coder generates the  appropriate id and href attributes for parameters that reference the same underlying data.  For example, if the parameters cDate and oDate refer to the same object, the message  coder encodes them like this if watt.server.SOAP.useMultiReference=true (or is not set,  which is the server’s installed behavior): And encodes them like this if watt.server.SOAP.useMultiReference=false: For more information about watt.server.SOAP.useMultiReference and other SOAP‐ related server parameters, see Appendix C, “SOAP‐Related Server Parameters”. For more  information about setting server parameters, see the webMethods Integration Server  Administrator’s Guide. Decoding the Output Parameters from a Remote Procedure Call When the results of a remote procedure call are returned to the SOAP RPC client, the  message coder converts them from XML and places them, as Java Objects, in respParms.  This process is known as decoding. The way in which the message coder decodes the results depends on whether  targetOutputSignature is set. If targetOutputSignature is not set, the output parameters are rendered according to  the data types declared in the XML. For example, it would convert a parameter whose  data type is xsi:type=xsd:decimal to a Java object of class java.math.BigDecimal. (For a  list of XML data types and the Java classes to which they are converted, see  . . . <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 . . . <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
  • 74. 6 Using the SOAP RPC Client 74 SOAP Developer’s Guide Version 7.1.1 Appendix B, “Encoding/Decoding Data‐Type Mapping”.) If an XML element does  not declare its type, the parameter is rendered as a String. If targetOutputSignature is set, the message coder converts the output parameters  according to the document type specified in targetOutputSignature.  If targetOutputSignature declares a parameter as a String, the value is rendered as a  String object, regardless of the data type declared in the XML. If targetOutputSignature declares a parameter as an Object, the value is rendered  according to the data type declared in the XML. When targetOutputSignature is specified, the message coder also validates the contents  of respParms. If the parameters returned in respParms violate the document type  specified in targetOutputSignature, (for example, if a required parameter is missing or  a value is not of the correct type), the message coder throws an exception. Decoding Complex Structures and Arrays For complex data types (XML elements that contain child elements), the message coder  produces documents (IData objects) in the pipeline. The message coder will create arrays of elements (that is, String Lists, Document Lists,  Object lists) for elements that are properly encoded as SOAP arrays. For more  information about how the arrays are encoded in a SOAP message, see the “Arrays”  section in the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at  http://www.w3.org/TR/SOAP/#_Toc478383522. Decoding Multi-Referenced Parameters The message coder can resolve parameters that are referenced through the href attribute  as long as the referenced value appears within the body of the SOAP message. The  message coder cannot resolve external references (references that point to resources  outside of the message) or references that point to elements outside the Body element. Within the Body element, the href attribute may appear before or after the value that it  references. The message coder can successfully resolve either type. 
  • 75. SOAP Developer’s Guide Version 7.1.1 75 6 Using the SOAP RPC Client For referenced elements, the message coder puts a single copy of the value in the pipeline  and generates references to it. Note: If the message coder cannot resolve a reference, it generates a null object for that  parameter. It also reports the problem in the server log if the server is running at  debug level 5 or higher. . . . <cDate id="id1">03/15/2000</cDate> <amt id="id2">300</amt> <oDate href="#id1"></oDate> . . . . . . <oDate href="#id1"></oDate> <amt id="id2">300</amt? <cDate id="id1">03/15/2000</cDate> . . . In a backward reference, a referenced value appears before the point where it is referenced In a forward reference, a referenced value appears after the point where it is referenced
  • 76. 6 Using the SOAP RPC Client 76 SOAP Developer’s Guide Version 7.1.1
  • 77. SOAP Developer’s Guide Version 7.1.1 77 A SOAP Faults Returned by the Integration Server Basic Structure of a SOAP Fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 webMethods SOAP Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
  • 78. A SOAP Faults Returned by the Integration Server 78 SOAP Developer’s Guide Version 7.1.1 Basic Structure of a SOAP Fault If the Integration Server is not able to process a SOAP message, it returns a SOAP fault. A  SOAP fault is a SOAP message with the following structure. Elements of a SOAP Fault The body of a SOAP fault contains the Fault element. When the Integration Server returns  a SOAP fault, it contains the following children: Element Value <faultcode> A QName indicating the class of error that occurred. The namespace  for the QName will be the same as that of the SOAP envelope and the  local name will be one of the following: Local Name Indicates that... Server The Integration Server was not able to  process the message because of a problem  on the server. Client The Integration Server was not able to  process the message because it was  formatted improperly.     —OR— Integration Server was not able to process  the message because the SOAP processor  (or one of the services it called) threw an  exception.  MustUnderstand The SOAP processor could not obey a  header element whose mustUnderstand  attribute was set to 1. <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>…</faultcode> <faultstring>…</faultstring> <faultactor>…</faultactor> <detail>…</detail> </SOAP-ENV:Fault> </SOAP-ENV:Body> The body contains the Fault element, which contains information about the failure
  • 79. SOAP Developer’s Guide Version 7.1.1 79 A SOAP Faults Returned by the Integration Server VersionMismatch The Integration Server does not support the  SOAP namespace specified in the SOAP  envelope. <faultstring> A message describing the error. For a list of messages that might  appear in faultstring, see “webMethods SOAP Faults” on page 81. <faultactor> A URI indicating which SOAP processor returned the error.  Example: http://rubicon:5555/soap/rpc <detail> An element containing detailed information about the error. The  Integration Server returns this element when an exception occurs  while it is processing the message.  The <detail> element returned by the Integration Server is from the  following namespace: http://www.webmethods.com/2001/10/soap It contains an element called <exception>, which has the following  children and provides specific information about the exception: Element Description <classname> The name of the Java class that was thrown. <message> The detailed error message from the  exception. <stackTrace> A Java stack trace.  Important! This element is included only if  the client is a member of the Developers or  Administrators group on the webMethods  Integration Server. <serviceStackTrace> A service stack trace. This element is  returned if a service stack is available to the  SOAP message handler. It generally  appears only when an exception is thrown  by one of the webMethods SOAP  processors or utilities. Important! This element is included only if  the client is a member of the Developers or  Administrators group on the webMethods  Integration Server. Element Value
  • 80. A SOAP Faults Returned by the Integration Server 80 SOAP Developer’s Guide Version 7.1.1 Example—Unknown SOAP Processor The following is an example of the SOAP fault that the Integration Server returns when a  client directs a message to a processor that does not exist on the server. <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Server</faultcode> <faultstring> [ISS.0088.9123] Requested SOAP processor inbox is not registered on this server </faultstring> <faultactor>http://localhost:5555/soap/inbox</faultactor> </SOAP-ENV:Fault> </SOAP-ENV:Body> Note that this fault does not include the <detail> element. Example—Exception While Processing Message The following is an example of the SOAP fault that the Integration Server returns if an  exception is thrown while it is processing a SOAP message. Note that this fault includes  the detail element, which provides information about the exception. <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Server</faultcode> <faultstring> [ISS.0088.9112] An Exception was thrown in the server </faultstring> <faultactor>http://localhost:5555/soap/inbox</faultactor> <detail xmlns="http://www.webmethods.com/2001/10/soap"> <exception> <className>com.wm.lang.flow.FlowException</className> <message xml:lang="en-US"> [ISC.0049.9010] Failure invoking unknown service at 'unlabeledINVOKE'. The service may have been renamed, moved or disabled. </message> <stackTrace xml:lang="en-US"> com.wm.lang.flow.FlowException: [ISC.0049.9010] Failure invoking unknown service at 'unlabeledINVOKE'. The service may have been renamed, moved or disabled.at java.lang.Throwable.&lt;init&gt;(Throwable.java:84)at java.lang.Exception.&lt;init&gt;(Exception.java:35)at com.wm.util.LocalizedException.&lt;init&gt;(LocalizedException.java:83)at com.wm.lang.flow.FlowException.&lt;init&gt;(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
  • 81. SOAP Developer’s Guide Version 7.1.1 81 A SOAP Faults Returned by the Integration Server 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> </SOAP-ENV:Envelope> webMethods SOAP Faults The following are SOAP‐related errors that are issued by the webMethods Integration  Server. [ISC.0076.0013] SOAP Message Coder cannot encode output data; pipeline does not match output signature. Cause: The SOAP message coder could not XML‐encode the results of a SOAP remote  procedure call because a variable appeared in the pipeline more than once. Response: On the Integration Server, examine the target service to determine why it is not  producing output values that match the output signature. Correct the serviceʹs signature  and/or logic after identifying the source of the problem. [ISC.0076.0014] SOAP Message Coder failure; a Runtime Exception was thrown in the SOAP Coder Cause: The message coder encountered a serious internal error. Response: Contact Software AG Customer Care. [ISC.0076.0015] SOAP Message Coder cannot encode variable varName; variable does not have a valid XML name Cause: The message coder could not XML‐encode the SOAP RPC request or response  because the pipeline contained the variable varName, whose name is not a valid name for  an XML element. Response: This error often occurs because the variable name contains a colon. Change the  name of varName to one that is also valid as an XML element name (or map varName to a  new variable, and use that variable as your SOAP RPC input or output parameter).
  • 82. A SOAP Faults Returned by the Integration Server 82 SOAP Developer’s Guide Version 7.1.1 [ISC.0076.0016] Soap Message Coder warning; unregistered coder for variable varName, using String Cause: The message coder was not able to recognize the data type for varName so it  treated the variable as a String. Response: Check the incoming XML and verify that it declares the correct data type. [ISC.0076.0017] SOAP Message Coder error; no coder is registered for encoding style styleName Cause: The message coder encountered a serious internal error. Response: Contact Software AG Customer Care. [ISC.0076.0018] Soap Message Coder warning; unregistered coder for variable varName, using BasicData Cause: The message coder was not able to recognize the complex data type for varName so  it treated the variable as a document (an IData object). Response: Check the incoming XML and verify that it declares the correct data type. [ISC.0076.0019] SOAP Message Coder cannot decode message; encoding style styleName is not a registered style Cause: The message coder could not decode the submitted XML because it does not  support the specified encoding style. Response: Check the incoming XML and verify that the encodingStyle attribute is  specified correctly and that it specifies a style that the Integration Server supports. [ISC.0076.0020] Soap Message Coder warning; invalid HREF found reference Cause: The message coder could not resolve the href pointing to reference. A null value  was produced instead. Response: Examine the incoming XML and make sure that the specified reference points  to an element that exists in the body of the message. Note: This message is a warning that is written to the server log at debug level 5 and  higher. Note: This message is a warning that is written to the server log at debug level 5 and  higher. Note: This message is a warning that is written to the server log at debug level 5 and  higher.
  • 83. SOAP Developer’s Guide Version 7.1.1 83 A SOAP Faults Returned by the Integration Server [ISC.0076.0021] SOAP Message Coder cannot decode message; arrayType attribute value attValue is malformed Cause: The message coder could not decode an XML‐encoded array because it cannot  understand the value of the arrayType attribute. Response: Check the incoming XML and make sure that the arrayType attribute is specified  correctly. For example, make sure that it is not missing a [ symbol. [ISC.0076.0022] SOAP Message Coder cannot decode message; cannot determine type of element elementName Cause: The message coder could not decode the XML‐encoded parameters it has received,  because the simple element elementName has an unknown data type (for example,  xsi:type="myDataType").  Response: Check the incoming XML and make sure the data type has been specified  correctly. Also make sure that it is using the correct namespace. [ISC.0076.0023] SOAP Message Coder cannot decode message; unable to create array for arrayType attribute value attValue Cause: The message coder could not decode an XML‐encoded array because it could not  allocate an array of the specified dimensions. Response: Check the incoming XML and make sure that the arrayType attribute is specified  correctly. For example, make sure that it does not specify a negative dimension or an  invalid array size (for example, too many dimensions or dimensions that are  unrealistically large). If the array is unusually large or the server is extremely very low on  memory, the possibility also exists that this error was the result of an out‐of‐memory  condition. [ISC.0076.9101] SOAP Encoding Registrar cannot register encoding style styleName; encoding style already exists Cause: The encoding registrar encountered a serious internal error. Response: Contact Software AG Customer Care. [ISC.0076.9102] SOAP Encoding Registrar cannot register Java type typeName; Java type already exists Cause: The encoding registrar encountered a serious internal error. Response: Contact Software AG Customer Care. [ISC.0076.9103] SOAP Encoding Registrar cannot register Schema type typeName; Schema type already exists Cause: The message code encountered a serious internal error. Response: Contact Software AG Customer Care.
  • 84. A SOAP Faults Returned by the Integration Server 84 SOAP Developer’s Guide Version 7.1.1 [ISC.0076.9201] Null mime object received Cause: The message coder could not decode the parameters in the SOAP message because  the message does not specify an encoding style. Response: This error usually occurs because the SOAP encodingStyle attribute is missing,  misplaced or misspelled. Examine the RPC request that was submitted to the Integration  Server and ensure that the SOAP Envelope includes the encodingStyle attribute. Also check  that the encodingStyle attribute has the proper syntax and namespace. [ISC.0076.9202] No data in buffer! Cause: The message coder encountered a serious internal error. Response: Contact Software AG Customer Care. [ISC.0076.9203] SOAP Message Coder cannot decode message; Invalid number value Cause: The message coder could not decode an XML‐encoded array because one of its  dimensions is set to a nonnumeric value. Response: Check the incoming XML and make sure that the arrayType attribute specifies a  positive integer. For example, make sure it has not been inadvertently set to a  nonnumeric value such as “A”. [ISC.0076.9204] SOAP Message Coder cannot encode output data; pipeline does not match output signature, duplicate variable varName in pipeline Cause: The message coder could not XML‐encode the results of a SOAP remote procedure  call because the variable varName appeared in the pipeline more than once. Response: On the Integration Server, examine the target service to determine why it is not  producing output values that match the output signature for varName. Correct the  service’s signature and/or logic after identifying the source of the problem. [ISC.0076.9205] SOAP Message Coder cannot encode variable varName; variable does not have a valid XML name Cause: The message coder could not XML‐encode the SOAP RPC request or response  because the pipeline contained the variable varName, whose name is not a valid name for  an XML element. Response: This error often occurs because the variable name contains a colon (:). Change  the name of varName to one that is also valid as an XML element name (or map varName  to a new variable, and use that variable as your SOAP RPC input or output parameter). [ISC.0076.9206] SOAP Message Coder error; no coder is registered for encoding style styleName Cause: The message coder encountered a serious internal error. Response: Contact Software AG Customer Care.
  • 85. SOAP Developer’s Guide Version 7.1.1 85 A SOAP Faults Returned by the Integration Server [ISC.0076.9208] SOAP Message Coder cannot decode message; cannot determine type of element elementName Cause: The message coder could not decode the XML‐encoded parameters it has received,  because the simple element elementName has an unknown data type (for example,  xsi:type="myDataType"). Response: Check the incoming XML and make sure the data type has been specified  correctly. Also make sure that it is using the correct namespace. [ISC.0076.9209] SOAP Message Coder cannot decode message; unable to create array for arrayType attribute value attValue Cause: The message coder could not decode an XML‐encoded array because it could not  allocate an array of the specified dimensions. Response: Check the incoming XML and make sure that the arrayType attribute is specified  correctly. For example, make sure that it does not specify a negative dimension or an  invalid array size (e.g., too many dimensions or dimensions that are unrealistically large).  If the array is unusually large or the server is extremely very low on memory, the  possibility also exists that this error was the result of an out‐of‐memory condition. [ISC.0076.9210] SOAP Message Coder cannot decode message; arrayType attribute value attValue is malformed Cause: The message coder could not decode an XML‐encoded array because it cannot  understand the value of the arrayType attribute. Response: Check the incoming XML and make sure that the arrayType attribute is using the  correct syntax. For example, make sure that it is not missing a “[” symbol. [ISC.0076.9211] SOAP Message Coder cannot encode output data; pipeline does not match output signature, required variable varName is missing Cause: The message coder could not transform the results of a SOAP remote procedure  call because the required variable varName was not in the pipeline. Response: On the Integration Server, examine the target service to determine why it is not  producing the required output variables. Correct the service’s signature and/or logic after  identifying the source of the problem. [ISC.0076.9212] SOAP Message Coder cannot encode output data; pipeline does not match output signature, extra variable varName in pipeline Cause: The message coder encountered a serious internal error. Response: Contact Software AG Customer Care.
  • 86. A SOAP Faults Returned by the Integration Server 86 SOAP Developer’s Guide Version 7.1.1 [ISS.0088.9102] ASSERTION: The directive directiveName in the URL urlName should be directiveName Cause: The SOAP message handler encountered a serious internal error. Response: Contact Software AG Customer Care. [ISS.0088.9103] Error reading SOAP Message from HTTP stream -- appears to be empty Cause: The SOAP message handler encountered a serious internal error. Response: Contact Software AG Customer Care. [ISS.0088.9105] Failed to register SOAP Handler directiveName Cause: The Integration Server was not able to successfully add the specified SOAP  processor to the processor registry. Response: Verify that the SOAP processor directive and fully qualified service name have  been specified correctly. This error usually occurs because the directive name or the  service name has not been specified.  [ISS.0088.9107] Failed to unregister SOAP Handler directiveName Cause: The Integration Server was not able to successfully remove the specified processor  from the SOAP Processor registry. Response: This error generally occurs because the registry does not contain a processor  registered to the specified directive. Verify that the process directive was specified  correctly. (Remember that directive names are case‐sensitive.) Also verify that the  specified directive is currently registered in the SOAP Processor registry. It may have  already been removed. [ISS.0088.9108] SOAP Handler directiveName already registered Cause: The Integration Server was not able to successfully register the SOAP processor,  because the registry already has a processor registered under the specified directive. Response: Register the SOAP processor under a different directive. Or unregister the  processor that is currently registered to directiveName, and then register this SOAP  Processor. [ISS.0088.9109] SOAP is only supported using HTTP POST protocol Cause: The SOAP message handler was not able to accept the request because the SOAP  message was submitted to the Integration Server using the HTTP GET method. The  SOAP message handler only accepts requests via the POST method (per W3C  specification). Response: Modify the client to use HTTP POST to submit SOAP messages to the  Integration Server.
  • 87. SOAP Developer’s Guide Version 7.1.1 87 A SOAP Faults Returned by the Integration Server [ISS.0088.9110] Invalid BOOLEAN value value for variable varName; must be 0 or 1 Cause: The addHeaderEntry utility failed because the mustUnderstand attribute was not set  correctly. Response: Check the logic in the process that failed to make sure that it sets the value of  varName to either 0 or 1. No other values are permitted when setting the mustUnderstand  attribute. [ISS.0088.9111] Cannot load or execute the SOAP processor directiveName Cause: The SOAP message handler cannot process the SOAP message because the  requested SOAP processor is non‐operational. Response: On the server, check the status of the service that is registered to directiveName.  Make sure this service is loaded and operating successfully. (Frequently this error occurs  because the processor was modified and then did not recompile successfully.) [ISS.0088.9112] An Exception was thrown in the server Cause: The Integration Server, the SOAP processor, or one of the services processing the  message has thrown an exception. Response: See the detail element in the SOAP fault to determine the exception that was  thrown and which process it was thrown by. [ISS.0088.9113] The SOAP Envelope does not have a Body block Cause: The SOAP client was given a soapRequestData that did not contain a body element. Response: Examine the logic in the client to see whether it uses the stringToSoapData or  streamToSoapData service to generate their SOAP objects. If so, determine whether the  String or stream from which the SOAP object was generated represented a valid SOAP  message. Also check whether the SOAP processor or client used any of the data removal  utilities (such as removeHeaderEntry or removeBodyEntry) and might have inadvertently  removed the entire Body element. [ISS.0088.9114] Missing SOAP directive in the URL url Cause: The SOAP message handler encountered a serious internal error. Response: Contact Software AG Customer Care. [ISS.0088.9116] The server cannot execute the requested SOAP utility; required parameter paramName is missing or invalid Cause: The requested SOAP utility failed to execute because a required parameter was not  supplied. Response: Check the logic in the SOAP processor or client to make sure that it passes the  correct parameters to each SOAP utility service that it invokes.
  • 88. A SOAP Faults Returned by the Integration Server 88 SOAP Developer’s Guide Version 7.1.1 [ISS.0088.9117] One or more header entries were not understood by the SOAP processor Cause: The SOAP processor has rejected the SOAP message because it cannot obey a  mandatory header entry (a header entry whose mustUnderstand attribute is enabled). [ISS.0088.9118] Parameter paramName must be a valid soapData Cause: The requested SOAP utility failed to execute because parameter paramName is not  a SOAP object. Response: Examine the logic in the SOAP processor or client and make sure that it passes  a SOAP object in parameter paramName. [ISS.0088.9119] SOAP Processor did NOT return a valid SOAP Response Cause: The message handler did not receive a valid SOAP message from the SOAP  processor. Response: Examine the logic in the SOAP processor to make sure that it composes the  SOAP response message correctly. For example, check to see whether it the processor  uses the stringToSoapData or streamToSoapData services to generate soapResponseData. If so,  determine whether the original String or stream represents a valid SOAP message. If the  SOAP processor logic seems correct, contact Software AG Customer Care. This would  indicate a serious internal error. [ISS.0088.9120] Parameter paramName is not one of the valid data types: dataType Cause: The requested SOAP utility failed to execute because parameter paramName did  not have the correct data type. The type in dataType is the data type that is expected. Response: Examine the logic in the SOAP processor or client and make sure that it passes  to paramName an object of the data type specified in dataType. [ISS.0088.9122] Service serviceName does not exist Cause: The SOAP facility could not complete the requested operation because it could not  find the specified service. This error is issued by various SOAP processes (e.g., registering  a SOAP processor, invoking a SOAP processor, invoking a target service). Response: Examine the process that failed and make sure that it specifies the name of the  requested service correctly. For example, if you receive this error when registering a  SOAP processor, check that you have specified the svcName parameter correctly.  Remember that service names are case‐sensitive. [ISS.0088.9123] Requested SOAP processor directiveName is not registered on this server Cause: The Integration Server could not process the SOAP message because it does not  have the SOAP processor requested by the client. Response: On the client side, verify that the correct process directive is specified in the  URL (remember that the directive is case‐sensitive). If the client has specified the process 
  • 89. SOAP Developer’s Guide Version 7.1.1 89 A SOAP Faults Returned by the Integration Server directive correctly, then use pub.soap.processor:list to verify that the requested processor is  registered on the Integration Server.  [ISS.0088.9124] SOAP Message does not conform to the SOAP message model Cause: The SOAP message passed to the validateSoapData utility failed validation (for  example, it is missing the Body element or the Header element follows the body).  Response: Examine the logic that produced the message and see whether it uses the  stringToSoapData or streamToSoapData service to manually generate a SOAP object instead of  using the message composition services (e.g., createSoapData, addHeaderEntry, addBodyEntry).  If so, determine whether the String or stream from which the SOAP object is generated  represents a valid SOAP message.  Also check whether the SOAP processor or client used any of the data removal utilities  (such as removeHeaderEntry or removeBodyEntry) and might have inadvertently removed  required portions of the SOAP object (for example, the entire Body element). [ISS.0088.9125] SOAP request does not conform to the SOAP message model Cause: The SOAP message handler could not process the SOAP request because it violates  the SOAP message schema (for example, it is missing the Body element or the Header  element follows the body).  Response: On the client side, correct the logic that builds the message to ensure that it  produces a valid SOAP message. [ISS.0088.9126] SOAP response does not conform to the SOAP message model Cause: The SOAP message handler could not return the SOAP response generated by a  SOAP processor on the Integration Server because the message violates the SOAP  message schema.  Response: Examine the logic in the SOAP processor and see whether it uses the  stringToSoapData or streamToSoapData service to generate a SOAP object. If so, determine  whether the String or stream from which the SOAP object is generated represents a valid  SOAP message. Examine the logic that produced the message and see whether it uses the  stringToSoapData or streamToSoapData service to manually generate a SOAP object instead of  using the message composition services (e.g., createSoapData, addHeaderEntry, addBodyEntry).  If so, determine whether the String or stream from which the SOAP object is generated  represents a valid SOAP message. Also check whether the SOAP processor or client used  any of the data removal utilities (such as removeHeaderEntry or removeBodyEntry) and might  have inadvertently removed required portions of the SOAP object (for example, the  entire Body element). [ISS.0088.9127] The server could not load the SOAP XML Validator Cause: The SOAP message handler encountered a serious internal error. Response: Contact Software AG Customer Care.
  • 90. A SOAP Faults Returned by the Integration Server 90 SOAP Developer’s Guide Version 7.1.1 [ISS.0088.9128] Request is from namespace 'msgNamespace', server requires namespace 'svrNamespace' Cause: The SOAP message handler could not process the message because the message is  not from a version of SOAP that the Integration Server supports. The Integration Server  supports the version indicated in svrNamespace.  Response: From the client side, resubmit the message using a version of SOAP that the  Integration Server supports.  [ISS.0088.9129] Comparison requires an rvalue Cause: The requested SOAP utility (e.g., addHeaderEntry, addBodyEntry) failed to  execute because it received a node that does not represent an enclosed XML element. Response: This error can occur if the node is missing opening and closing tags (e.g., the  node contains ʺ hello ʺ instead of ʺ <a>hello</a> ʺ). Examine the process that called the  failing utility and make sure that it passes a valid node object to the SOAP utility. [ISS.0088.9130] Comparison righthand operand evaluates to more than one value Cause: The requested SOAP utility (e.g., addHeaderEntry, addBodyEntry) failed to  execute because it received a node that does not have a root element. Response: This error can occur if the node contains an XML fragment that represents  uncontained elements (e.g., the node contains ʺ <b>hello</b> <c>world</c> ʺ instead of ʺ  <a> <b>hello</b> <c>world</c> </a> ʺ). Examine the logic that called the failing utility  and make sure that it passes a node containing only one top‐level XML element. [ISS.0088.9131] Comparison operator is missing. Cause: The requested SOAP utility (e.g., addHeaderEntry, addBodyEntry) failed to  execute because it received a node that does not represent a well‐formed XML document. Response: This error can occur if the node contains overlapping or missing tags (e.g., a  node that contains ʺ <b>hello ʺ or ʺ <a> <b>hello <c>world</b></c> </a> ʺ). Examine the  logic that called the failing utility and make sure that it passes a node containing well‐ formed XML. [ISS.0088.9132] Failed to register SOAP Handler directiveName, illegal characters in directive name Cause: The Integration Server was not able to successfully register the SOAP processor,  because directiveName contains characters that are not allowed in a directive name. Response: Register the SOAP processor under a name that is composed only of letters,  digits, or the characters -_.!~*'( ).
  • 91. SOAP Developer’s Guide Version 7.1.1 91 A SOAP Faults Returned by the Integration Server [ISS.0088.9133] Error while encoding RPC output. Cause: The message coder could not XML‐encode the parameters associated with a SOAP  remote procedure call. Response: See the detail element in the SOAP fault for information about the specific  failure that occurred. [ISS.0088.9134] Exception occurred while processing the body of the message. Cause: The Integration Server, the SOAP processor, or one of the services processing the  SOAP message has thrown an exception. Response: See the detail element in the SOAP fault to determine the exception that was  thrown and which process it was thrown by. [ISS.0088.9135] A WMDocument Exception was thrown in the server, usually because an XML block was not well-formed. Cause: The SOAP message handler, the soapHTTP service, or the soapRPC service has  received a SOAP message that contains invalid XML. Response: Check the process that submitted the SOAP message to the Integration Server  and make sure that it is producing valid XML. This error usually occurs because of a  basic error in the XML document, such as missing tags or overlapping elements. [ISS.0088.9136] A WattEvaluationException was thrown by the XQL Query engine. Cause: The XQL query processor encountered a serious internal error. Response: Contact Software AG Customer Care. [ISS.0088.9137] Invalid input parameter; paramName must be a Document (IData). Cause: The requested SOAP utility failed to execute because the object passed in  paramName is not an IData object. Response: Check the logic in the SOAP processor or client to make sure that it passes an  IData in paramName. [ISS.0088.9138] Input parameters do not conform to targetInputSignature: validationDetails. Cause: The pub.client:soapRPC service could not submit the remote procedure call because  the input parameters did not pass the data‐validation process. Response: This error is thrown when a client supplies an invalid set of input parameters  for a SOAP remote procedure call. Specifically, it indicates that the parameters submitted  to pub.client:soapRPC in reqParms do not match the structure and constraints of the  document type specified in targetInputSignature.  Generally, you will want to code your client to detect this kind of error and take some  type of corrective action when it occurs.
  • 92. A SOAP Faults Returned by the Integration Server 92 SOAP Developer’s Guide Version 7.1.1 [ISS.0088.9139] Output parameters do not conform to targetOutputSignature: validationDetails. Cause: The SOAP RPC client could not submit the remote procedure call because the  output parameters returned by the remote server did not pass the data‐validation  process. Response: This error is thrown when a client receives an invalid set of output parameters  (results) from a SOAP remote procedure call. Specifically, it indicates that the parameters  returned to pub.client:soapRPC in respParms do not match the structure and constraints of  the document type specified in targetOutputSignature.  Generally, you will want to code your client to detect this kind of error and take some  type of corrective action when it occurs. [ISS.0088.9140] Invalid target signature docTypeName, must be a Document Type Cause: The SOAP RPC client could not process the remote procedure call because it was  not able to validate the input or output parameters associated with the request. The  signature it was given for validation is not a document type. Response: Examine the logic in the SOAP RPC client and make sure that the object it  specifies in targetInputSignature and/or targetOutputSignature is a document type. That is,  these parameters, if used, specify the fully qualified name of a document type that exists  on the Integration Server.  [ISS.0088.9141] Invalid target signature docTypeName, Document Type does not exist Cause: The SOAP RPC client could not process the remote procedure call because it was  not able to validate the input or output parameters associated with the request. The  specified document type does not exist on the Integration Server. Response: Examine the logic in the SOAP RPC client and make sure that  targetOutputSignature and/or targetOutputSignature are correctly specified. (Remember  that the names of document types are case sensitive.). Also verify that the specified  document type exists on the server and the package in which it resides is loaded and  enabled. [ISS.0088.9142] attribute() incorrect attribute name "{0}" Cause: The pub.soap.util:addBodyEntry service failed because it was given an XML node that  was not namespace qualified. Response: Examine the logic in the SOAP client or target service (depending on which  entity issued the error) and verify that the XML node that the addBodyEntry service is  attempting to add is namespace qualified (that is, that it includes the xmlns attribute and  that the element name has the proper namespace prefix).  Note: This error occurs only if namespace checking is enabled on the Integration  Server. See “watt.server.SOAP.enforceMsgPartNS” on page 113.
  • 93. SOAP Developer’s Guide Version 7.1.1 93 A SOAP Faults Returned by the Integration Server [ISS.0088.9143] count() takes a query parameter Cause: The pub.soap.util:addHeaderEntry service failed because it was given an XML node that  was not namespace qualified. Response: Examine the logic in the SOAP client or target service (depending on which  entity issued the error) and verify that the XML node that the addHeaderEntry service is  attempting to add is namespace qualified (that is, that it includes the xmlns attribute and  that the element name has the proper namespace prefix).  [ISS.0088.9144] This SOAPEnvelope object already contains a valid SOAPHeader object. Cause: An attempt was made to add a SOAPHeader object to the SOAPEnvelope of a  SOAPMessage that already contains a SOAPHeader object. Response: Any SOAPEnvelope object must contain a maximum of one SOAPHeader  objects. [ISS.0088.9145] This SOAPEnvelope object does not contain a valid SOAPHeader object. Cause: An attempt was made to access the SOAPHeader object, but the SOAPEnvelope of  the SOAPMessage does not contain a SOAPHeader object. Response: Add a SOAPHeader object to the SOAPEnvelope before accessing it. [ISS.0088.9146] This SOAPEnvelope object already contains a valid SOAPBody object. Cause: An attempt was made to add a SOAPBody object to the SOAPEnvelope of a  SOAPMessage that already contains a SOAPBody object. Response: Any SOAPEnvelope object must contain exactly one SOAPBody object. [ISS.0088.9147] This SOAPEnvelope object does not contain a valid SOAPBody object. Cause: An attempt was made to access the SOAPBody object, but the SOAPEnvelope of  the SOAPMessage does not contain a SOAPBody object. Response: Add a SOAPBody object to the SOAPEnvelope before accessing it. [ISS.0088.9148] Exception occurred while retrieving SOAPHeader object. Cause: The specified exception occurred while attempting to access the SOAPHeader  object. Response: Correct the error and retry. Note: This error occurs only if namespace checking is enabled on the Integration  Server. See “watt.server.SOAP.enforceMsgPartNS” on page 113.
  • 94. A SOAP Faults Returned by the Integration Server 94 SOAP Developer’s Guide Version 7.1.1 [ISS.0088.9149] Exception occurred while retrieving SOAPBody object. Cause: The specified exception occurred while attempting to access the SOAPBody object. Response: Correct the error and retry. [ISS.0088.9150] Exception occurred while retrieving SOAPHeaderElement objects. Cause: The specified exception occurred while attempting to access the  SOAPHeaderElement object. Response: Correct the error and retry. [ISS.0088.9151] Exception occurred while retrieving SOAPBody Element objects. Cause: The specified exception occurred while attempting to access the  SOAPBodyElement object. Response: Correct the error and retry. [ISS.0088.9152] The property <property> is unknown. Cause: An attempt was made to either get or set a property of the specified  SOAPMessage, unknown. The only valid SOAPMessage property names are  javax.xml.soap.WRITE_XML_DECLARATION and  javax.xml.soap.CHARACTER_SET_ENCODING. Response: Correct the name of the property to use one of the valid property names. [ISS.0088.9153] This SOAPMessage object already contains a valid Detail object. Cause: An attempt was made to add a Detail object to the SOAPBody of this  SOAPMessage, but the SOAPBody already contains a Detail object. The SOAPBody can  contain one and only one Detail object.  Response: Remove the existing Detail object before adding the new one. [ISS.0088.9154] This SOAPMessage object already contains a valid Fault object. Cause: An attempt was made to add a Fault object to the SOAPBody of this  SOAPMessage, but the SOAPBody already contains a Fault object. The SOAPBody can  contain one and one only Fault object. Response: Remove the existing Fault object before adding a new one. [ISS.0088.9155] This SOAPMessage does not contain a valid Envelope object. Cause: The specified SOAPMessage does not contain a valid SOAPEnvelope object. Response: Create a new SOAPMessage that contains a valid SOAPEnvelope object.
  • 95. SOAP Developer’s Guide Version 7.1.1 95 A SOAP Faults Returned by the Integration Server [ISS.0088.9156] JAX Handler <handler> already registered. Cause: An attempt was made to register the JAX‐RPC handler, but the handler is already  registered. Response: No action is required. [ISS.0088.9157] Error initializing JAX Handler <handler>:<errorMessage> Cause: An error occurred while initializing the JAX‐RPC handler. The error message is  specified following the colon. Response: Correct the error indicated by the error message and retry. [ISS.0088.9158] Error destroying JAX Handler <handler>:<errorMessage> Cause: An error occurred while destroying the JAX‐RPC handler. The error message is  specified following the colon. Response: Correct the error indicated by the error message and retry. [ISS.0088.9159] Failed to register JAX Handler <handler>. Cause: An attempt to register the JAX‐RPC handler failed. Response: Search the Integration Server log for errors indicating why the JAX‐RPC  handler could not be registered. Correct any errors and retry. [ISS.0088.9160] Failed to unregister JAX Handler <handler> - Not Registered. Cause: An attempt to unregister the JAX‐RPC handler failed. The handler was not  registered. Response: No action is required. [ISS.0088.9161] Failed to find JAX Handler <handler> - Not Registered. Cause: The specified JAX‐RPC handler could not be located because it is not registered. Response: Register the specified JAX‐RPC handler and retry. [ISS.0088.9162] Failed to find JAX Handler for header <header> Cause: The JAX‐RPC handler for the specified header was not found. Response: Correct the name of the JAX‐RPC handler and retry.
  • 96. A SOAP Faults Returned by the Integration Server 96 SOAP Developer’s Guide Version 7.1.1 [ISS.0088.9163] Could not retrieve WSDL for service <service>; WSD not found Cause: An attempt to retrieve the WSDL for the specified service fails because the Web  service descriptor does not exist. Response: Correct the name of the web service and verify that the Web service descriptor  exists. [ISS.0088.9164] Access to Web service descriptor <Web service descriptor> denied. Cause: The user is not authorized to access the specified Web service descriptor. Response: Specify a username that is authorized to access the specific Web service  descriptor. [ISS.0088.9251] JAX-RPC Handler failed to process the message. Cause: The JAX‐RPC Handler was invoked to process the message. Either the  handleRequest() or handleResponse() method returned false, indicating a failure. Response: Check the Integration Server log for error messages generated by the JAX‐RPC  handler. [ISS.0088.9252] An exception has been caught: <errorMessage> Cause: An exception was caught while attempting to process a SOAPMessage. Response: Correct the problem indicated by the error message. [ISS.0088.9253] Could not add “Text” element to “Reason” element, locale is null. Cause: An attempt to add a Text element to the existing Reason element failed because the  locale was not specified. Response: Specify the locale when adding the Text element. [ISS.0088.9254] The System property, javax.xml.soap.MetaFactory must be set to “com.wm.app.b2b.server.saaj.SAAJMetaFactory” Cause: The javax.xml.soap.MetaFactory is not set properly. Response: Set the javax.xml.soap.MetaFactory property to  “com.wm.app.b2bserver.saaj.SAAJMetaFactory”. [ISS.0088.9320] MTOM Attachments Processing Failed: Cannot convert SOAP Message to XOP Package; “null” value for “Web Service Descriptor”. Cause: The Web service descriptor identified by the part of request URL (for provider) or  passed Web service descriptor name (for consumer) as parameter, does not exist. Response: Correct the URL or correct the passed Web service descriptor name or create a  proper Web service descriptor.
  • 97. SOAP Developer’s Guide Version 7.1.1 97 A SOAP Faults Returned by the Integration Server [ISS.0088.9321] MTOM Attachments Processing Failed: Cannot convert SOAP Message to XOP Package; base64Binary encoded data is not in the Canonical Lexical form. Cause: Base64Binary encoded data is not in Canonical Lexical form; it contains line break  characters or tabs. Response: Convert the Base64Binary data into Canonical Lexical form. [ISS.0088.9322] MTOM Attachments Processing Failed: Cannot convert SOAP Message to XOP Package; invalid SOAP Message. Cause: The SOAP Message is invalid; either it is not well formed or it does not contain  valid namespace declarations. Response: Check the structure and content of the SOAP message. [ISS.0088.9323] MTOM Attachments Processing Failed: Cannot convert SOAP Message to XOP Package; I/O Error occurred. Cause: Converting SOAP Message to XOP package has been interrupted by another  thread. Response: Retry the action that caused it. [ISS.0088.9324] MTOM Attachments Processing Failed: Cannot convert XOP Package to SOAP Message; “Content-Id” header field is missing in some of the attachments. Cause: One or more attachments does not contain the “Content‐Id” field. This field is  required to put the content of the attachment back into the SOAP message. Response: Verify that the serialization of XOP Package to MIME stream had “Content‐Id”  present in the corresponding MIME part. [ISS.0088.9325] MTOM Attachments Processing Failed: Cannot serialize the XOP Message; unable to retrieve bytes from SOAP String using the SOAP Message Content Encoding. Cause: The conversion of SOAP String to byte array using the encoding specified for  SOAP Message has failed.  Response: Correct the content encoding specified for the SOAP message.  [ISS.0088.9326] MTOM Attachments Processing Failed: Cannot serialize the XOP Message; MIME serialization has failed. Cause: Serialization of XOP Package to MIME Stream has failed. Response: Verify the structure of SOAP Message is correct, particularly the elements  which contains base64Binary data.
  • 98. A SOAP Faults Returned by the Integration Server 98 SOAP Developer’s Guide Version 7.1.1 [ISS.0088.9327] MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream; value of the “Content-type” header of the MIME message is not equal to “multipart/related”. Cause: Value for the “Content‐Type” header field of the MIME Message is not equal to  “multipart/related”. Response: Verify that you have passed the correct value for “Content‐type” while  serializing the MIME Message. [ISS.0088.9328] MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream; value of the “type” parameter of the “Content-Type” header of the MIME message is not equal to “application/xop+xml” Cause: Value for the “type” parameter of the “Content‐Type” header field of the MIME  message is not equal to “application/xop+xml”. Response: Verify that you have passed the correct value for “type” parameter while  serializing the MIME message. [ISS.0088.9329] MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream; value of the “start-info” parameter of the “Content-Type” header of the MIME message is not equal to “application/xop+xml” Cause: Value for the “start‐info” parameter of the “Content‐Type” header field of the  MIME message is not equal to “application/xop+xml”. Response: Check if you have passed the correct value for “start‐info” parameter while  serializing the MIME message otherwise pass the correct value for it. [ISS.0088.9330] MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream; “Content-Type” header of the Root MIME Part is invalid. Cause: Invalid content type for Root MIME part. Response: Verify that you have passed the correct value for “Content‐Type” header field  of the Root MIME Part while serializing the MIME message. [ISS.0088.9331] MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream; “Content-Type” header of the Root MIME Part does not match with the “type” parameter of the MIME message. Cause: The value of the “Content‐Type” header of the Root MIME Part is not equal to the  value of the “type” parameter of the “Content‐Type” header of the MIME message. Response: Verify that you have passed the correct value for these field(s)/parameter(s)  while serializing the MIME messages. 
  • 99. SOAP Developer’s Guide Version 7.1.1 99 A SOAP Faults Returned by the Integration Server [ISS.0088.9332] MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream; value of the “type” parameter of the “Content-Type” header of the Root MIME Part does not match with the value of the “start-info” parameter of the MIME message. Cause: The value of the “type” parameter of the “Content‐Type” header of the Root MIME  Part is not equal to the value of the “start‐info” parameter of the “Content‐Type” header  of MIME message. Response: Verify that you have passed the correct value for these field(s)/parameter(s)  while serializing the MIME. [ISS.0088.9333] MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream; SOAP Message in the Root MIME Part is not of version 1.2. Cause: The version of the SOAP Message is not equal to 1.2. Response: Edit the version of the SOAP Message to 1.2 and send the SOAP 1.2 message. [ISS.0088.9334] MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream; Root MIME Part contains invalid SOAP Message. Cause: The SOAP message in the Root MIME Part is invalid; either it is not well formed or  it does not contain valid name space declarations. Response: Check the structure and content of the SOAP message in the Root MIME Part. [ISS.0088.9335] MTOM Attachments Processing Failed: Cannot de-serialize the input MIME Stream; input stream is not a valid MIME stream. Cause: MIME Stream does not contain the valid data as per the MIME specifications. Response: Verify that the MIME stream contains a valid MIME message.
  • 100. A SOAP Faults Returned by the Integration Server 100 SOAP Developer’s Guide Version 7.1.1
  • 101. SOAP Developer’s Guide Version 7.1.1 101 B Encoding/Decoding Data-Type Mapping XML-to-Java Mappings (Decoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Java-to-XML Mappings (Encoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 webMethods to XML Mappings (Encoding & Decoding) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
  • 102. B Encoding/Decoding Data-Type Mapping 102 SOAP Developer’s Guide Version 7.1.1 XML-to-Java Mappings (Decoding) The following tables describe the Java objects that the message coder creates for the  various XML Schema data types. Data types from http://schemas.xmlsoap.org/soap/encoding/ The following describes the Java objects to which Simple Object Access Protocol (SOAP) 1.1  ‐ W3C Note 08 May 2000 types are converted (that is, types from namespace  http://schemas.xmlsoap.org/soap/encoding/): Note: The message coder generates the objects listed below only when a parameter is  declared as an Object in the accompanying signature. This list does not apply to  parameters that the signature declares as Strings. If the signature defines a parameter  as a String or if a parameter is not defined in a signature, the message coder always  renders it as a String. When the XML parameter is of type… The message coder renders it as a… ENTITIES String ENTITY String ID String IDREF String IDREFS String NCName String NMTOKEN String NMTOKENS String NOTATION String Name String QName String base64 byte[ ] binary String boolean Boolean byte Byte century String date Date decimal BigDecimal double Double
  • 103. SOAP Developer’s Guide Version 7.1.1 103 B Encoding/Decoding Data-Type Mapping 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 When the XML parameter is of type… The message coder renders it as a…
  • 104. B Encoding/Decoding Data-Type Mapping 104 SOAP Developer’s Guide Version 7.1.1 Data types from http://www.w3.org/1999/XMLSchema The following describes the Java objects to which the types defined in XML Schema  Datatypes ‐  W3C Last Call Draft April 7 2000 are converted (that is, types from namespace  http://www.w3.org/1999/XMLSchema). 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 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
  • 105. SOAP Developer’s Guide Version 7.1.1 105 B Encoding/Decoding Data-Type Mapping Data types from http://www.w3.org/2000/10/XMLSchema The following describes the Java objects to which XML Schema Datatypes ‐  W3C Candidate  Recommendation Oct 24 2000 types are converted (that is, types from namespace  http://www.w3.org/2000/10/XMLSchema): 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 When the XML parameter is of type… The message coder renders it as a… CDATA String ENTITIES String ENTITY String ID String IDREF String IDREFS String hexBinary byte[ ] NCName String NMTOKEN String When the XML parameter is of type… The message coder renders it as a…
  • 106. B Encoding/Decoding Data-Type Mapping 106 SOAP Developer’s Guide Version 7.1.1 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 timeInstant String timePeriod String token String When the XML parameter is of type… The message coder renders it as a…
  • 107. SOAP Developer’s Guide Version 7.1.1 107 B Encoding/Decoding Data-Type Mapping Data types from http://www.w3.org/2001/XMLSchema The following describes the Java objects to which XML Schema Datatypes ‐  W3C  Recommendation May 2 2001 types are converted (that is, types from namespace  http://www.w3.org/2001/XMLSchema): unsignedByte Short unsignedInt Long unsignedLong BigInteger unsignedShort Integer uriReference String year String When the XML parameter is of type… The message coder renders it as a… ENTITIES String ENTITY String ID String IDREF String IDREFS String hexBinary byte[ ] NCName String NMTOKEN String NMTOKENS String NOTATION String Name String QName QName anyURI String base64Binary String boolean Boolean byte Byte date Date dateTime GregorianCalendar decimal BigDecimal When the XML parameter is of type… The message coder renders it as a…
  • 108. B Encoding/Decoding Data-Type Mapping 108 SOAP Developer’s Guide Version 7.1.1 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 When the XML parameter is of type… The message coder renders it as a…
  • 109. SOAP Developer’s Guide Version 7.1.1 109 B Encoding/Decoding Data-Type Mapping Java-to-XML Mappings (Encoding) The following describes how Java objects are encoded as XML schema data types. Note: The following data types are used only when message coder is encoding a  parameter that is defined as an Object in the accompanying signature or is encoding a  parameter that is not declared in a signature. When a parameter is defined as a String  in the accompanying signature, it is always encoded according to its Content type  constraint. Object of type… Is encoded as type… From namespace… BigDecimal decimal  http://www.w3.org/2001/XMLSchema BigInteger integer  http://www.w3.org/2001/XMLSchema Boolean boolean  http://www.w3.org/2001/XMLSchema Byte byte  http://www.w3.org/2001/XMLSchema byte[ ] base64  http://schemas.xmlsoap.org/soap/encoding/ Date date http://www.w3.org/2001/XMLSchema Document string  http://www.w3.org/2001/XMLSchema Double double  http://www.w3.org/2001/XMLSchema ElementNode string  http://www.w3.org/2001/XMLSchema Float float  http://www.w3.org/2001/XMLSchema GregorianCalend ar datetime  http://www.w3.org/2001/XMLSchema Hashtable Hashtable  http://www.webmethods.com/2001/10/soap/encoding IData* data  http://www.webmethods.com/2001/10/soap/encoding Integer int  http://www.w3.org/2001/XMLSchema Long long  http://www.w3.org/2001/XMLSchema MBoolean boolean  http://www.w3.org/2001/XMLSchema MByte byte  http://www.w3.org/2001/XMLSchema MDouble double  http://www.w3.org/2001/XMLSchema MFloat float  http://www.w3.org/2001/XMLSchema MInteger int  http://www.w3.org/2001/XMLSchema MLong long http://www.w3.org/2001/XMLSchema MShort short http://www.w3.org/2001/XMLSchema QName QName http://www.w3.org/2001/XMLSchema
  • 110. B Encoding/Decoding Data-Type Mapping 110 SOAP Developer’s Guide Version 7.1.1 webMethods to XML Mappings (Encoding & Decoding) Data types from http://www.webmethods.com/2001/10/soap/encoding The following Java objects are encoded with webMethods‐specific data types (that is,  types from namespace http://www.webmethods.com/2001/10/soap/encoding). Short short http://www.w3.org/2001/XMLSchema String string http://www.w3.org/2001/XMLSchema Vector Vector http://www.webmethods.com/2001/10/soap/encoding Java Object XML type Hashtable Hashtable Vector Vector IData* data com.wm.util.Table data array * Or any class that implements the IData interface (for example, BasicData,  IDataCodable, Values). Object of type… Is encoded as type… From namespace…
  • 111. SOAP Developer’s Guide Version 7.1.1 111 C SOAP-Related Server Parameters SOAP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
  • 112. C SOAP-Related Server Parameters 112 SOAP Developer’s Guide Version 7.1.1 SOAP Parameters The following describes the server parameters that you can use to configure the way in  which SOAP operates on the Integration Server. For information about how to set server  parameters, see the webMethods Integration Server Administrator’s Guide. watt.server.SOAP.directive Specifies the directive that represents the SOAP message handler. The default is soap.  This parameter determines the URL that is used to access SOAP processors on the  Integration Server. watt.server.SOAP.defaultProtocol Specifies the default protocol that Integration Server uses for new SOAP messages.  Specify SOAP 1.1 Protocol or SOAP 1.2 Protocol. The default is SOAP 1.1 Protocol. watt.server.SOAP.MTOMThreshold Specifies the field size, in kilobytes, that determines whether Integration Server handles  base64binary encoded data in a SOAP request as a MIME attachment or whether it sends  it inline in the SOAP message. If the Web service descriptor for the SOAP message  enables attachments for the SOAP request, Integration Server passes as MIME  attachments any base64 fields in a SOAP message that are larger than the threshold. This  only applies to SOAP 1.2 messages. The default is 0. watt.server.SOAP.validateSOAPMessage Specifies whether the SOAP message handler will validate messages that it receives and  sends. Set to true or false. Default is true.  When watt.server.SOAP.validateSOAPMessage is true, the message handler validates  messages against the SOAP schema. Be aware that the this validation process checks only  that the message envelope is structured correctly—for example, it checks the message has  at least one body element and there is at most one header element. It does not validate  any of the data carried by the message.  If you are operating in a production environment where the validity of the messages  submitted to the server is assured, you might set watt.server.SOAP.validateSOAPMessage  to false to optimize performance. Note: This parameter is overridden by an individual SOAP processor’s  validateSOAPMessage setting. Consequently, the server’s  watt.server.SOAP.validateSOAPMessage setting is used only when a SOAP  processor’s validateSOAPMessage parameter has not been set. For more information  about setting the validateSOAPMessage parameter, see the  pub.soap.processor:registerProcessor service in the webMethods Integration Server Built‐In  Services Reference.  http://hostName:portNum/soap/[processDirective] This parameter specifies this segment of the SOAP processor URL
  • 113. SOAP Developer’s Guide Version 7.1.1 113 C SOAP-Related Server Parameters watt.server.SOAP.useMultiReference Specifies how the message coder is to encode parameters that point to the same  underlying data object in the pipeline. Set to true or false. Default is true. For example, if two output parameters cDate and oDate point to the same underlying data  in the pipeline, the message coder encodes the parameters like this if  watt.server.SOAP.useMultiReference is true: And like this if watt.server.SOAP.useMultiReference is false: watt.server.SOAP.enforceMsgPartNS Specifies whether the server allows non‐namespace qualified header and body entries to  be added to a SOAP message. Set to true or false. Default is true. If watt.server.SOAP.enforceMsgPartNS=true, the server will throw an exception if the  pub.soap.utils:addHeaderEntry or pub.soap.utils:addBodyEntry service (or their underlying  methods) attempts to insert a non‐namespace qualified element into a SOAP message. If  false, non‐namespace qualified elements are permitted. For interoperatbility with other SOAP implementations, we recommend that you run  your server with this parameter enabled (the default setting). This ensures that your  server will not generate and transmit SOAP messages that have non‐namespace qualified  header or body entries. Note: This parameter affects only the way in which multi‐referenced parameters are  encoded. It does not affect the way in which they are decoded. The message coder  always recognizes and decodes multi‐referenced elements regardless of how  watt.server.SOAP.useMultiReference is set. . . . <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 . . . <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
  • 114. C SOAP-Related Server Parameters 114 SOAP Developer’s Guide Version 7.1.1
  • 115. SOAP Developer’s Guide Version 7.1.1 115 D Using the SOAP RPC Processor What is the RPC Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Behavior of the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Building Target Services for the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 The Message Coder and the RPC Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
  • 116. D Using the SOAP RPC Processor 116 SOAP Developer’s Guide Version 7.1.1 What is the RPC Processor? The RPC processor is the subsystem that the Integration Server uses to receive and  process SOAP remote procedure calls (RPCs). The RPC processor is invoked when the  message handler receives a URL with a process directive set to “rpc,” as shown below: What Does a SOAP RPC Message Look Like? A SOAP RPC message is an ordinary SOAP message whose body conveys a remote  procedure call. The body of an RPC message has a standard structure that specifies the  name of the requested procedure and its input parameters.  The qualified name (QName) of the first element within the body identifies the procedure  that the client is calling. On the Integration Server, the QName specifies the universal  name of the service to be executed. The children within the first element represent the input parameters for the requested  procedure. For example, the following message body contains a call to a procedure named  GL:journalEntry. It also conveys four input parameters to this procedure: Id, date, amt,  and acct. Basic structure of a SOAP remote procedure call For more information about the structure of a SOAP RPC message, see the Simple Object  Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/. Note: The RPC Processor is deprecated for Integration Server 7.1. To submit a SOAP RPC message to the Integration Server, specify the “rpc” directive in the URLhttp://rubicon:5555/soap/rpc <SOAP-ENV:Body> <GL:journalEntry xmlns:GL="http://www.expt.com/GL"> <Id>2398</Id> <date>03/15/2000</date> <amt>237.50</amt> <acct>Cash</acct> </GL:journalEntry> </SOAP-ENV:Body> The QName of the first element specifies the requested procedure... ...and its children supply the input parameters. . . . . . . GL:journalEntry <Id>2398</Id> <date>03/15/2000</date> <amt>237.50</amt> <acct>Cash</acct> <amt>237.50</amt>
  • 117. SOAP Developer’s Guide Version 7.1.1 117 D Using the SOAP RPC Processor QNames and Input Parameters When an RPC processor receives a SOAP remote procedure call, it must: Resolve the QName in the body in the message with the name of a procedure in the  local environment, and… Render the input parameters in a form that the target procedure can use. On the Integration Server, the RPC processor performs this work by: Matching the QName to the universal name of a service, and… Engaging the message coder to convert the XML‐encoded input parameters to a set of  Java objects that the service can consume. What Does a Results Message Look Like? Results are also carried in the body of the message and are formatted in a standard way.  The qualified name (QName) of the first element within the body of the message is the  same as the QName of the first in the original request, except that the suffix  “Response” is appended to it. The children of this element contain the output values from the requested procedure. The following is an example of a response message that contains two output parameters:  status and balance. Basic structure of a SOAP RPC results message The results use the same namespace as the original request. By default, the webMethods  Integration Server uses the prefix “ser‐root” for this namespace. Note:  The Integration Server expects the QName in the incoming SOAP message to be  normalized according to Unicode Normalization Form C. Normalization ensures that  names containing non‐ASCII characters (particularly those with accented or  combining characters) are represented in a standard way. If the client has not  normalized the QName, the Integration Server might not be able to match it with a  universal name in its registry. <SOAP-ENV:Body> <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> The QName of the first element has the “Response” suffix... ...and its children contain the output parameters . . . . . . ser-root:journalEntryResponse <status xsi:type="xsd:string">closed</status> <balance xsi:type="xsd:int">0</balance> . . .
  • 118. D Using the SOAP RPC Processor 118 SOAP Developer’s Guide Version 7.1.1 For more information about the structure of a SOAP RPC response, see the Simple Object  Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/. Behavior of the RPC Processor When the RPC processor receives a SOAP message, the following occurs: 1 The processor searches for the target service. The processor locates the service whose  universal name (explicit or implicit) matches the QName of the first element in the  body of the message. For example, if the RPC processor received the following request, it would fetch the  service whose universal name matches the namespace name http://www/expt.com/GL/ and  the local name journalEntry.  If the processor cannot locate the target service, it returns a SOAP fault that contains  the following error message: [ISS.0088.9122] Service namespaceName:localName does not exist For more information about this error, see Appendix A, “SOAP Faults Returned by  the Integration Server”. 2 If the processor finds the requested service, the message coder decodes the input parameters. The message coder extracts the XML‐encoded input parameters from the body of the  message and converts them into Java objects. For more information about the  decoding process, see “Decoding the Input Parameters” on page 123. 3 The processor invokes the target service and passes the decoded parameters to the service  via the pipeline. 4 When the service ends, the message coder encodes the results. The message coder converts  the parameters named in the output signature to a set of XML‐encoded values. For  more information about encoding, see “Encoding the Output Parameters” on  page 127. 5 The processor assembles the SOAP response message and passes it back to the message  handler. . . . <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> . .
  • 119. SOAP Developer’s Guide Version 7.1.1 119 D Using the SOAP RPC Processor Building Target Services for the RPC Processor Any service on the Integration Server can function as a target service of a SOAP remote  procedure call, providing it satisfies the following criteria: The service’s implicit or explicit universal name matches the QName that the client  will submit in the remote procedure call. For information about assigning universal  names to services, see “To assign, edit, or view an explicit universal name” on  page 34. The names of the parameters in the target service’s input signature match the names  of the parameters that the client will pass in the remote procedure call. (Keep in mind  that these names are case sensitive.) The service’s output signature defines all of the values that are to be returned to the  client. The service’s ACL specifies the groups of users who are authorized to execute it. To ensure that parameters are properly encoded, decoded, and validated, you should  also ensure that: The Content type property for each String‐based parameter in the output signature  specifies the data type that is to be assigned when they are XML‐encoded. (See “The  Message Coder and the RPC Processor” on page 122 for information about how the  Content type property is used to encode and decode parameter values.) The service’s Validate input and/or Validate output properties are enabled if you want the  input and/or output values to be validated at run time. Error Handling If a target service throws an exception while it is processing, the message handler  automatically returns a SOAP fault to the client. Depending on the type of error that  occurs, the SOAP fault may include a “detail” element, which provides specific  information about the exception. This element will include a stackTrace element if the  client is a member of the Developers or Administrators user group.
  • 120. D Using the SOAP RPC Processor 120 SOAP Developer’s Guide Version 7.1.1 For more information about SOAP faults, see Appendix A, “SOAP Faults Returned by  the Integration Server”. Example—Target Service for the RPC Processor The following is an example of a very simple target service that is suitable for calling with  SOAP RPC. This service takes three String parameters (acct, amt, and loc) and returns one  String parameter (authCode). This service is located in sample.soap:targetSvc_rpcProcSimple. You can call it via SOAP RPC  by executing the client service, sample.soap:buildRPC_SendHTTPSimple, from Developer.  When you run the client service in Developer, it will prompt you for the following values: For this input parameter... Enter... acct Any string of characters. amt A decimal value, such as 150.75 or 15.00. (Omit commas from  large values; otherwise, the value will fail validation.) loc Any string of characters. userName A user name that belongs to the Developers ACL. password The password for the user name that you entered in  userName. ...and details about the error. ...containing the error message... When the target service throws an exception, the message handler returns a SOAP fault... <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode> SOAP-ENV:Client </faultcode> <faultstring> [ISS.0088.9134] Exception occurred while processing the body of messag </faultstring> <faultactor> http://localhost:5555/soap/mySoapProc </faultactor> <detail xmlns="http://www.webmethods.com/2001/10/soap/"> <exception> <className>nameOfClassThatWasThrown</className> <message xml:lang="en-US">detailedMsgIssuedbyException</message> <stackTrace>textFromStackTrace</stackTrace> </exception> </detail> </SOAP-ENV:Fault>
  • 121. SOAP Developer’s Guide Version 7.1.1 121 D Using the SOAP RPC Processor A simple target service This flow simulates a service that issues an authorization code based on the value in the  input parameter amt. Because a SOAP RPC target does not require any special logic, the  service does not perform any work that is SOAP‐specific. You could call this service from  any type of client. It contains nothing that restricts its use to SOAP remote procedure  calls. The characteristics that are significant if this service is to be used as a SOAP RPC target  are its signature and its universal name. The Signature. The signature for this service defines three input variables (acct, amt, and  loc) and one output variable (authCode). Note that the Validate input and Validate output settings are enabled in this example to ensure that the input and output values are  validated at run time. Signature for the sample target service The signature is critical because it determines how variables are decoded and  encoded at run time. In this example, the input variables are declared as Strings,  which means that the message coder will render them as Strings regardless of the  data types specified in the XML. If you examine the properties for these parameters with the Developer, you will see  that the Content type and Required properties are specified. These will be used to  validate the values that the client provides.
  • 122. D Using the SOAP RPC Processor 122 SOAP Developer’s Guide Version 7.1.1 The signature declares one output variable called authCode. Because this is the only  variable declared in the output signature, it will be the only parameter returned to the  client.  If you examine the properties for authCode, you will see that its Content type is set to  string {http://www.w3.org/2001/XMLSchema}. This tells the message coder to set the  type attribute to ʺxsd:stringʺ when it encodes this parameter. The Universal name. An explicit universal name has been specified for this service in the  Universal name category of the Properties panel. The universal name determines the  QName that causes this service to execute. In this example, the service will be  triggered when a client submits a SOAP remote procedure call whose QName is  composed of the namespace name http://www.expt.com/AUTH and the local name  getAuthCode. Properties for the sample target service The Message Coder and the RPC Processor The message coder is the subsystem that decodes and encodes the input and output  parameters associated with a SOAP remote procedure call. Its role is to turn a set of XML‐ encoded values into a pipeline of the appropriate data types (the decoding process) and,  conversely, to turn objects in the pipeline to a set of XML‐encoded values (the encoding  process).  Note: The encoding and decoding processes are sometimes referred to as “serializing  and deserializing” or “marshalling and unmarshalling.” Universal name is specified on the Properties panel
  • 123. SOAP Developer’s Guide Version 7.1.1 123 D Using the SOAP RPC Processor Encoding/Decoding Rules To encode and decode the parameters in a SOAP RPC message, the message coder  follows the SOAP 1.1 encoding style, which is specified by the following SOAP  encodingStyle attribute: SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" This attribute specifies the set of rules that govern how the input and output parameters  of a SOAP RPC message are to be represented in XML. These rules are defined in the  “SOAP Encoding” section of the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08  May 2000 at http://www.w3.org/TR/SOAP/.  Decoding the Input Parameters The decoding process is the process of converting a set of XML‐encoded values to an IData  object (a pipeline). When the RPC processor receives a valid procedure call, it engages the message coder,  which decodes the input parameters and produces the pipeline that is passed to the  target service.  Transforming Input Parameters into a Pipeline To produce a pipeline for the target service, the message coder uses the input parameters  from the body of the message and the input signature from the target service. Note: Currently, the Integration Server supports only the SOAP 1.1. encoding style.  However, the ability to accommodate different encoding styles is designed into the  product, so as additional styles become available, support for them can easily be  added to the Integration Server. Note: The message coder is also engaged by the SOAP RPC client to decode the output  parameters returned by a SOAP remote procedure call. For information about this  use of the message coder, see “The Message Coder and the RPC Client” on page 71.
  • 124. D Using the SOAP RPC Processor 124 SOAP Developer’s Guide Version 7.1.1 Producing a pipeline from the input parameters in a remote procedure call During the decoding process, the message coder matches the names of the parameters  passed by the client with the names of the parameters defined in the input signature. It  uses the input signature to determine how to render the parameters in the pipeline. If the input signature declares a parameter as a String, the parameter is rendered as a Java  String object, regardless of the data type declared in the XML. If the input signature declares a parameter as an Object, the value is rendered according to  the data type declared in the XML. (For a list of XML data types and the Java classes  to which they are converted, see Appendix B, “Encoding/Decoding Data‐Type  Mapping”.) If an XML element does not declare its type, the parameter is rendered as  a String. The following table shows how the message coder would decode an input parameter  named amt given various data‐type declarations and input signatures. Note that when  the input signature defines the parameter as a String, the message coder always produces  a String object, regardless of the data type declared in the XML.  When XML data type is... and Input Signature is... The Message Coder produces... <amt xsi:type="xsd:decimal">500.00</amt> <amt xsi:type="xsd:decimal">500.00</amt> of class java.math.BigDecimal Message Coder The message coder takes the encodingStyle and the input parameters from the SOAP RPC message… …and the input signature from the target service… …and produces a pipeline for the target service 1 2 3
  • 125. SOAP Developer’s Guide Version 7.1.1 125 D Using the SOAP RPC Processor Parameters that are Not in the Input Signature The message coder decodes every input parameter that a client submits, even those that  do not appear in the input signature. When a client submits parameters that are not  declared in the input signature, the message coder renders them as Strings. Decoding Complex Structures and Arrays For complex data types (XML elements that contain child elements), the message coder  produces documents (IData objects) in the pipeline. The message coder creates arrays of elements (that is, String Lists, Document Lists, Object  lists) for elements that are properly encoded as SOAP arrays in the SOAP message. For  more information about how the arrays are encoded in a SOAP message, see the “Arrays”  section in the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May 2000 at  http://www.w3.org/TR/SOAP/#_Toc478383522. Decoding Multi-Referenced Parameters The message coder can resolve parameters that are referenced through the href attribute  as long as the referenced value appears within the body of the SOAP message. The  message coder cannot resolve external references (references that point to resources  outside of the message) or references that point to elements outside the Body element. Within the Body element, the href attribute may appear before or after the value that it  references. The message coder can successfully resolve either type. <amt xsi:type="xsd:float">500.00</amt> <amt xsi:type="xsd:float">500.00</amt> of class java.lang.Float <amt>500.00</amt> (that is, undeclared) <amt>500.00</amt> (that is, undeclared) When XML data type is... and Input Signature is... The Message Coder produces...
  • 126. D Using the SOAP RPC Processor 126 SOAP Developer’s Guide Version 7.1.1 For referenced elements, the message coder puts a single copy of the value in the pipeline  and generates references to it. Decoding and Validation Be aware that the message coder does not validate the input parameters that it decodes.  For example, it does not verify that an element of type xsi:type=decimal actually  contains a numeric value. It simply renders the element as a java.lang.String object or a  java.math.BigDecimal object, depending on the data type specified in the signature of the  target service. Additionally, the message coder does not verify that the set of parameters it receives from  the client matches the parameters in the input signature in name or number. If a client  includes parameters that are not in the input signature, the message coder includes them  in the pipeline anyway (as Strings). If a parameter is declared in the input signature, but  is not supplied by the client, that parameter is omitted from the pipeline. Validating Input Parameters If you want to validate the input parameters that a client submits via SOAP RPC, you use  the server’s normal validation mechanisms to impose data validation on the target  service. For example, to ensure that clients provide a non‐negative integer for a  parameter named hours, you would: Constrain the hours parameter by setting its Content type property to: nonNegativeInteger {http://www.w3.org/2001/XMLSchema} Note: If the message coder cannot resolve a reference, it generates a null object for that  parameter. It also reports the problem in the server log if the server is running at  debug level 5 or higher. Example of a Backward Reference . . . <cDate id="id1">03/15/2000</cDate> <amt id="id2">300</amt> <oDate href="#id1"></oDate> . . . Example of a Forward Reference . . . <oDate href="#id1"></oDate> <amt id="id2">300</amt? <cDate id="id1">03/15/2000</cDate> . . . In a backwards reference, a referenced value appears before the point where it is referenced. In a forward reference, a referenced value appears after the point where it is referenced.
  • 127. SOAP Developer’s Guide Version 7.1.1 127 D Using the SOAP RPC Processor Enable the parameterʹs Required property, and Set the Validate input option on the target service’s Input/Output tab. These settings would cause the server to throw an exception if the client omitted the hours  parameter or submitted a value such as .5 or twenty rather than a non‐negative integer.  For more information about validating data at run time, see the webMethods Developer  User’s Guide. Encoding the Output Parameters The encoding process is the process of converting a Java object to an XML‐encoded value.  The SOAP RPC processor engages the message coder to encode the results of services  that are invoked via a SOAP remote procedure call. Transforming Output Parameters to XML When the message coder encodes the results of a remote procedure call, it uses both the  values in the pipeline and the output signature of the target service. Encoding the output parameters from a remote procedure call Note: The message coder is also engaged by the SOAP RPC client to encode the input  parameters for an outbound remote procedure call. For information about this use of  the message coder, see “The Message Coder and the RPC Client” on page 71. Message Coder The message coder uses the pipeline… …and the output signature of the target service… …to produce the XML-encoded results 1 2 3
  • 128. D Using the SOAP RPC Processor 128 SOAP Developer’s Guide Version 7.1.1 During the encoding process, the message coder converts the parameters defined in the  output signature to XML‐encoded values. If the output signature declares a parameter as a String, the value of the parameter is  encoded according to its Content type property. For example, if Content type were  nonNegativeInteger {http://www.w3.org/2001/XMLSchema}, the value would be  encoded as an xsi:type="xsd:nonNegativeInteger". If Content type is not specified, the  message coder encodes the value as a string (as if the parameter were Content type  string {http://www.w3.org/2001/XMLSchema}). If the output signature declares a parameter as an Object, the value of the parameter is  encoded according to its underlying Java class. For example, if the object were a  java.lang.Boolean, the message coder would declare it as xsi:type="xsd:boolean" in  the resulting XML. For a list of recognized Java classes and the XML Schema data  types to which they are converted, see Appendix B, “Encoding/Decoding Data‐Type  Mapping”. If the message coder does not recognize the underlying class, it encodes  the parameter as a string (it uses the object’s toString( ) method to produce the  parameter’s value). Encoding Complex Structures and Arrays The message coder encodes documents (IData objects) as complex data types.  The message coder encodes Document Lists, String Lists, and Object Lists as SOAP  arrays. For more information about how the arrays are encoded in SOAP messages, see  the “Arrays” section in the Simple Object Access Protocol (SOAP) 1.1 ‐ W3C Note 08 May  2000 at http://www.w3.org/TR/SOAP/#_Toc478383522. Encoding Multi-Referenced Elements By default, the message coder generates references when encoding parameters that  reference the same underlying data in the pipeline. However, this behavior can be  modified with the watt.server.SOAP.useMultiReference parameter. When watt.server.SOAP.useMultiReference is true, the message coder generates the  appropriate id and href attributes for parameters that reference the same underlying data.  For example, if the parameters cDate and oDate refer to the same object, the message  Important! It is important to understand that the message coder encodes only those  parameters defined in the service’s output signature. It does not encode the entire  pipeline. Therefore, if a service has no output signature, no values are returned to the  client. Additionally, this means that if any of the original input values need to be  returned to the client, those values must be included in the output signature.
  • 129. SOAP Developer’s Guide Version 7.1.1 129 D Using the SOAP RPC Processor coder encodes them like this if watt.server.SOAP.useMultiReference=true (or is not set,  which is the server’s installed behavior): And encodes them like this if watt.server.SOAP.useMultiReference=false: For more information about watt.server.SOAP.useMultiReference and other SOAP‐ related server parameters, see Appendix C, “SOAP‐Related Server Parameters”. For more  information about setting server parameters, see the webMethods Integration Server  Administrator’s Online Help. . . . <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 . . . <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
  • 130. D Using the SOAP RPC Processor 130 SOAP Developer’s Guide Version 7.1.1
  • 131. SOAP Developer’s Guide Version 7.1.1 131 E Creating Custom SOAP Processors What is a Custom SOAP Processor? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Accessing a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Building a Custom SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Registering a SOAP Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
  • 132. E Creating Custom SOAP Processors 132 SOAP Developer’s Guide Version 7.1.1 What is a Custom SOAP Processor? If the default processor provided by webMethods Integration Server does not suit your  needs, you can create your own customized SOAP processor and register it on the  Integration Server. For example, you might create a custom processor that delegates  messages based on the value of a particular header entry, or you might create a customer  processor that drops messages into queues based on the type of documents they carry. Implementing a custom SOAP processor on the Integration Server involves two basic  steps: 1 First, you must build a service that acts as a SOAP processor. You can code this service to  operate on SOAP messages in whatever manner your solution requires. However, it  must accept a soapRequestData object and a soapResponseData object as input, and must  return a soapResponseData object as output. For information about this step, see  “Building a Custom SOAP Processor” on page 133. 2 Second, you must register the service on the Integration Server as a SOAP processor. You do  this to associate the service with a specific process directive (a name that is unique  among all SOAP processors on the server) and make it accessible to the SOAP  message handler. For information about registering a service as a SOAP processor,  see “Registering a SOAP Processor” on page 141. Accessing a Custom SOAP Processor To direct a message to a custom processor, a client specifies the processor’s “process  directive” in the URL. The process directive is the name under which the custom  processor is registered with the SOAP message handler. For example, the following URL  would invoke the custom processor registered as “inbox.” The following URL would invoke the custom processor registered as “svcRq.” Important! The creation of custom processors is deprecated for Integration Server 7.1.  Custom processors created in earlier releases are still supported. Important! Process directives are case sensitive. The directive specified in the URL  must match exactly the process directive as it is defined on the webMethods  Integration Server. This URL directs the message to the SOAP processor registered as “inbox”http://rubicon:5555/soap/inbox This URL directs the message to the SOAP processor registered as “svcRq”http://rubicon:5555/soap/svcRq
  • 133. SOAP Developer’s Guide Version 7.1.1 133 E Creating Custom SOAP Processors If the URL specifies a process directive that is not registered on the server, the SOAP  message handler returns a SOAP fault containing the following error message: [ISS.0088.9123] Requested SOAP processor directiveName is not registered on this server. For information about SOAP faults, see Appendix A, “SOAP Faults Returned by the  Integration Server”. Building a Custom SOAP Processor A SOAP processor is a service that operates on SOAP messages. It can be any type of  service and can contain any kind of logic that your solution requires. Inputs and Outputs When the SOAP message handler invokes a custom processor, it passes two input  parameters to that processor: soapRequestData, an object containing the entire SOAP message soapResponseData, an object containing an empty SOAP message When the custom processor ends or exits, the SOAP message handler returns the  contents of soapResponseData to the client (unless the processor throws an exception, in  which case the SOAP message handler generates a SOAP fault and returns it to the  client). How to Create a Custom SOAP Processor The following describes the general steps you take to create a custom processor. 1 Create a new service that has the following signature: You can use pub.soap.utils:requestResponseSpec to specify the inputs and outputs for the  service. 2 Code the service to process SOAP messages in the way you need. The following describes  several tasks that a custom processor typically executes. However, the behavior of  your processor will depend entirely on the needs of your solution. It might include  all, some, or none of the following: Extracting data from the SOAP request message. To extract information from a SOAP  message, you use the data‐retrieval utilities such as getBody and getHeader. (For a  complete list of the data‐retrieval services, see page 58.) These services retrieve a  Inputs: soapRequestData   (of type Object) soapResponseData   (of type Object) Outputs: soapResponseData   (of type Object)
  • 134. E Creating Custom SOAP Processors 134 SOAP Developer’s Guide Version 7.1.1 specified element from the soapRequestData and return the requested element as  an XML node (or an array of XML nodes). To extract data from the returned node,  you query it with the pub.xml:queryXMLNode service. Invoking services to process the data extracted from the message. After extracting the  data with which you want to work, you can map it to the appropriate variables (if  necessary) and pass it to services that process it in some way. (To ensure that the  data you have extracted is in the correct format, you might want to validate it  against a schema using pub.schema:validate or make sure that the service to which  you pass the data performs data validation on its input parameters.) Invoking services based on a particular QName in the SOAP request message. If your  SOAP messages use a qualified name (QName) to specify a target service on the  webMethods Integration Server, you can use pub.soap.utils:getQName (which resides  in the WmPublic package) to extract the element’s QName from the message and  then use pub.universalName:find (which resides in the WmPublic package) to locate  the service associated with that name. 3 Use the SOAP message-composition services to populate soapResponseData. The message‐ composition services are services (such as addHeaderEntry and addBodyEntry) that you  use to add content to the empty message in soapResponseData. (For a complete list of  message‐composition services, see page 51.)  The message‐composition services require an XML node representation of the header  entry or body entry that you want to add to the message. You can generate an XML  node using services such as pub.xml:documentToXMLString and pub.xml:xmlStringToXMLNode.  For an example of how to do this, see Step 3 in the sample code shown on page 137. 4 When you finish coding the service, register it as a SOAP processor. This step associates the  service with a specific process directive and makes it accessible to the SOAP message  handler. For information about registering a service as a SOAP processor, see  “Registering a SOAP Processor” on page 141. Important! Be aware that you cannot query the soapRequestData object directly.  To extract information from soapRequestData (or similar SOAP objects, such as  soapData and soapResponseData), you must use one of the data‐retrieval  services to extract an element of the message (for example, the header, the  body, or the entire envelope) and query the resulting XML node. Note: To invoke the service associated with a QName, you will need to create a  Java service that performs a doInvoke of the service returned by  pub.universalName:find. See the com.wm.app.b2b.server package in the webMethods  Integration Server Java API Reference for information about the doInvoke method.  This method is a member of the Service class.
  • 135. SOAP Developer’s Guide Version 7.1.1 135 E Creating Custom SOAP Processors Error Handling If your SOAP processor (or any service that it calls) throws an exception, the SOAP  message handler automatically returns the following SOAP fault to the client. The fault  includes a “detail” element that provides specific information about the exception. This  element will include a stackTrace element if the client is a member of the Developers or  Administrators user group. Note: The SOAP message returned to the client when an exception occurs contains  only the SOAP fault. It does not include any message content (for example, header  entries, body entries) that the target service may have inserted into soapResponseData  before the exception occurred.  ...and details about the error. When a custom processor throws an exception, the message handler returns a SOAP fault... ...containing an error message... <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/1999/XMLSchema" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"> <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> http://localhost:5555/soap/mySoapProc </faultactor> <detail xmlns="http://www.webmethods.com/2001/10/soap/"> <exception> <className>nameOfClassThatWasThrown</className> <message xml:lang="en-US">detailedMessageIssuedbyException</message <stackTrace>textFromStackTrace</stackTrace> </exception> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
  • 136. E Creating Custom SOAP Processors 136 SOAP Developer’s Guide Version 7.1.1 Returning Your Own SOAP Faults Although the SOAP message handler automatically returns a SOAP fault when a custom  processor throws an exception, there may be times when you want your custom  processor to return a SOAP fault. For example, you might want to return a fault if the  client omits a required piece of data or if a requested resource is not available. In these  situations, you can choose to do either of the following:  Code your processor to detect the error condition and throw an exception. This will  cause the message handler to return the standard SOAP fault code shown above. If  you include a detailed error message when you throw the exception, that message  will be included in the detail element within the SOAP fault. —OR— Code the processor to detect the error, but instead of throwing an exception, compose  your own SOAP fault in soapResponseData and then exit normally. This will cause the  message handler to simply return the contents of soapResponseData (which contains  the SOAP fault that your processor generated) to the client. If you choose this  approach, you must be thoroughly familiar with the SOAP specification regarding  fault codes. For more information about SOAP faults, see Appendix A, “SOAP Faults Returned by  the Integration Server” of this document and the Simple Object Access Protocol (SOAP) 1.1 ‐  W3C Note 08 May 2000 at http://www.w3.org/TR/SOAP/#_Toc478383507 for SOAP 1.1  and the SOAP 1.2 W3C Recommendation 27 April 2007 at http://www.w3c.org/TR/soap12‐ part1/ for SOAP 1.2. Example—Custom Processor The following is an example of a SOAP processor that drops the body of the message  (along with several other pieces of control information that it extracts from the header)  into a queue based on the value of a certain header entry. If the document is successfully  logged into the queue, the processor returns an acknowledgment. Otherwise, it generates  an error message and throws an exception so that the client receives a SOAP fault. This example is located in sample.soap:customProc_msgQueue in the WmSamples package.  You can find the WmSamples package in the certified samples area of the Knowledge  Base on the Advantage Web Site. You might want to open this example with Developer to  see how the pipeline is mapped between steps. Important! The SOAP specification states explicitly that the recipient of a SOAP  message must return a SOAP fault anytime it fails to process the submitted message  successfully. 
  • 137. SOAP Developer’s Guide Version 7.1.1 137 E Creating Custom SOAP Processors Custom processor that drops messages into queues Note: If you want to execute this service from Developer, enable the  acquireSOAPMessage step at the top of the flow. This step generates soapRequestData and  soapResponseData objects, which simulate the pipeline that this service would receive  from the SOAP message handler. If you want to execute this service via the SOAP  message handler (that is, from a client), disable acquireSOAPMessage. # Description Step 1 Extract data from SOAP request message. This sequence retrieves required pieces  of information from the message by extracting the header and body elements  from soapRequestData and querying the results. This example expects a  SOAP message that is structured as follows:
  • 138. E Creating Custom SOAP Processors 138 SOAP Developer’s Guide Version 7.1.1 To extract information from the message, this service executes the following  steps: Step Description 1.1 getHeader—This step retrieves the header from soapRequestData. It  returns an XML node that represents the entire header element (that is,  from <Header> to </Header>).  1.2 queryXMLNode—This step extracts specific pieces of control  information from the header by executing the following XQL queries  against the XML node returned by Step 1.1. Var Name XQL Query QU_docType /PMK:postmark/docType/text() QU_priority /PMK:postmark/priority/text() QU_sender /PMK:postmark/sender/text() QU_timeSent /PMK:postmark/tStamp/text() # Description <?xml version="1.0" encoding="UTF-8"?> <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> <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> <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> </SOAP-ENV:Envelope> This service pulls certain control information from the header... ...and extracts the document carried in the body of the message and drops it in a queue
  • 139. SOAP Developer’s Guide Version 7.1.1 139 E Creating Custom SOAP Processors If you examine the queryXMLNode step with Developer, you will see that  it also executes the following query, which extracts the entire Header  node as a String: Var Name XQL Query wholeNode /source() This query is included for debugging purposes. It allows you to  examine the raw XML associated with the Header node. If you were to  put this service into production, you would omit this query. 1.3 getBody—This step retrieves the body from soapRequestData. It returns  an XML node that represents the entire body element (that is, from  <Body> to </Body>).  1.4 queryXMLNode—This step extracts the contents of the body element by  executing the following XQL query against the XML node returned in  Step 1.3. Var Name XQL Query QU_doc //source() Step 2 Log extracted data in a queue. This sequence generates a timestamp and drops  the information extracted by Step 1 into a queue (in this example, this action is  simulated by a MAP step). It produces a “receipt” that reports the name of the  queue into which the message was dropped. If the message is rejected by the  queue, the receipt will contain an error message. # Description
  • 140. E Creating Custom SOAP Processors 140 SOAP Developer’s Guide Version 7.1.1 Step 3 Compose SOAP Response Message. This sequence checks the result generated by  Step 2. If Step 2 returns an error, this step generates an error message and  throws an exception (which causes a SOAP fault to be returned to the client).  Otherwise, it generates a response message that is structured as follows: To produce the response message, this service executes the following steps: Step Description 3.1.1 documentToXMLString—This service converts the receipt document to  an XML String.  3.1.2 xmlStringToXMLNode—This step converts the XML String to an XML  node. (Recall that to add a body entry to soapResponseData, you must  place the entry in the pipeline as an XML node.) 3.1.3 addBodyEntry—This step adds the body entry to soapResponseData. Step 4 FOR DEBUG ONLY. This step converts the contents of soapResponseData to a  String using the soapDataToString service. This allows you to examine the  finished message with Developer, which is useful during testing and  debugging. You would not include this step in a production service. # Description <?xml version="1.0" encoding="UTF-8"?> <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: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> </SOAP-ENV:Envelope> The receipt from the queue is returned in the body of the SOAP response message
  • 141. SOAP Developer’s Guide Version 7.1.1 141 E Creating Custom SOAP Processors Registering a SOAP Processor To make a custom SOAP processor available for use, you must register it on the  Integration Server. This action associates your processor with a particular directive and  makes it known to the SOAP message handler. (If your server runs in a cluster, be sure to  register it on every server in the cluster.) To register a SOAP processor, you execute the service, pub.soap.processor:registerProcessor. To  ensure that your SOAP processor is registered whenever the server is restarted, we  recommend that you include pub.soap.processor:registerProcessor in a startup service. If you execute this service and examine the contents of finishedMessage on the  Results panel, you will see a SOAP message similar to the following: Note: If you register your SOAP processor using a startup service, make sure that the  package in which the startup service resides designates the WmPublic package as a  dependency. This will instruct the server to load WmPublic before it loads your  package and ensure that pub.soap.processor:registerProcessor is available when your  startup service executes. # Description
  • 142. E Creating Custom SOAP Processors 142 SOAP Developer’s Guide Version 7.1.1 How to Register a SOAP Processor The following describes the general steps you take to register a SOAP processor. 1 Create a flow service that invokes pub.soap.processor:registerProcessor. Set the following  input variables for this service: 2 Run the flow service that you just created and verify that it executed successfully. If a  processor is already registered under the name you specified in directive, the service  will throw an exception. In this case, you must either register the new processor  under a different name, or, if you want the new processor to replace the current one,  you must unregister the current processor (with pub.soap.processor:unregisterProcessor)  and then register the new one. 3 Add the flow service to the startup list. To ensure that your processor is automatically  registered with the SOAP message handler whenever the server is started, we suggest  that you make it a startup service.  Set... To... directive A String specifying the process directive that you want to  assign to the processor.  Note: Use only letters, digits, or the characters -_.!~*'( ) in  the name you specify in directive. svcName A String specifying the fully qualified name of the service  that you are registering as a SOAP processor.  descriptiveName Optional. A String that contains a descriptive comment for  this SOAP processor. This comment is shown when you run  the utility service pub.soap.processor:list to get a list of the  registered SOAP processors. validateSoapMessage Optional. A String indicating whether the SOAP message  handler is to validate the SOAP messages that this processor  sends and receives. This setting overrides the server’s global  watt.server.SOAP.validateSOAPMessage setting. 
  • 143. SOAP Developer’s Guide Version 7.1.1 143 E Creating Custom SOAP Processors Viewing the List of Registered SOAP Processors If you want to view the list of currently registered SOAP processors, execute  pub.soap.processor:list from Developer. This service returns a document list called list that  contains a document (an IData object) for each SOAP processor registered on the server.  List of registered SOAP processors Each document in list will contain the following keys: Key Value directive A String containing the process directive that is assigned to the  SOAP processor. svcName A String containing the fully qualified name of the service that  functions as the SOAP processor.  descriptiveName A String containing the descriptive comment that was given to the  SOAP processor when it was registered. This element will be  empty if the processor was not registered with a descriptive  comment. validateSoapData A String indicating whether the SOAP message handler validates  the SOAP messages that this processor sends and receives.
  • 144. E Creating Custom SOAP Processors 144 SOAP Developer’s Guide Version 7.1.1 Deactivating a Registered SOAP Processor To deactivate a registered SOAP processor, execute pub.soap.processor:unregisterProcessor and  specify the process directive of the processor that you want to deactivate. This action will  remove the processor from the list of registered SOAP processors and make it  inaccessible to the message handler. You can also use this service when you want to change the registration information for a  SOAP processor. For example, if you wanted to change a processor’s directive, service, or  descriptive name, you would unregister the processor and then re‐register it with the  new information.
  • 145. SOAP Developer’s Guide Version 7.1.1 145 Index A accessing custom processor 132 default processor 38 RPC Client 64 RPC processor 116 actor attribute example of 13, 14 general usage 13, 14 addBodyEntry service 41, 46, 51, 54, 134, 140 addHeaderEntry service 41, 46, 51, 53, 134 adding content to a SOAP message 41, 45, 51, 53, 54, 134, 140 addTrailer service 41, 51, 134 application data 14 architecture of SOAP facility 20 attributes (actor, mustUnderstand) 13, 14 B behavior default processor 38 RPC processor 118 binding extensions 21 Body element adding content to 45, 54 basic structure of 10 example of 15 Fault codes 16, 78 requirements of 14 building a custom processor example 136 general steps 133 building a target service example 42, 120 general steps 40 building SOAP messages example 52 general steps 50 building solutions receive messages 30 send messages 35 business payload 14 C classname element 79 composing SOAP request 50, 52 SOAP response 41, 45, 134, 140 conventions used in this document 7 createSoapData service 50, 52 creating SOAP messages 50 custom processors accessing 132 addressing messages to 132 example of 136 how to build 133 inputs and outputs 132, 133 overview of 132 registering on server 132, 134, 141 returning errors from 135 unregistering on server 144 D data types supported by message coder 101 XML to Java conversion 102, 109 data-retrieval services using in custom processors 133, 137 using in target service 40, 43 deactivating a SOAP processor 144 decoding SOAP RPC parameters. See message coder decomposing SOAP messages. See extracting data from SOAP messages default processor accessing 38 addressing messages to 38 behavior of 38 building target services for 40 inputs and outputs 39 selection of target services 38 use of QNames 38 use of universal names 38 detail element 16, 79, 80
  • 146. Index 146 SOAP Developer’s Guide Version 7.1.1 developing solutions that receive messages 30 that send messages 35 documentation additional 8 conventions used 7 feedback 8 documentToXMLString service 41, 45, 46, 51, 134, 140 E encoding SOAP RPC parameters. See message coder encodingStyle attribute 123 enforceMsgPartNS parameter 113 Envelope element basic structure of 10 namespace declarations 11 requirements of 10 error handling in custom processors 135 in target services 41, 119 list of Fault codes 77 explicit universal names 33 extracting data from SOAP messages 40, 43, 61, 71, 133, 137 F Fault codes example of 17, 80 list of 77 structure of 16, 78 testing for 61, 71 faultactor element 16, 79 faultcode element 16, 78 faultstring element 16, 79 feature overview 20 fetching data from a SOAP message 40, 43, 61, 71, 133, 137 find service 35, 134 G getBody service 40, 44, 58, 133, 139 getBodyEntries service 58 getDocument service 58 getHeader service 40, 58, 133, 138 getHeaderEntries service 58 getQName service 134 getTrailers service 40, 58, 133 H Header element adding content to 46, 53 attributes of 13, 14 basic structure of 10 example of 12 namespace declarations 12 requirements of 12 HTTP, using to send SOAP messages 56 I implicit universal names 33 invoking a remote procedure call 64 J Java data types 101 Java-to-XML data type mapping 109 L list service for registered processors 143 for universal names 35 local names 31, 32 M message coder data type mapping 101 data-type mappings for decoding 102 data-type mappings for encoding 109 decoding Object parameters, RPC client 74 decoding Object parameters, RPC processor 124 decoding RPC parameters, RPC client 73 decoding RPC parameters, RPC processor 123 decoding String parameters, RPC client 74 decoding String parameters, RPC processor 124 decoding structures and arrays 74, 125 decodingundeclaredparameters,RPCprocessor 125 encoding Object parameters, RPC client 72 encoding Object parameters, RPC processor 128 encoding RPC parameters, RPC client 71 encoding RPC parameters, RPC processor 127
  • 147. Index SOAP Developer’s Guide Version 7.1.1 147 encoding String parameters, RPC client 72 encoding String parameters, RPC processor 128 encoding structures and arrays 72, 128 multi-referenced parameters 73, 74, 125, 128 usage by RPC client 71 usage by RPC processor 123 validating parameters, RPC client 72 validating parameters, RPC processor 126 message element 79 message handler relationship to SOAP processors 21 response generated by 22 role in overall architecture 20, 21 validation performed by 21 message-composition services using in a custom processor 134, 140 using in target service 41, 45 using to compose a new message 51 messages basic structure of 10 Body element 14 building solutions that receive messages 30 building solutions that send messages 35 composing 50 Envelope element 10 extracting data from 40, 43, 61, 71, 133, 137 Header element 12 payload 14 posting to the webMethods Integration Server 21 receiving 20 sending 23, 55 sending RPC 24, 64 testing for Faults 61, 71 validation of 22 multi-referenced parameters configuring encoding behavior 113 decoding 74, 125 encoding 73, 128 mustUnderstand attribute 13 causing addHeaderEntry utility to fail 87 N namespace names 31 namespaces enforcing in header and body entries 51, 113 for SOAP elements 11 usage in Envelope 11 usage in the Header 12 usage in universal names 31 nodes adding to SOAP messages 41, 45, 46, 51, 53, 134, 140 extracting data by querying 40, 44, 58, 133, 138, 139 generating 41, 45, 46, 51, 53, 134, 140 returned by data-retrieval services 40, 44, 58, 133, 138, 139 validating contents of 40, 134 normalization expected of QNames 39, 117 universal names 32 O overview of SOAP 10 P parameters, watt.server.SOAP 112 payload 14 posting SOAP messages to the webMethods Integration Server 21 process directive assigning to custom processor 141 deactivating 144 description of 30 for custom processor 132 for default processor 38 for RPC processor 116 modifying 144 position in URL 21 processor:list service 143 processor:registerProcessor service 141 processor:unregisterProcessor service 144 processors. See SOAP processors program code conventions in this document 7 Q QNames extracting from message 134 invoking services by 134 used in SOAP RPC 116, 117, 118 qualified names. See QNames queryXMLNode service 40, 44, 58, 133, 138, 139
  • 148. Index 148 SOAP Developer’s Guide Version 7.1.1 R receiving messages building solutions that receive messages 30 overview of 20 via custom processor 132 via default processor 38 via RPC processor 116 registering a custom processor 132, 134, 141 registerProcessor service 141, 142 remote procedure call decoding output parameters 73 encoding input parameters 71 invoking 64 processing response 71 request messages composing 50 processing 40, 133 response messages composing 41, 134 processing 61, 71 retrieving data from SOAP messages 40, 43, 61, 71, 133, 137 RPC client 64 calling procedures remotely 64 RPC message example of 116 QName 116, 117 response namespace 117 results example 117 RPC processor accessing 116 addressing messages to 116 decoding parameters. See message coder encoding parameters. See message coder receiving a SOAP message 118 target service criteria 119 S schemas governing Envelope structure 11 validating application data against 40, 134 validating messages against 21 sending SOAP messages building solutions that send messages 35 example 59 general steps 56 overview of 23 sending SOAP RPC messages overview of 24 using the RPC client 64 ser-root prefix 117 server parameters watt.server.SOAP.directive 112 watt.server.SOAP.enforceMsgPartNS 113 watt.server.SOAP.useMultiReference 113 watt.server.SOAP.validateSOAPMessage 112 serviceStackTrace element 79 SOAP directive, changing 112 SOAP envelope trailers 17 SOAP extensions 21 SOAP faults. See Fault codes SOAP message handler. See message handler SOAP processors custom processors 31, 132 default processor 31, 38 displaying list of 143 overview of 30 posting messages to 21 registering on server 141 role in overall architecture 20, 21, 22 RPC processor 31, 116 supplied by webMethods 31 unregistering 144 soapData object adding content to 51 creating 50, 52 soapDataToString service 46, 54, 61, 140 soapHTTP service 55, 56 soapRequestData creation by message handler 22 passed from default processor 39 passed to custom processors 132, 133 soapResponseData composing 41, 45, 134, 140 creation by message handler 22 passed from default processor 39 passed to cusom processors 132, 133 soapRPC client composing the remote procedure call 69 invoking 64 processing output values 67 stackTrace element 79, 119 submitting a remote procedure call 68
  • 149. Index SOAP Developer’s Guide Version 7.1.1 149 T target services assigning universal names to 41 example of 42, 120 how to build 40 returning errors from 41, 119 selection process 38 signature requirements 40 using with RPC processor 119 trailers example of 17 usage 17 troubleshooting information 8 typographical conventions in this document 7 U Universal Name Registry finding services in 35 overview of 35 services that operate on 35 viewing contents of 35 universal names assigning to a service 34 assigning, editing, and viewing 34 finding service name for 35, 134 implicit vs explicit 33 local portion of name 32 namespace portion of name 31 overview of 31 removing from a service 35 Universal Name Registry 35 usage by default processor 38 viewing name assigned to service 34 universalName:find service 35, 134 universalName:list service 35 unregistering a SOAP processor 144 unregisterProcessor service 142, 144 URLs for custom SOAP processors 132 for the default SOAP processor 38 for the RPC SOAP processor 116 format of 21 used to address SOAP processors 21 useMultiReference parameter 73, 113, 128 V validate service 40, 134 validateSOAPMessage parameter 112 validating application data 40, 134 SOAP Envelope 22 SOAP RPC parameters 126 VersionMismatch fault code 21 viewing list of registered processors 141, 143 list of universal names 35 W watt.server.SOAP.directive 112 watt.server.SOAP.enforceMsgPartNS 113 watt.server.SOAP.useMultiReference 73, 113, 128 watt.server.SOAP.validateSOAPMessage 112 X XML data types 101 XML nodes. See nodes XML, encoding and decoding. See message coder xmlStringToXMLNode service 41, 45, 46, 51, 134, 140 XML-to-Java data type mapping 102
  • 150. Index 150 SOAP Developer’s Guide Version 7.1.1