Web Services Adapter Actions
  • 03 Jun 2022
  • 7 Minutes to read
  • Dark
    Light

Web Services Adapter Actions

  • Dark
    Light

Article summary

Web Services Adapter Actions

HTTP Record Fields

All HTTP actions return a record with the following fields:

Field

Description

statusCode

the HTTP status code returned from the server

statusReason

the descriptive name of the HTTP status code returned from the server

headers

a Record containing the HTTP header fields returned from the server

data

the data returned from the server. Will be E4X XML object if the data is detected to be XML, an ECMAScript object if detected to be JSON, a String if detected to be any other kind of text, and a byte array if anything else

All HTTP actions may also return undefined in the event of any error that doesn't result in at least an HTTP status.

httpDELETE

Perform an HTTP DELETE operation.

Property

Value

Description

url*

text, expression, variable

the url

headers

expression, variable

Record or Object containing HTTP header fields

username

text, expression, variable

username for authentication to the url

password

password, string, expression, variable

password for authentication to the url

options

expression, variable

A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout.

returnVariable

expression, variable

name of the variable to be assigned to the return value

result = httpDELETE("http://httpbin.org/delete")
log(result ? result.statusCode + " " + result.statusReason + "\n"
+ toJSON(result.data, true) : "Missing Result")

httpGET

Perform an HTTP GET operation.

Property

Value

Description

url*

text, expression, variable

the url

headers

expression, variable

a Record or Object containing HTTP header fields

username

text, expression, variable

username for authentication to the url

password

password, string, expression, variable

password for authentication to the url

options

expression, variable

A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTime which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout.

returnVariable

expression, variable

name of the variable to be assigned to the return value

result = httpGET("http://httpbin.org/get")
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")

httpHEAD

Perform an HTTP HEAD operation.

Property

Value

Description

url*

text, expression, variable

the url

headers

expression, variable

Record or Object containing HTTP header fields

username

text, expression, variable

username for authentication to the url

password

password, string, expression, variable

password for authentication to the url

options

expression, variable

A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout.

returnVariable

expression, variable

name of the variable to be assigned to the return value

result = httpHEAD("http://httpbin.org/get")
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.headers, true) : "Missing Result")

httpOPTIONS

Perform an HTTP OPTIONS operation.

Property

Value

Description

url*

text, expression, variable

the url

headers

expression, variable

Record or Object containing HTTP header fields

username

text, expression, variable

username for authentication to the url

password

password, string, expression, variable

password for authentication to the url

options

expression, variable

A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout.

returnVariable

expression, variable

name of the variable to be assigned to the return value

result = httpOPTIONS("http://httpbin.org/get")
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.headers, true) : "Missing Result")

httpPATCH

Perform an HTTP PATCH operation.

Property

Value

Description

url*

text, expression, variable

the url

headers

expression, variable

Record or Object containing HTTP header fields

data

expression, variable

Data to post

username

text, expression, variable

username for authentication to the url

password

password, string, expression, variable

password for authentication to the url

options

expression, variable

A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout.

returnVariable

expression, variable

name of the variable to be assigned to the return value

jsonRestMessage = toJSON({surname: "Jon", givenName: "Doe"})
result = httpPATCH("http://httpbin.org/patch", {"Content-Type": "application/json"}, jsonRestMessage, "user",<Password>)
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")

httpPOST

Perform an HTTP POST operation.

Property

Value

Description

url*

text, expression, variable

the url

headers

expression, variable

Record or Object containing HTTP header fields

data

expression, variable

Data to post

username

text, expression, variable

username for authentication to the url

password

password, string, expression, variable

password for authentication to the url

options

expression, variable

A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout.

returnVariable

expression, variable

name of the variable to be assigned to the return value

soapMessage =
<Envelope>
<Body>
<thankYou xmlns="urn:idauto:dss:samples:thankYouServer"/>
</Body>
</Envelope>

result = httpPOST("http://httpbin.org/post", {"Content-Type": "application/xml", SOAPAction: "thankYou"}, soapMessage, "user",<Password>)
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")

httpPUT

Perform an HTTP PUT operation.

Property

Value

Description

url*

text, expression, variable

the url

headers

expression, variable

Record or Object containing HTTP header fields

data

expression, variable

Data to post

username

text, expression, variable

username for authentication to the url

password

password, string, expression, variable

password for authentication to the url

options

expression, variable

A record or JavaScript object with a field for each additional option. Currently defined fields are connectTimeout and socketTimeout which require a numeric value from 1 to 2147483647 (0x7FFFFFFF) that represents the number of milliseconds for the timeout, and 0 representing no timeout.

returnVariable

expression, variable

name of the variable to be assigned to the return value

formMessage = "surname=Doe&givenName=John"
result = httpPUT("http://httpbin.org/put", {"Content-Type": "application/x-www-form-urlencoded"}, formMessage, "user",<Password>)
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")

Unsolicited Basic Authentication

Usually for HTTP Basic Authentication, the client makes a request without the credentials and the server responds with a challenge telling the client what kind of authentication it needs to perform the operation. The client then reissues the request with the provided credentials. For some web services, the server does not issue the challenge, but rather expects the client to send any the credentials without being asked for them. Usually this is the case when some requests can be processed without any authentication, but will provide a different answer based on being authenticated as a known user who has more rights. This is known as unsolicited authentication. The Web Service Adapter will perform unsolicited authentication if you provide the X-UnsolicitedBaseAuth header with a non-null value.

formMessage = "surname=Doe&givenName=John"
result = httpPUT("http://httpbin.org/put", {"Content-Type": "application/x-www-form-urlencoded", "X-UnsolicitedBaseAuth": "1"}, formMessage, "user",<Password>)
log(result ? result.statusCode + " " + result.statusReason + "\n" + toJSON(result.data, true) : "Missing Result")

Implementing SOAP Endpoint Action Sets

The Web Service Adapter supports implementing SOAP endpoints using an Action Set.

  • The Action Set MUST define at least one input parameter. Any additional input parameters must be defined as optional. When invoked as an endpoint, the first input parameter will contain an E4X XML object that represents the SOAP message and is guaranteed to be a valid SOAP Envelope. Any additional input parameters will have the value undefined.
  • The Action Set MUST return a valid SOAP Envelope (either as a String or as an XML object). Failure to do so will result in a SOAP Fault message being returned to the client. The SOAP version of the returned Envelope SHOULD match the SOAP Version of the Envelope provided as the first input parameter.
  • Other than the above requirements, the Action Set MAY exercise any/all DSS capabilities for which the server is licensed.
  • An Action Set is invoked as a SOAP endpoint by POSTing a valid SOAP 1.1 or SOAP 1.2 Envelope to a URL of the form:
    • http[s]:server[:port]/dss/services/soap/<action-set-name> * Clients that cannot gracefully handle an HTTP return code of 500 Internal Server Error (e.g. Flash/Flex) , should post to the alternate URL which will return 200 OK even when there is a SOAP Fault: * http[s]:server[:port]/dss/ws/dss/soap/<action-set-name>
  • Invoking an Action Set as SOAP endpoint MUST provide valid credentials of a User that is authorized to run the Action Set (e.g. have role Administrator or Operator) using one of the following methods.
    • HTTP Basic Authentication; OR
    • Providing the credentials as query parameters on the URL:
      • ?authUser=<user>&authPassword=<password>
  • An Action Set invoked as a SOAP endpoint will write its execution log to a file on the DSS server exactly as it would if it were invoked manually using the runAsync or runForValue REST resource endpoints. The log will contain detailed trace information if and only if the URL has the trace=true query parameter appended.
  • An Action Set that implements a SOAP endpoint MAY still be invoked/called like any other Action Set provided that the required first parameter is supplied. Calling the SOAP endpoint Action Set from a wrapper Action Set is usually the simplest way to test/debug the Action Set.
# define the soepenv and thanks namespaces so we can use them in e4x expressions
# (since differing namespaces for different versions of SOAP, respond with the same SOAP version as the request)
soapenv = message.namespace()
thanks = "urn:idauto:dss:samples:thankYouServer"

# Start off with a mostly empty response
response = <Envelope xmlns={soapenv}> <Body/> </Envelope>
responseBody = response.soapenv::Body

# Check that request body has a thanks::thankYou element
thankYou = message.soapenv::Body.thanks::thankYou[0]

if(!thankYou) {
# Fault structure is different in SOAP 1.2 than SOAP 1.1
if(soapenv == "http://www.w3.org/2001/06/soap-envelope") {
# SOAP 1.2
fault = <Fault xmlns={soapenv} xmlns:soapenv={soapenv}> <Code> <Value>soapenv:Sender</Value> </Code> <Reason> <Text>Missing thankYou element</Text> </Reason> </Fault>
} else {
# Check that request body has a thanks::thankYou element
# Fault structure is different in SOAP 1.2 than SOAP 1.1
fault = <Fault xmlns={soapenv} xmlns:soapenv={soapenv}> <faultcode>soapenv:Client</faultcode> <faultstring>Missing thankYou element</faultstring> </Fault>
}

dummy = responseBody.appendChild(fault)
} else {
youreWelcome = <youreWelcome xmlns={thanks}/>
dummy = responseBody.appendChild(youreWelcome)
}

# return the response
return response.toXMLString()

Was this article helpful?

ESC

Eddy AI, facilitating knowledge discovery through conversational intelligence