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

    Web Services Adapter Actions

    • Updated on 03 Jun 2022
    • 7 Minutes to read
    • Print
    • 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?
    What's Next