SOAP

Allows to perform SOAP calls on a SOAP API.

Json

Example

{
  "name": "protocol-soap-perform",
  "taskReferenceName": "soap",
  "description": "The business description of the task",
  "type": "SUB_WORKFLOW",
  "optional": false,
  "inputParameters": {
    "endpoint": "https://",
    "useAuthentication": true,
    "login": "",
    "password": "",
    "request": "file://assets/request.xml"
  }
}

Definition

Property	Type	Required	Description
			The name (or type) of the task
			The unique name of the task in your job. It is used to reference this task in the workflow.
			The functional description of this task in your job.
			The type of the task. It must be SUB_WORKFLOW.
	:		true: the job continues if there is an error on this task. false: the job fails.
			Input parameters of the task. See below

Inputs

Property	Type	Required	Description
			The endpoint.
			Does it need authentication?
			Login
			Password
	:		REQUEST: perform the calls described in the request document. FILE / FILES: send the given file, or each of the given files, as the SOAP message.
			A file that defines all the requests. See the definition below.
			The file to send as the SOAP message.
			The files to send, one call per file.
	:		Default: false When set to true, the report generation is skipped and thus the report is not available in the output parameters.
	:		Default: info It defines the log level to be recorded in the report. error < warning < info < debug

Input request

Example

<Soap>
  <Soap-Call>
    <Request>
        <Soap-Message>
          <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope/" soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
            <soap:Body xmlns:m="http://www.example.org/stock">
              <m:GetStockPrice>
                <m:StockName>IBM</m:StockName>
              </m:GetStockPrice>
            </soap:Body>
          </soap:Envelope>
        </Soap-Message>
        <Headers>
            <Header key="customHeader">value</Header>
        </Headers>
    </Request>    
    <Metadata>
      <ean>1234567890123</ean>
    </Metadata>  
  </Soap-Call>
</Soap>

Definition

You can do multiple calls with only one xml file.

XPath	Description	Occurs
Soap	Root of the document	1
./Soap-Call	For each call.	1..*
../Request	The request element	1
../Request/@path	The path containing path params.	0..1
../Request/Headers	The headers	0..1
.../Headers/Header	A header	1..*
.../Headers/Header@key	The name of the header	1
.../Soap-Message	The soap message	1
../Metadata	An element that can be used to store information and retrieve it in the responses.	0..1

Outputs

Property	Type	Description
responses		An xml file containing the responses for each request. Only in mode = REQUEST.
file		The response received. Only in mode = FILE.
files		The responses received, one per call. Only in mode = FILES.
listing		An xml file listing the responses. Only in mode = FILE or FILES.
allSuccess		YES | NO. YES: all calls had a success response. NO: at least one request had an error response.

The task status does not tell you whether the calls worked

The task ends COMPLETED even when every call failed - a non-2xx response is a result, not a task failure. allSuccess is the output to test: it is YES only when every response carried a 2xx status.

Note that allSuccess is also YES when no call was made at all, for instance when the request document lists none. A YES therefore means "nothing failed", not "something succeeded" - check the responses or the listing if you need to know that calls actually happened.

Headers sent by default

Every call carries these three headers unless you override them:

Header	Value
content-type	text/xml
cache-control	no-cache
mime-version	1.0

Header names are case-insensitive, so content-type and Content-Type are the same header. A header you declare in Request/Headers replaces the default of the same name, and if you declare the same name twice, the last one wins.

When useAuthentication is true, an authorization header carrying HTTP Basic credentials is added as well.

Output responses

Example

<Soap>
  <Soap-Call>
    <Request>
        <Soap-Message>
          <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope/" soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
            <soap:Body xmlns:m="http://www.example.org/stock">
              <m:GetStockPrice>
                <m:StockName>IBM</m:StockName>
              </m:GetStockPrice>
            </soap:Body>
          </soap:Envelope>
        </Soap-Message>
        <Headers>
            <Header key="customHeader">value</Header>
        </Headers>
    </Request>    
    <Metadata>
      <ean>1234567890123</ean>
    </Metadata>  
    <Response>
        <Status-Code>200</Status-Code>
        <Content>
          <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope/" soap:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
            <soap:Body xmlns:m="http://www.example.org/stock">
              <m:GetStockPriceResponse>
                <m:Price>34.5</m:Price>
              </m:GetStockPriceResponse>
            </soap:Body>
          </soap:Envelope>
        </Content>
    </Response>
  </Soap-Call>
</Soap>

Definition

The response has the structure as the request with some elements added.

XPath	Description	Occurs
./Response	The response for each call.	1
../Status-Code	The status code of the response	1
../Content	The content of the response	1

When the endpoint cannot be reached

When the endpoint cannot be reached at all, the call still appears in responses, with its request echoed back and an Error element in place of the response:

<Soap>
    <Soap-Call>
        <Request>
            <Soap-Message>…the message that was to be sent…</Soap-Message>
        </Request>
        <Response>
            <Error>Unable to contact the webservice.</Error>
        </Response>
    </Soap-Call>
</Soap>

Execution report log codes

Code	Severity	Metadata	Raised when
SOAP_REQUEST_START	info	endpoint, file	Before each SOAP request. In FILE / FILES mode, also once at the start of the task.
SOAP_REQUEST_SUCCESS	info	endpoint, file, statusCode	After each request that succeeded.
SOAP_REQUEST_ERROR	error	endpoint, file, statusCode	After each request that failed. Depending on the error, this can also stop the task.
SOAP_INVALID_INPUT	error	message	An input is invalid. Stops the task.
SOAP_INVALID_XML_INPUT	error	message	In REQUEST mode, the input file is invalid. Can stop the task.
SOAP_TASK_COMPLETE_SUCCESS	info	listing, responses	At the end of the task, when no error was encountered.
SOAP_TASK_COMPLETE_ERROR	error	listing, responses	At the end of the task, when at least one error was encountered.

Limits and additional notes

• 50 requests in a file.