Syntax:

com.ibi.agents.XDAddAttachmentFromFileAgent

Description:

This service adds a new attachment with the contents determined by the contents of a file. This service is convenient to provide binary data without first going through a Java character set encoding. The attachment headers are specified by the special registers of type HDR in the MIME Header Namespace.

There are also four parameters to specify the most common MIME headers. When used, these parameters override special registers of the same name. Notice the value of the Content-ID header is taken as is, so the value must contain the surrounding angle brackets. For example, a valid value for Content-ID might be <cid>. This service follows the OnSuccess edge upon successful execution, otherwise it follows OnError.

Parameters:

Syntax:

com.ibi.agents.XDAddAttachmentAgent

Description:

This service adds a new attachment with the contents determined by the value of a string expression. The Java Character Set parameter specifies how the Java characters in the string are converted to bytes in the body of the attachment. The attachment headers are specified by the special registers of type HDR in the MIME Header Namespace.

There are also four parameters available to specify the most common MIME headers. When used, these parameters override special registers of the same name. Notice the value of the Content-ID header is taken as is, so the value must contain the surrounding angle brackets. For example, a valid value for Content-ID might be <cid>. This service follows the OnSuccess edge upon successful execution, otherwise it follows OnError.

Parameters:

Syntax:

com.ibi.agents.XDAttachOps

Description:

This service performs operations on document attachments.

Parameters:

Syntax:

com.ibi.agents.XDAttachmentToDocAgent

Description:

This service finds an attachment and makes it the body of the document. The attachment can be selected by index or by Content-ID. If the Attachment Number is specified, it takes precedence over the Content- ID. The attachment index is base 0. If present, the Content- ID must NOT contain the surrounding angle brackets.

For example, the value cid for the Content-ID parameter will match an attachment with a Content-ID header equal to <cid>. The Header Namespace is the special register namespace where MIME headers for the selected attachment will be stored. The attachment will be stored as bytes if the Keep Document Flat parameter is enabled. Otherwise, the attachment will be parsed as XML. If the attachment is itself a Multipart, then the document will contain the parse of the Main Body Part and the other parts will appear as document attachments.

The MIME headers of the Main Body Part will be saved as registers in the Main Body Part Header Namespace. This is needed to keep them distinct from the Multipart headers. The Delete Attachment parameter determines what to do with the selected attachment when it is not a Multipart: the attachment can be preserved or deleted. This service follows OnSuccess upon successful execution, otherwise, it follows fail_notfound if the attachment cannot be found, or it follows fail_operation if there is another error.

Parameters:

Syntax:

com.ibi.agents.XDCorsAgent

Description:

This service implements the server-side processing of Cross-Origin Resource Sharing (CORS) as described in http://www.w3.org/TR/cors/.

Normally, browsers forbid cross-origin requests for security reasons. CORS specifies a mechanism that allows browsers to make cross-origin requests to resources that opt in to provide access. CORS defines a set of HTTP headers and the rules to process them. Most common browsers implement CORS natively. It is expected that the user agent making the request will be a browser. The CORS service implements the server-side rules to respond to CORS requests received by an nHTTP listener.

If the request is simple (such as GET, HEAD, or POST), then the user agent (for example, the browser) can make the request directly. The user agent adds the Origin header to indicate which site is asking for this resource. The syntax of an origin is:

scheme "://" host [ ":" port ]

The same syntax is used to configure the allowed origins in the service.

If the request is not simple, then the user agent must send a pre-flight request before the actual request to authorize it. The pre-flight request is an OPTIONS request for the same URL. The Access-Control-Request-Method header indicates the method of the actual request (for example, PUT). The optional Access-Control-Request-Headers header indicates which headers will be used in the actual request. Depending on the response of the pre-flight request, the user agent can abort or make the actual request following the same rules as a simple request.

The CORS service analyzes the request, and depending on its configuration, will report one of the following results:

• The request is allowed (allowed).
• The request is not allowed (notallowed).
• The request is not CORS compliant (notcompliant).

In accordance with the specification, the CORS service adds the CORS response headers only if the request is allowed. The new headers appear as Special Registers (SREGs) in the Response Header Namespace.

The CORS service sets the output document of an OPTIONS request to a zero-length byte array. This will return an empty body with Content-Length equal to 0. This is the most appropriate result, but an application can modify the output document afterwards if necessary. For other requests, the CORS service returns the input document as the output document. Unlike the headers, the output document will be the same irrespective of the actual outcome (allowed, notallowed, or notcompliant).

The nHTTP listener must be configured carefully to make CORS processing possible. The OPTIONS Handling property must be set to event. This instructs the listener to pass the request to the channel instead of responding directly. The Request Header Namespace and the Response Header Namespace must not be none, and they must be different from each other. This makes the request headers available to the CORS service, and allows the response headers be sent with the response. Of course, the Excluded Headers property should not list the CORS headers. The HTTP Response Code must be 200 for a CORS pre-flight response. The Authentication Scheme and the Authentication Realm properties should be considered carefully. CORS is a mechanism used to relax security. It does not replace the need for user credentials to protect sensitive data.

Parameters:

The following table describes the parameters for the Cross-Origin Resource Sharing Service.

Parameter	Description
Allowed Origins	List of origins that are allowed access to the resource. Leave empty or enter * to allow all origins. The syntax of an origin is: scheme "://" host [ ":" port ] This property is used to validate the Origin header in the request and influences the value of the Access-Control-Allow-Origin header in the response. The return value of the Access-Control-Allow-Origin header will be * if the Allowed Origins is * and Supports Credentials is false.
Allowed Methods	Comma-separated list of HTTP methods that are supported by the resource. Leave empty to allow all methods. This is used to validate the Access-Control-Request-Method header in the pre-flight request and to initialize the Access-Control-Allow-Methods header in the pre-flight response.
Supported Headers	Comma-separated list of HTTP header field names that are supported by the resource. Leave empty to claim support for all headers. This is used to validate the Access-Control-Request-Headers header in the pre-flight request and to initialize the Access-Control-Allow-Headers header in the pre-flight response.
Exposed Headers	Comma-separated list of HTTP header field names of headers (other than the simple response headers) that the resource might use and can be exposed. This is used to initialize the Access-Control-Expose-Headers header in the response of the actual request.
Supports Credentials	Indicates whether the resource supports user credentials in the request. This is used to initialize the Access-Control-Allow-Credentials header in the response. Notice the return value of the Access-Control-Allow-Origin header will never be * for a resource that supports credentials.
Max Age	Specifies the amount of seconds the user agent (for example, the browser) is allowed to cache the result of the pre-flight request. The value 0 means unbounded. This is used to initialize the Access-Control-Max-Age header in the response of the pre-flight request.

Edges:

The edges returned are described in the following table.

Edge	Description
success	The message was successfully analyzed. The cors Special Register contains the result.
fail_parse	An iFL expression could not be evaluated.
fail_operation	The service is not executing a request received by an nHTTP listener.

Special Registers:

The following table describes the Special Register (SREG) that is assigned upon a successful execution.

Special Register	Description
cors	The outcome of analyzing the request. This will be one of the following values: allowed notallowed notcompliant Note: These values are lowercase and do not contain any spaces.

GET /app/page1 HTTP/1.1
Host: example.com

GET /app/page1 HTTP/1.1
Host: example.com
Origin: http://host.com

GET /app/page1 HTTP/1.1
Host: example.com
Origin: http://host1.com

Access-Control-Allow-Origin: http://host1.com
Access-Control-Expose-Headers: RespHdr1,RespHdr2
Access-Control-Allow-Credentials: true

OPTIONS /app/page1 HTTP/1.1
Host: example.com
Origin: http://host1.com

OPTIONS /app/page1 HTTP/1.1
Host: example.com
Origin: http://host1.com
Access-Control-Request-Method: HEAD

OPTIONS /app/page1 HTTP/1.1
Host: example.com
Origin: http://host1.com
Access-Control-Request-Method: GET
Access-Control-Request-Headers: ReqHdr1,ReqHdr2

Access-Control-Allow-Origin: http://host1.com
Access-Control-Allow-Methods: GET,POST
Access-Control-Allow-Headers: ReqHdr1,ReqHdr2,ReqHdr3
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 30

Syntax:

com.ibi.agents.XDAttachmentFromDocAgent

Description:

This service adds a new attachment with the contents determined by the input document. The attachment headers are specified with user parameters. The name and value of the user parameter become the name and value of the header. Notice the value of the Content-ID header is taken as is, so the value must contain the surrounding angle brackets.

For example, a valid value for Content-ID might be <cid>. The Attachment Type parameter specifies the attachment Content-Type. If the Attachment Type is omitted, a Content-Type is chosen based on the document data:

• application/binary if the document contains bytes
• text/plain if the document is flat
• application/xml otherwise

The optional Attachment Name parameter controls the name sub-parameter of the Content-Type header. The Content-Type name can also be given directly in the Content-Type header value if desired.

The Body Result parameter specifies what to return in the output document: keep copies the input document to the output document, empty returns an empty document instead. This service follows OnSuccess upon successful execution, otherwise it follows the fail_attach edge.

Parameters:

Syntax:

com.ibi.agents.XDCookieAgent

Description:

This service adds a cookie to the HTTP responses, enabling them to retain stateful information.

Parameters:

Syntax:

com.ibi.agents.XDHTTPEmitAgent

Description:

This service is a general HTTP emitter for use within the service stack. The document is posted using HTTP to a designated server.

Parameters:

The result of the post appears in the <native> section of the <emitstatus> result. If the Return parameter value is STATUS, the status message is always generated. If it is RESPONSE (the default) the actual information returned from the POST is emitted, except in the cases of an error in which case the status information is emitted. The POST is considered successful if the POST can reach its destination and a 200 status is received. A successful return response is considered to be XML if the first character is a <. Otherwise, a flat document is created.

Example:

The following is an example of configuration settings for an HTTP Emit service object in iIT Designer:

A simple way to test your HTTP Read service is to first configure a channel that uses an HTTP listener as the inlet and a File emitter as the outlet to examine the messages that are received by the listener. Your HTTP listener configuration settings would look similar to the following example, where an HTTP port and a document root are specified.

After you deploy and start the channel with the HTTP listener and File emitter, you can test run your process flow, which contains an HTTP Emit service object. You must supply an incoming document with the appropriate content (for example, HTML):

<html>
  <head>
    <title>my iWay http</title>
   </head>
     <body> Testing HTTP Emit Service! </body>
</html>

If the service runs successfully, you will receive this HTML document in the output folder that is specified by your File emitter. The HTTP listener channel picks up the document that is emitted by the HTTP Emit service.

Syntax:

com.ibi.agents.XDNHttpEmitAgent

Description:

Emits nHTTP messages to a client without interrupting a configured business process. For more information, see the iWay Service Manager Protocol Guide.

Parameters:

Parameter	Description
Configuration Parameters
Target URL (required)	URL that is used to post this information.
HTTP Client Provider (required)	HTTP client Provider that is used to manage connections for this emitter.
Cookie Store Name	Allows thread-specific management of cookies. If not specified, a cookie store global to the HTTP Client provider will be used.
Action Method	Select one of the following supported methods from the drop-down list: DELETE GET - will send a data-encoded request to the configured URL. HEAD - will send a request to the configured URL and return a status document. POST - sends the current document as a request entity. PUT
Request Content Type	Overrides content type of response. Select one of the following options from the drop-down list: application/EDI-X12 application/EDIFACT application/XML text/html text/plain
User ID	User ID for Basic Authentication challenges.
Password	Password for Basic Authentication challenges.
Domain	Domain for NTLM authentication challenges. Note that to use NTLM, you must enable connection persistence.
Request Header Namespace	Special register namespace from which HTTP headers for the outgoing request will be taken. Choose Default Namespace to send HDR type registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be sent as HTTP headers. Supply a namespace prefix here to indicate which headers to send. Default Namespace - Sends HDR type registers with no namespace prefix. none - Means that no special registers will be sent as HTTP headers.
Request Main Part Header Namespace	Special register namespace from which MIME headers for the outgoing request will be taken. Provide a prefix to control the request Main BodyPart headers in the presence of attachments. Selecting none means that no special registers will be sent as MIME headers.
Response Header Namespace	Special register namespace into which HTTP headers from the incoming response will be saved. Choose Default Namespace to create special registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be created. Default Namespace - Creates special registers with no namespace prefix. Pick one - Supply a namespace prefix here to indicate header namespace.
Excluded Headers	A comma delimited list (case insensitive) of headers that should not be sent with the request, even if they are found in the request header namespace.
Ask for Compressed Response	If set, requests will set the Accept-Encoding header to indicate that that the client can accept a compressed response, as described in RFC-2616. If the response has a compressed content encoding, the client will automatically inflate. deflate either gzip none
Compress Request	If set, the request entities will be compressed using the selected encoding and the content-encoding header will be set accordingly. deflate gzip none
Release Connection Immediately	If set to true, then the connection will be released to the connection pool immediately. This is the default. If set to false, then the connection identifier is stored in the httpclient-key special register and the HTTP Client Manager agent must be called later to release the connection explicitly. The main reason to retain the connection is to reuse it for streaming of other services.
Maximum HTTP Client Manager Delay	Maximum time the HTTP Client Manager can take to handle a particular connection before it is automatically aborted. The format is [xxh][xxm]xx[s]. The default is 60 seconds.
Try Expect/Continue Handshake?	If set to true, the client will send the HTTP Expect: 100-continue header and await HTTP 100 response before sending the request body. The default is false.
Chunk Encoded Request?	If set to true, request entity will be sent with chunk encoding. The default is false.
Maximum Request Size	Maximum size, after compression, of a request entity that can be sent with this emitter. A value of 0 means no maximum and if no value is specified, the parameter defaults to 256KB.
Maximum Response Size	Maximum size of a response entity that can be received by this emitter. 0 means no maximum and blank will default to 256KB.
TCP Properties
Persistence	If set to true, ask the server to maintain the connection. The default is false.
Response Timeout value in Seconds (required)	The value in seconds to wait for a response before generating an error.
Agent Specific Parameters
Return (required)	URL to post this information to, for example, http://thehost:9876. Choose: input - to return input document status - or an XML document with transaction parameters and status response - to capture output from the server
Preemitter	If set to true, (default) the preemitters will not run.
Response Wrapper Tag	The tag name with which to wrap the response if the response is non-XML and must be XML.
Response Base64 Encoded	If set to true, the response will use Base64 encoding. False is the default.

Syntax:

com.ibi.agents.XDHTTPReadAgent

Description:

This service reads an HTTP source using HTTP GET and returns a result. The GET facility input accepts a URL in the incoming document and issues an HTTP GET through that URL. The transform business service and standard output can accept and operate upon this output. It is presumed that some output is returned, otherwise an error is generated.

In a use case scenario, the HTTP Read service can be part of an architecture for a web search engine, similar to the Google search engine. The service could be used to traverse or spider the contents of webpages for indexing purposes.

Parameters:

The input document might be the following assuming that the tagname parameter is set to inurl:

<?xml version="1.0"?>
<inurl>http://localhost:1234/xmlone.xml</inurl>

Example:

The following is an example of configuration settings for an HTTP Read service object in iIT Designer:

A simple way to test your HTTP Read service is to first configure a channel that uses an HTTP listener. Your HTTP listener configuration settings would look similar to the following example, where an HTTP port and a document root are specified.

After you deploy and start the channel with the HTTP listener, you can test run your process flow, which contains an HTTP Read service object. You must ensure that the file name you supply within the <Test> tag of your incoming document is valid and is also contained within the document root folder specified for your HTTP listener configuration settings. A sample HTTP read incoming document can have the following format:

<Test>http://localhost:1234/index1.htm</Test>

If the service ran successfully, you will receive the contents of index1.hml as the output from the service. For example:

Syntax:

com.ibi.agents.XDReSTRouteAgent

com.ibi.agents.XDReSTRouteReviewer

iIT Service Object:

http: HTTP ReST Routing Service

Description:

This service routes a Representational State Transfer (ReST) request to a process flow based on the request method and path. An HTTP ReST Routing Reviewer (com.ibi.reviewer.XDReSTRouteReviewer) is also provided, which shares the same parameters as the service.

The main purpose of these components is to identify a process flow to execute, given a URI path and the type of the HTTP request. The name of the process flow will be stored in a special register (SREG). In addition to this routing function, some elements in the URI path, and all keys and values in the URI query string, will be stored as SREGs. This functionality will be made available as a service for use within a process flow, but also as a reviewer. This allows for earlier execution in the processing stage to allow conditional routing to handle the execution of the identified process flow.

The service uses an XML document whose structure corresponds to the elements in the path. This XML document has the following structure:

<route>
  <verb type="GET">
    <step type="literal" value="master">
      <step type="literal" value="vendor">
        <step type="regex" value="[0-9]+" flow="vendorRequest" sreg="true">
         <step type="literal" value="item" flow="vendorAllItemsRequest">
           <step type="regex" value="[0-9]+" flow="vendorItemRequest" sreg="true">
              <sreg name="extrareg1" value="something"/>
              <sreg name="extrareg2" value="somethingelse"/>
              <step type="literal" value="allproperties"
               flow="vendorItemAllProperties"/>
           </step>
           <step type="default" flow="VendorItemUnknownRequest"/>
         </step>
       </step>
     </step>
   <step type="default" flow="UnknownMasterRequest"/>
  </step>
 </verb>
</route>

A schema will follow for this XML document.

In this section, the individual components of the URI path are called path elements and the <step> elements in the XML document are called steps.

Each step can match a path element. How a step is matched to a path element depends on its type (as indicated by the type attribute of the step element).

1. A literal step matches if the value of the step (as indicated by the value of the value attribute of the step element) matches the path element exactly.
2. For a regex step, the value of the step is a regular expression. A regex step matches if the regular expression matches the path element.
3. A default step matches if no other step matches.

The search process starts at the verb node that corresponds to the type of the HTTP request. For the first element in the path, each step child node of the verb node is checked to see if it matches the path element. The first step that matches is taken. This is repeated for the second path element, looking at the step children of the first step, and so on, until the final path element is reached.

Note: The order of step nodes in the routing XML document is very important.

Consider the following example, which shows a path element "1234" and two step nodes:

<step type="regex" value="[0-9]+" flow="generalIntRequest"/>
<step type="literal" value="1234" flow="specific1234Request"/>

In this scenario, the regex step is always taken, since it is seen first and also matches 1234, even though the literal step is an exact match.

If a step has the sreg attribute set to true, a Special Register (SREG) will be created using the previous path element as the SREG name and the current path element as the SREG value.

When the final path element is reached, the value of the flow attribute for the last step found is the name of the process flow to be executed. If, for any path element, no matching step can be found, the service will return the fail_notfound edge.

For example, using the document above, consider that the following URI is provided:

/master/vendor/1428/item/2345/allproperties

In this scenario, the target register is set to vendorItemAllProperties and the following SREGs are set:

• vendor=1428
• item=2345

Additional SREGs to set for the final step can be specified by adding <sreg> nodes as children of the step node. For example, consider the following URI:

/master/vendor/1234/item/2345

The target register would be set to vendorItemRequest, the SREGs as shown above, and the following additional SREGs would be set:

• extrareg1=something
• extrareg2=somethingelse

If the incoming URI includes a query string, the service will store the key-value pairs in the query string as SREGs. Query string parameters will not be used in the route search.

To facilitate debugging, the XML schema will include two additional attributes:

1. The <route> node can have a verbose attribute, which when set to true indicates that the service will generate additional tracing at the iSM DEBUG level, with details of the route search process.
2. Any <step> node can have a name attribute, the value of which, if present, will be included in the verbose tracing to make it easier to correlate traces to the routing tree.

Step Attributes:

Attribute	Description
type	The type of attribute value: literal. Value is a literal, exact match required. ci_literal. Case insensitive literal. regex. Regular expression. default. Any other (must be last in a compare set).
value	A compare value of type in the type attribute.
flow	Name of a process flow if this is the final step (iFL allowed).
sreg	If true, then a Special Register (SREG) will be created using the value of the previous path element as the key and this value of the current path element as the register value.
role	The user must have this role to descend on this step.
name	A node name used in tracing.

Inputs:

The service is agnostic as to the input. The service operates on the incoming URL.

Outputs:

If a process flow is found for this path, then the input will be output. In any other case, the output will either be the input document or an iSM status/error document, as determined by the Output Type parameter for this service.

Parameters:

Parameter	Description
Route File Path (required)	The path to the XML file describing the route. The file is loaded when the service is first executed and remains in effect until the listener is restarted.
ReST Verb (required)	The HTTP verb (DELETE, GET, POST, or PUT). In nHTTP this is in the SREG called reqType.
URI (required)	The URI of the incoming HTTP request. In nHTTP, this is stored in the SREG called url. This may include a path and a query string. Note: This is slightly different from the Object parameter in the prototype service.
Flow Name Register (required)	An SREG of this name will be created with the name of the process flow to run.
Route Namespace	SREG namespace prefix to use when creating SREGs from path steps, including the process flow name register. Applies to the routing portion of the URL.
Query Namespace	SREG namespace prefix to use when creating SREGs from the query string portion of the URL. Defaults to the same as the Route Namespace. Using a separate namespace can allow these registers to be passed and managed as a group.
Output Type	Determines in the event of a routing error, what document should be output from this service. Select one of the following document types: status. A standard iSM error document. input. The original input document.

Edges:

Parameter	Description
Success	A process flow was located.
fail_notfound	No process flow was located.
fail_parse	Unable to process configuration parameters, which is most likely an iFL error.
fail_route	Other failure specific to this agent (for example, unable to locate or parse the routing file).
fail_security	A role does not match, meaning that this user is not permitted to use this URL (security trigger flow runs in iSM Version 6.1.9).

ReST Process Flow Message:

When a non-POST verb in encountered by nHTTP, a default message is generated. The schema for this message is located in the following directory:

<iwayhome>/etc/manager/extensions/iwxnhttp/misc/doc

From time to time, iWay Software may add additional, non-conflicting elements to this schema in future releases.

The input document to the process flow holds the parsed information from the arriving HRRP input, including all headers and the URL split up for use.

For example (spacing for display purposes only):

<http user="auto" type="GET">
 <parms>
  <parm name="ibse-port">9000</parm>
  <parm name="Host">clientbox:10000</parm>
  <parm name="Connection">Keep-Alive</parm>
  <parm name="pdm">0</parm>
  <parm name="version">1.1</parm>
  <parm name="Accept-Language">en-AU</parm>
  <parm
name="action">user.req?user=999999999&account=1234567890123456&tranid=tid1234</parm>
<parm name="Accept">text/html, application/xhtml+xml, */*</parm>
  <parm name="User-Agent">Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0)</parm>
  <parm name="url">/user.req?user=999999999&account=1234567890123456&tranid=tid1234</parm>
  

<parm name="ip">127.0.0.1</parm>
  <parm name="source">hostname unknown</parm>
  <parm name="Accept-Encoding">gzip, deflate</parm>
  <parm name="reqType">GET</parm>
 </parms>
 <body />
 <url secure="false">
  <host>clientbox</host>
  <port>10000</port>
  <path>/user.req</path>
  <query>user=999999999&account=1234567890123456&tranid=tid1234</query>
  <queryparms>
   <parm name="user">99999999</parm>
   <parm name="account">1234567890123456</parm>
   <parm name="tranid">tid1234</parm>
  </queryparms>
  <incomingurl>	http:clientbox:1000/user=999999999&account=1234567890123456&tranid=tid1234
  </incomingurl>
  </url>
 <version>1.1</version>
</http>

Using an XML iterator, the process flow can easily step through the <queryparms>, or using standard XSLT, can extract a specific URI value as required. All registers set in the channel are housed in the <http/parms> elements and can be extracted if required.

The user (source of the message) can be authenticated using standard nHTTP services, avoiding the need to do so within the executing process flow.

iWay Functional Language (iFL) Support:

The iFL language used within iSM provides facilities to support RESTful services. Key functions for this support are listed and described in the following table:

Function	Description
_urlparse()	Parses a URL into its component parts, including searching for specific keywords in the query section of the URI.
_token()	Enables extraction of specific portions of the URI as required.

The information extracted by the iFL is represented in the incoming document. The iFL simply makes it possible to look at the URL directly.

For more information on _urlparse() and _token(), see the iWay Functional Language Reference Guide.

Route Step XML Schema Document:

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.iwaysoftware.com/RouteStep" xmlns:tns="http://www.iwaysoftware.com/RouteStep" elementFormDefault="qualified">
    <complexType name="sregType">
    	<annotation>
    		<documentation>
    			Represents a special register to create if its parent
    			step matches the last path element.
    		</documentation>
    	</annotation>
    	<attribute name="name" type="string" use="required"></attribute>
    	<attribute name="value" type="string" use="required"></attribute>
    </complexType>
    <complexType name="stepType">
    	<annotation>
    		<documentation>
    			Represents one step in the URI path for looking up the
    			route. The lookup process attempts to match elements in
    			the path to steps.
    		</documentation>
    	</annotation>
    	<choice minOccurs="0" maxOccurs="unbounded">
    		<element name="sreg" type="tns:sregType"/>
    		<element name="step" type="tns:stepType"/>
    	</choice>
    	<attribute name="type" use="required">
    		<simpleType>
    <restriction base="string">
    				<enumeration value="literal"></enumeration>
    				<enumeration value="ci_literal"></enumeration>
    				<enumeration value="regex"></enumeration>
    				<enumeration value="default"></enumeration>
    			</restriction>
    		</simpleType>
    	</attribute>
    	<attribute name="value" type="string" use="optional">
    		<annotation>
    <documentation>
    				When type is 'literal', the value attribute holds a
    				literal that must match the path element. Type "ci_literal"
    				is similiar, but ignores case when matching the path element.  
    				When type is 'regex', this attribute holds a regular
    				expression to match the path element. When type is
    				'default', this attribute is not used.
    			</documentation>
    		</annotation>

    	</attribute>
    	<attribute name="flow" type="string" use="optional">
    		<annotation>
    			<documentation>
    				The flow to run for this URI path. Will be set into
    				the target special register.
    			</documentation>
    		</annotation>
    	</attribute>
    	<attribute name="sreg" type="boolean">
    		<annotation>
    			<documentation>
    				If true, the value of this path element will be
    				saved as a special register, with key as the value
    				of the previous path element. 
    			</documentation>
    		</annotation>
    	</attribute>
    	<attribute name="name" type="string" use="optional">
    		<annotation>
    			<documentation>
    				Use the name attribute to identify this step in
    				debug tracing.
    			</documentation>
    		</annotation>
    	</attribute>
    	<attribute name="role" type="string" use="optional">
    		<annotation>
    			<documentation>
    				Optionally, the role required to the flow that
					would be run if this were the final element in the URI path. Assumes
					that the user has been authenticated by an iSM auth realm.
				</documentation>
    		</annotation></attribute>
    </complexType>
    <complexType name="verbType">
        <annotation>
        	<documentation>Matches the ReST verb or HTTP method for the current request.</documentation>
        </annotation>
        <sequence>
    		<element name="step" type="tns:stepType" minOccurs="1" maxOccurs="unbounded"></element>
    	</sequence>
    	<attribute name="type" use="required">
    		<simpleType>
    			<restriction base="string">
    				<enumeration value="GET"></enumeration>
    				<enumeration value="POST"></enumeration>
    				<enumeration value="PUT"></enumeration>
    				<enumeration value="DELETE"></enumeration>
    			</restriction>
    		</simpleType>
    	</attribute>
    </complexType>
    <complexType name="routeType">
    	<sequence>
    		<element name="verb" type="tns:verbType" minOccurs="1" maxOccurs="4"></element>
    	</sequence>
    	<attribute name="verbose" type="boolean" use="optional"></attribute>
    </complexType>
    <element name="route" type="tns:routeType"></element>
</schema>

This service is used to terminate the session. The following table lists and describes its parameter.

Parameter	Description
Expire Cookie	Determines how the termination is to be effected. If set to false, it removes the session information from the server. No further action is taken. If set to true, in addition to removing the session information, it sends an instruction to the client to delete the JSESSIONID cookie itself.

The service returns the input document on the success edge.

As a good practice, you can use this service when the application has completed the session, so as to reduce server resources.

Syntax:

com.ibi.agents.XDOAuth1Agent

Description:

This service creates the HTTP Authorization header for OAuth 1.0a as specified in RFC5849. This RFC describes a 3-legged protocol where the user authorizes the client application to access a protected resource hosted by a service provider.

The OAuth 1.0 Authentication supports a variant called the 0-legged protocol where the request is signed without the user credentials. The signature is computed using just the consumer key and the consumer secret. These credentials are obtained once when the application programmer registers his client application with the service provider during development. This service assumes the consumer secret is a private key.

Parameters:

The following table lists and describes the parameters for the OAuth 1.0 Authentication service.

Parameter	Description
HTTPS URL	Request URL used in the computation of the Signature Base String.
HTTP Method	HTTP Method used in the computation of the Signature Base String. Selecting POST will also cause the current document to be hashed to produce the oauth_body_hash.
Header Namespace	Special register namespace where the Authorization HTTP header is stored. If not supplied, the default namespace will be used.
Client ID	The consumer key of the client credentials.
KeyStore Provider	Provider for the keystore containing the client private key.
Private Key Alias	Alias of the private key within the keystore.
Private Key Password	Password for the private key. If left blank, the password for accessing the keystore will be used.

The OAuth Authentication service only creates the Authorization header. The HTTP request must be sent in a separate step, usually with the NHTTP Emit service.

The HTTPS URL and HTTP Method parameters are used in the Signature Base String. They must match the Target URL and Action Method of the NHTTP Emit service. The URL scheme must be HTTPS because an SSL connection is needed to protect the information that is passed in clear. Choosing the POST method also instructs the service to compute a hash of the entity body to be part of the signature. This algorithm was specified by Google in its OAuth Request Body Hash extension.

The Authorization header will be stored in the specified Header Namespace. This parameter should match the Request Header Namespace in the NHTTP Emit Agent. This will ensure that the header is sent with the request. It is possible to use different namespaces, as long as the Authorization register is copied to the Request Header Namespace before the request is sent.

The Client ID is the consumer key supplied by the service provider when the developer registered the client application with the service provider. This serves as the user name for the client application. The service provider uses the client ID to retrieve the public key to validate the signature.

The KeyStore Provider is the name of the provider that holds the client private key. The Private Key Alias and Private Key Password are the Alias and Password for the private key. This key is used as the consumer secret when signing the Authorization header.

The output document is the same as the input document.

For the POST method, the document contains the same data but it will be stored as bytes if it was not already. This is to guarantee the document will not be altered before it is sent because any change to the document would invalidate the signature.

Edges:

The following table lists and describes the edges that are returned by the OAuth Authentication service.

Edge	Description
success	The Authorization header was successfully created.
fail_parse	An iFL expression could not be evaluated.
fail_operation	The operation could not be completed successfully.

Example 1

This example shows the creation of an OAuth 1.0a Authorization header for a GET method. The following table lists the parameter values for the service.

Parameter	Value
HTTPS URL	https://sandbox.api.mastercard.com/atms /v1/atm?Format=XML&PageOffset=0&PageLength=10& PostalCode=46312&Country=USA
HTTP Method	GET
Header Namespace	hdrns
Client ID	DKB0vGSHs4r1Vv308yObMj4QhhJkIMP5G 3a14KmEa7f96b5e!414a78536b4a6f6272634a41446e 4566483851625a7a413d
KeyStore Provider	keyprov
Private Key Alias	key1
Private Key Password	key1pass

This assumes key1 is the alias of a private key entry in the KeyStore provider keyprov. The service will compute the following Signature Base String. The oauth_nonce and oauth_timestamp will obviously change each time the service executes.

GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fatms%2Fv1%2Fat
m&Country%3DUSA%26Format%3DXML%26PageLength%3D10%26PageOffset%3D0
%26PostalCode%3D46312%26oauth_consumer_key%3DDKB0vGSHs4r1Vv308yObMj4QhhJ
kIMP5G3a14KmEa7f96b5e%2521414a78536b4a6f6272634a41446e4566483851625a7a41
3d%26oauth_nonce%3D180284899533025%26oauth_signature_method%3DRSA
SHA1%26oauth_timestamp%3D1396020436%26oauth_version%3D1.0

The service will store the following header value in the hdrns. Authorization special register. The oauth_signature changes every time the service is executed because the oauth_nonce and oauth_timestemp varies.

OAuth oauth_signature="JjBI1gi5EMHwcihnCyK0RX7UzCC2SCtplutEjUgUXaI2nhGd4IR3L7b
WMtpJKkyUnR667lpkI7zqbM3oR3CHc2%2FgxPerD%2FSDGibHTAcTHCfV9%2F0xBVzv%2Fzo
1egU4CEqjZGSeIAeJKQYOflKSrfX8ken0MsXwXv5s9TLQuO8pRPwCfrqgrmVa%2FHhlzRxU7
pEv2kpJn4opG3Cvn01aKlotztxG8u476aEydFq03emqjVh8GMArtGDt8RhJqisJ0OB9SsaWU
K%2FsV%2BQtvghmX7G0pyQ6hLJUa3NSqlINU2k19cLOhUEnylDVD62sTZGrPe9%2B3zKLj%2
BX77eGLFKrDqOxk9w%3D%3D",oauth_version="1.0",oauth_nonce="18028489953302
5",oauth_signature_method="RSASHA1",oauth_consumer_key="DKB0vGSHs4r1Vv30
8yObMj4QhhJkIMP5G3a14KmEa7f96b5e%21414a78536b4a6f6272634a41446e456648385
1625a7a413d",oauth_timestamp="
1396020436"

If the Request Header Namespace is hdrns in the NHTTP Emit service, this will add the following HTTP header to the HTTP request.

Authorization: OAuth oauth_signature="JjBI1gi5EMHwcihnCyK0RX7UzCC2SCtplutEjUgUXaI2nhGd4IR3L7b
WMtpJKkyUnR667lpkI7zqbM3oR3CHc2%2FgxPerD%2FSDGibHTAcTHCfV9%2F0xBVzv%2Fzo
1egU4CEqjZGSeIAeJKQYOflKSrfX8ken0MsXwXv5s9TLQuO8pRPwCfrqgrmVa%2FHhlzRxU7
pEv2kpJn4opG3Cvn01aKlotztxG8u476aEydFq03emqjVh8GMArtGDt8RhJqisJ0OB9SsaWU
K%2FsV%2BQtvghmX7G0pyQ6hLJUa3NSqlINU2k19cLOhUEnylDVD62sTZGrPe9%2B3zKLj%2
BX77eGLFKrDqOxk9w%3D%3D",oauth_version="1.0",oauth_nonce="18028489953302
5",oauth_signature_method="RSASHA1",oauth_consumer_key="DKB0vGSHs4r1Vv30
8yObMj4QhhJkIMP5G3a14KmEa7f96b5e%21414a78536b4a6f6272634a41446e456648385
1625a7a413d",oauth_timestamp="1396020436"

Example 2

This example shows the creation of an OAuth 1.0a Authorization header for a POST method. The following table lists the parameter values for the service.

Parameter	Value
HTTPS URL	https://sandbox.api.mastercard.com/fraud/merchant/v1/termination-inquiry?Format=XML&PageLength=10&PageOffset=0
HTTP Method	POST
Header Namespace	hdrns
Client ID	DKB0vGSHs4r1Vv308yObMj4QhhJkIMP5G3 a14KmEa7f96b5e!414a78536b4a6f6272634a41446e4 566483851625a7a413d
KeyStore Provider	keyprov
Private Key Alias	key1
Private Key Password	key1pass

The following input document is the parsed XML document:

<ns2:TerminationInquiryRequest xmlns:ns2="http://mastercard.com/termination"><AcquirerId>1996
</AcquirerId><TransactionReferenceNumber>1</TransactionReferenceNumber>
<Merchant><Name>TEST</Name><DoingBusinessAsName>TEST
</DoingBusinessAsName><PhoneNumber>5555555555</PhoneNumber>
<NationalTaxId>1234567890</NationalTaxId><Address><Line1>5555 Test Lane
</Line1><City>TEST</City><CountrySubdivision>XX</CountrySubdivision>
<PostalCode>12345</PostalCode><Country>USA</Country></Address>
<Principal><FirstName>John</FirstName><LastName>Smith</LastName>
<NationalId>1234567890</NationalId><PhoneNumber>5555555555</PhoneNumber>
<Address><Line1>5555 TestLane</Line1><City>TEST</City><CountrySubdivision>XX
</CountrySubdivision><PostalCode>12345</PostalCode><Country>USA
</Country></Address><DriversLicense><Number>1234567890</Number>
<CountrySubdivision>XX</CountrySubdivision></DriversLicense></Principal>
</Merchant></ns2:TerminationInquiryRequest>

The service will compute the following Signature Base String. Notice the extra attribute oauth_body_hash compared to Example 1.

POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Ffraud%
2Fmerchant%2Fv1%2Fterminationinquiry&Format%3DXML%26PageLength%3D10%
26PageOffset%3D0%26oauth_body_hash%3Dh3%252BhLMkT%252B3pBvRolKEc95fobEB8
%253D%26oauth_consumer_key%3DDKB0vGSHs4r1Vv308yObMj4QhhJkIMP5G3a14KmEa7f
96b5e%2521414a78536b4a6f6272634a41446e4566483851625a7a413d%26oauth_nonce
%3D180286176383600%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp
%3D1396020438%26oauth_version%3D1.0

The service will store the following header value in the hdrns Authorization special register. The oauth_signature, oauth_nonce, and oauth_timestamp will change every time the service is executed.

OAuth oauth_signature="GSgJ6wUiYDznurpspn2ztn9PZeuXIBy4LZZHOSuMQrQ8OskwdWdaX0i
UXfNELxEQUniy6z5b2c06yVCut4XoYtV5XJaYnoG78bqkJ3LLVBqZ%2Brv%2F%2FTbIQmz0c
enMAinlR09QeduIHV7gPGqd%2FBi9Rkj%2BHnxI5bLNGn0nQoOie%2BSNUAPCjnn2Ydoj44l
Sufmur6N2U7paJAuEIfp3VANbLwCI%2Bts5EBr3ecCn7eEqbuQMzs8hW2c%2FdzZqoOvyEda
O86SVcTX9vT5XI8V%2FRluupobCRy8xSuxubnCJrf5USfT%2FB5rudqNkHW0%2BmtE8hxVLI
L9v2dKPSRxtqsU75GsrgA%3D%3D",oauth_body_hash="h3%2BhLMkT%2B3pBvRolKEc95f
obEB8%3D",oauth_version="1.0",oauth_nonce="180286176383600",oauth_signat
ure_method="RSASHA1",oauth_consumer_key="DKB0vGSHs4r1Vv308yObMj4QhhJkIMP
5G3a14KmEa7f96b5e%21414a78536b4a6f6272634a41446e4566483851625a7a413d",
oauth_timestamp="1396020438"

The output document is the same as the input but the data is now stored as bytes.

If the Request Header Namespace is hdrns in the NHTTP Emit service, this will add an Authorization header to the HTTP request.

Syntax:

com.ibi.agents.XDOAuth2Agent

Description:

This service emits an HTTPS request authenticated by OAuth 2.0 using the credentials of a Google service account.

OAuth 2.0 is described in RFC6749 and RFC6750. It is an authorization framework that enables an application to obtain access to an HTTP resource. The role of the client and the resource owner are separate. The client does not use the resource owner credentials. Instead, it requests an access token from a trusted authorization server. The client presents the token together with the request to the resource server which grants access if the token is valid.

The OAuth 2.0 Authentication service manages the creation and renewal of access tokens by communicating with the authorization server. If it obtains a valid access token, it incorporates the token with the outgoing HTTPS request to make the authenticated call.

When OAuth 2.0 is used interactively, the user is often redirected to a consent screen to enter his credentials. Since the iSM service operates in a server-to-server scenario, there is no consent screen involved. Instead, the client provides its credentials with the private key associated with a Google service account. The authorization server will be accessed at the same location as the resource server.

When obtaining a token, the client must specify the scope of the access requested. For example, there could be a scope for read-only and another for read-write permissions. It is also possible to request multiple scopes in a single access token.

The scopes are not standardized. The resource servers are free to define the scopes that make sense for their application. The documentation of the resource server API will make it clear which OAuth 2.0 scopes it supports. It remains the responsibility of the application designer to request and use the appropriate scopes.

Parameters:

The following table lists and describes the parameters for the OAuth 2.0 Authentication service.

Parameter	Description
HTTP Client Provider	HTTP Client provider that manages connections for this emitter.
Destination URL	URL where the request will be addressed. The URL should be fully specified, including the HTTPS scheme.
HTTP Method	POST sends the current document as a request entity. GET and HEAD will send a request to the configured URL.
Content Type	Content type for the HTTP request to be sent by this emitter.
Request Header Namespace	Special register namespace from which HTTP headers for the outgoing request will be taken. Select Default Namespace to send the HDR type registers with no namespace prefix, or supply a namespace prefix here. None means that no special registers will be sent as HTTP headers.
Response Header Namespace	Special register namespace into which HTTP headers from the incoming response will be saved. Select Default Namespace to create special registers with no namespace prefix, or supply a namespace prefix here.
Scopes	Determines which services the application requests access to. Select one from the list or enter a space-separated list of scopes.
Project ID	Value of the x-goog-project-id header.
Service Account Email	Email address of the service account.
KeyStore Provider	Provider for the keystore containing the service account private key.
Private Key Alias	Alias of the service account private key within the keystore.
Private Key Password	Password for the private key. If left blank, the password for accessing the keystore will be used.

The HTTP Client provider can be defined on the pooling providers page in the iWay Service Manager console. Google recommends that OAuth 2.0 should always be used with HTTPS, therefore the HTTP Client provider should specify an SSLContext Provider.

The authenticated request will be sent to the Destination URL. The service will access the authorization server at the same location to obtain access tokens. The HTTP method specifies the type of request: GET, PUT, POST, HEAD, PATCH or DELETE. The Content Type parameter specifies the content type of the authenticated request.

If additional headers are needed, they can be declared as HDR registers in the Request Header Namespace. The default value is none, which means there is no Request Header Namespace and no extra headers are added.

The headers of the HTTP response are stored as special registers in the specified Response Header Namespace.

The Scopes parameter specifies the access scope requested from the authorization server. The access token returned will grant those scopes. For example, if the scope in the token is read-only-access and a write operation is attempted, the resource server will reject the call because the scope is not sufficient. The scopes are application specific. For more information, see the resource server API documentation to learn which scopes it supports.

The Project ID is optional. When present, it specifies the value of the x-goog-project-id header. In the cloud platform of Google, a Project consists of a set of users, a set of APIs, and billing, authentication, and monitoring settings for those APIs.

The Service Account Email acts like a user name for a service account. It looks like an email address but there is no actual email involved. The credential for the service account is a private key. The KeyStore Provider is the name of the iSM keystore provider that holds the private key. The Private Key Alias and the Private Key Password are the alias and password of the private key entry within the Keystore.

Edges:

The following table describes the edges that are returned by the OAuth 2.0 Authentication Service.

Edge	Description
Success	The request message was successfully sent and the response received.
fail_parse	An iFL expression could not be evaluated.
fail_operation	The operation could not be completed successfully.

Example:

This example shows how to retrieve a document from the Google Cloud Storage using the OAuth 2.0 Authentication Service.

Google Cloud Storage is a service to store data in the cloud and retrieve it later. It has a RESTful API, authenticated with OAuth 2.0. The equivalent of a file is called an object. Objects are stored in folders called buckets. Buckets are like directories, except they are not hierarchical. Every bucket exists in a single namespace shared by all users of the service. The slash ( / ) character is invalid in a bucket name but is accepted in an object name.

The Google Cloud platform supports multiple varieties of credentials. For server to server applications, a service account must be used. This is a name associated with a public key. The client proves his identity by encrypting with the private key which is kept secret. Service accounts are tied to a specific Google project. They are created in the Google Developer Console. Google chooses the service account name and creates the public-private key pair automatically. The private key is downloaded at the time the service account is created.

The Google Developer Console may change without notice. Proceed with the following steps:

From the following website, https://console.developers.google.com:

1. Sign in with your Google account or create a new google account on the sign-in page if you do not already have one. This is your regular Google account, not a service account yet.
2. Create a new Google project, specify the project name and the project ID, and then write down the project ID.
3. In the left menu, select APIs & auth and then click on APIs. Ensure that the Google Cloud Store is set to ON.
4. In the left menu, select APIs & auth, click Consent. and then proceed to the next step. The consent screen is not used in this example, but it must be selected and meet the requirements of Google.
5. Enter any Product Name and click Save.
6. In the left menu, select APIs & auth, click Credentials, and select Create new Client ID.
7. In the dialog that appears, select Service Account and click Create client ID. This will download a PKCS12 Keystore containing the private key of this service account.
8. Save the keystore in a convenient location and write down the keystore password shown on the screen, for example, notasecret.
9. Record the email address of the service account shown on the screen. The email address will look similar to the following:

   298643775104-81neakmsco3agrv956tl8inu8ci7oedl@developer.gserviceaccount.com

10. In the left menu, select Billing & settings, then enable the billing, and fill in the financial information.
11. In the left menu, click Storage, select Cloud Storage, Storage Browser and then click Create a bucket, and enter the bucket name. This must be a unique name among all buckets in the Google Cloud Storage. A good practice is to use your bucket name with your domain name changing the period with a dash. For example: test99-example-com
12. Click Upload and select a file to store in the Google Cloud Storage, then write down the name of the bucket and the file name in the bucket.
13. Go to https://pki.google.com and download the CA certificate for Google Internet Authority G2. This will be used to create a truststore.

    The following information will be available:

    • The project ID.
    • The Keystore containing the private key.
    • The Keystore password.
    • The service account email address.
    • The bucket name.
    • The object name in the bucket.
    • The certificate for Google Internet Authority G2.
14. Import the Google CA certificate into a Java Keystore with the following command. This assumes the certificate is stored in a file called GIAG2.cer

    keytool -import -trustcacerts -file GIAG2.cer -alias giag2 -keystore GIAG2.jks -storepass secret -storetype JKS

15. In the left menu of the iWay Service Manager console, click Security Providers, and then click New to create a new Keystore provider to be used as the truststore.

    The following table lists the parameters and values of the Keystore provider.

    Parameter	Value
    Name	giag2
    Description	Google Internet Authority G2
    Keystore	Path to GIAG2.jks
    Keystore Password	secret
    Keystore type	JKS
    KeyStore JCE Provider	SUN

16. Click New again to create another Keystore provider for the private key of the service account.

    Parameter	Description
    Name	cloudkey
    Keystore	Path to the keystore containing the service account private key.
    Keystore Password	The keystore password chosen by Google, for example, notasecret.
    Keystore type	PKCS12-DEF
    KeyStore JCE Provider	BC

17. Create an SSLContext provider to be used by the HTTPS connections, and accept all default parameters except the following:

    Parameter	Description
    Name	GoogleSSL
    Keystore Provider	Not used but required. You can enter giag2
    Truststore Provider	giag2
    Security Protocol	TLS

18. Create an HTTP Client provider to manage connections to the Google Cloud Storage by clicking Pooling Providers in the left menu of the iWay Service Manager console, and then clicking New.
19. Accept all default parameters except those found in the following table:

    Parameter	Description
    Name	GoogleClient
    SSL Context Provider	GoogleSSL

20. In your process flow, create an instance of the OAuth 2.0 Authentication Service configured as shown in the following table. Replace the values in angle brackets with the actual value obtained in the Google Developers console.

    Parameter	Description
    HTTP Client Provider	GoogleClient
    Destination URL	URL of the object in the Google Cloud Storage.
    HTTP Method	GET
    Scopes	https://www.googleapis.com/auth/devstorage.read_only
    Project ID	The Google Project ID.
    Service Account Email	The service account email address chosen by Google.
    KeyStore Provider	cloudkey
    Private Key Alias	privatekey
    Private Key Password	Password chosen by google, for example, notasecret.

    The Destination URL can take one of the following forms:

    • https://<bucketname>.storage.googleapis.com/<objectname>
    • https://storage.googleapis.com/<bucketname>/<objectname>

    For example, if the bucket name is mybucket-example-com, and the object name is root.xml, the destination URL can be one of two equivalent URLs:

    • https://mybucket-example-com.storage.googleapis.com/root.xml
    • https://storage.googleapis.com/mybucket-example-com/root.xml

    This instance of the OAuth 2.0 Authentication Service accepts any input document since the GET method does not send a request entity in the body of the message. The output document will be the contents of the object found in the Google Cloud Storage or an error document.

Syntax:

com.ibi.agents.XDWSHttpClientAgent

Description:

This service executes a web service through an HTTP Client provider and allows a transformation to be applied to the response document.

Parameters:

Strip SOAP Envelope Parameter

The Strip SOAP Envelope parameter moves namespaces to the payload node when a SOAP response is received. For example, assume that the target web service returns the following message to the service:

<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:somens="http://somens.com">
      <SOAP-ENV:Body>
          <somens:payload>Hello</somens:payload>
      </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If set to true, then the Strip SOAP Envelope parameter cuts the child of the <SOAP-ENV:Body> element, which in this example, is <somens:payload>. The result is not, by itself, a well-formed XML document because the xmlns attribute that declares the somens namespace prefix is lost during the cut.

Enabling the Strip SOAP Envelope parameter causes the service to ascend the XML tree looking for namespace declarations and copies these attributes to the payload node. For example, after the SOAP envelope is removed, the response document has the following structure:

<somens:payload xmlns:somens="http://somens.com">Hello</somens:payload>