SOAP Request Action Plugin



This plug-in provides the ability to periodically execute a SOAP query on a web service. It can be used for a one-off request or as a polling mechanism.

Saved Parameters Description

  • Name: The name used to identify a saved SoapRequest configured instance.
  • Comments: Some comments about this saved SoapRequest configured instance.
  • WSDL URI: The WSDL (Web Services Description Language) URI (Uniform Resource Identifier) to describe the remote service. See instructions below.
  • WSDL file: The local WSDL file to describe the remote service. See instructions below.
  • Service: The SOAP operation out of the defined operations for the remote service.
  • Provide explicit payload?: To provide an explicit SOAP XML payload. If checked, the payload must be entered in the 'Service payload' box.
  • End point: The URL for the remote node providing the service. Can be used if no WSDL is specified. Otherwise extracted from the WSDL.
  • Soap action: Explicit SOAP operation. Can be used if no WSDL is specified. Otherwise extracted from the WSDL.
  • HTTP basic auth user: The account name to access the remote service via HTTP basic authentication. Optional.
  • HTTP basic auth password: The account password to access the remote service via HTTP basic authentication. Optional.
  • Service payload: The SOAP request XML payload.
  • Service action parameters: The SOAP request operation parameters if an explicit payload is not provided.
  • Session header parameters: The SOAP request header parameters if an explicit payload is not provided.

Trigger and Polling Settings

  • Polling frequency: Polling interval in seconds. If not set, no polling is done.
  • Keep trigger ongoing?: To use this plugin as a trigger. Set a non null polling frequency when selected. See instructions below.
  • Maximum number of records returned: Maximum number of records in a response to be put in Formatted_result output. If keep trigger ongoing is selected, each spawned workorder will handle this maximum number of records.
  • Polling stop condition code: Ruby code condition to stop the polling. By default, return true, meaning stop now.
  • Record identification code: Ruby code to identify what consists of a unique record out of the formatted record. Use it if Keep trigger ongoing? is on.
  • Return real status: By default this step will always return as COMPLETE, unless a critical error is detected. By checking this option it is possible to modify the return status and status_details in one of the formatting or extraction codes.
  • Result records extracting code: Ruby code to extract an array out of the response.
  • Record formatting code: Ruby code to format a record out of the extracted array.
  • Results formatting code: Ruby code executed after the response is treated (and record extracting + formatting has been applied if any).
  • Result type: Type of the expected Service_results output. Among array, string, int, hash, flag.
  • Return raw reponse?: Check this box to return the full XML response with the SOAP envelope
  • Return structured response body?: Check this box to return the XML response body.

Inputs Description

The list of inputs depends on the configuration of the SoapRequest action template.

Changes in this list of inputs will override any values set in the action template.

Mandatory inputs:

  • Wsdl_uri: The WSDL URI to describe the remote service. Not needed if End point and Soap action are specified.
  • Service_action: The SOAP operation out of the defined operations for the remote service. Not needed if End point and Soap action are specified.

Optional Inputs:

  • Http_basic_auth_user: The account name to access the remote service via basic authentication.
  • Http_basic_auth_password: The account password to access the remote service via basic authentication.
  • Result_formatting_code: Ruby code executed after the response is treated.
  • Polling_stop_condition: Ruby code condition to stop the polling.
  • Records_extracting_code: Ruby code to extract an array out of the response.
  • Record_formatting_code: Ruby code to format a record out of the extracted array.
  • Cookie: HTTP header cookie. To keep the session information between multiple soap requests.

Outputs Description

  • Each processed outputs name/value pair will introduce a new output of the selected type.

  • Raw_response: The raw response as a string. Only present if 'Return raw reponse?' is selected.
  • Response_body: The SOAP response body as a hash. Only present if 'Return structured response body?' is selected.
  • Service_results: The results after the code in 'Results formatting code' has been applied. Type is determined by 'Result type'. By default an array.
  • Cookie: The cookie response as a string.

Supported Actions

None

Dependencies

None

Operating Instructions

Overview:

This action generates a SOAP request to a remote service and handles the response.
  1. Select either a remote WSDL as a HTTP URI (for example, http://www.ebi.ac.uk/ws/services/WSDbfetch?wsdl) or a locally imported WSDL file.
    A local WSDL file must be stored in this Orchestrator folder:
    /opt/aspera/var/config/orchestrator/actions_config/soap_requests/
  2. Select an operation from the 'Service' drop-down list.
  3. Check the 'Provide explicit payload?' box if you want to enter the XML payload explicitly. Input variables can be specified with the <%=myvariable%> notation.

    Alternatively to a WSDL URI or local file, an End point and a Soap action can be specified if 'Provide explicit payload?' is selected.

    Alternatively to an explicit payload, you can provide the 'Service action parameters' and/or 'Session header parameters'. This is not encouraged as it relies on parsing the wsdl to find the input parameters, which can be unpredictable. With the payload mode, you can test with soapUI and then just cut and paste the xml into the payload section.

  4. The authentication can be done via a HTTP basic authentication login and password in the appropriate fields. Username and password are then combined into a "username:password" string, and they are Base64 encoded and put in the http Authorization header.

Polling:

The SOAP request can be repeated until a condition is met.

Set a polling frequency to enable this feature (for example, 5 for 5 seconds periodicity).

Example with this response (Raw_response output):

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
     <ns1:GetSessionsResponse xmlns:ns1="urn:Aspera:XML:FASPSessionNET:2009/11:Types">
         <SessionKeysResult>
            <ResultCount>2</ResultCount>
            <RemainingResultCount>0</RemainingResultCount>
            <IterationToken>dd549761f97954417d2abf3c47ec877b0000000000001229</IterationToken>
            <SessionKey>
               <UUID>fe77385c-3d17-4613-b839-1fc04bc5d423</UUID>
            </SessionKey>
            <SessionKey>
               <UUID>678357a5-cbf1-490a-8417-3d1f17390ea6</UUID>
            </SessionKey>
         </SessionKeysResult>
     </ns1:GetSessionsResponse>
   </soapenv:Body>
 </soapenv:Envelope>

The xml_result variable is built from parsing the XML body if present. It contains this hash: 

{"GetSessionsResponse"=>[{"SessionKeysResult"=>[{"ResultCount"=>["2"], "SessionKey"=>[{"UUID"=>["fe77385c-3d17-4613-b839-1fc04bc5d423"]}, 
 {"UUID"=>["678357a5-cbf1-490a-8417-3d1f17390ea6"]}], "RemainingResultCount"=>["0"], 
 "IterationToken"=>["dd549761f97954417d2abf3c47ec877b0000000000001229"]}],  "xmlns:ns1"=>"urn:Aspera:XML:FASPSessionNET:2009/11:Types"}]}

The stop condition is expressed in Ruby in "Polling stop condition code".

Example: 

xml_result["GetSessionsResponse"][0]["SessionKeysResult"][0]["RemainingResultCount"][0] == '0' rescue nil

This will repeat the request until the result count in the XML response is equal to 0

Select "Keep trigger ongoing?" to enable a trigger functionality. Spawn a new workorder each time a new record (determined by the record identification code) is found in the response. Then proceed with the next steps in the workflow. The new instance will keep polling for new records in the response. A record that has already been detected is memorized and will not be re-detected again (unless the workflow is restarted).

Formatting:

Specify in "Result records extracting code" the Ruby code to extract an array of things out of the response.

Specify in "Record formatting code" the Ruby code to format each extracted record.

Specify in "Record identification code" the Ruby code to identify what consists of a unique record out of the formatted record.

With "Result records extracting code" such as: 

return xml_result["GetSessionsResponse"][0]["SessionKeysResult"][0]["SessionKey"]

The extracted array will be the following with 2 records:

[{"UUID"=>["fe77385c-3d17-4613-b839-1fc04bc5d423"]}, {"UUID"=>["678357a5-cbf1-490a-8417-3d1f17390ea6"]}]

With "Record formatting code" such as 

return { "id" => record["UUID"][0] } rescue nil

Each record will be a hash with id as the key and the UUID value

Service_results output will then hold an array such as: 

[{"id" => "fe77385c-3d17-4613-b839-1fc04bc5d423"}, {"id" => "678357a5-cbf1-490a-8417-3d1f17390ea6"}]

With "Record identification code" = return "#{record["id"]}", if keep trigger ongoing is selected, the trigger will identify records by their UUID.

Note that "Record identification code" can be left empty if for example only 'return record["UUID"][0]' is specified in "Record formatting code". In this case, by default "Record identification code" will take the record UUID as the unique record identifier.

In this case, Service_results output will hold an array such as: 

["fe77385c-3d17-4613-b839-1fc04bc5d423", "678357a5-cbf1-490a-8417-3d1f17390ea6"]

Also note that "Result records extracting code" and "Record formatting code" can be used without "Keep trigger ongoing?" being selected and without a polling period being set. Use this case to format an array of things out of the response and output it into Service_results.

In addition to the "Result records extracting code" and "Record formatting code", some post-treatment code can be applied in "Results formatting code". For example, if we wanted an output as a hash with iteration_token only, we would add in "Results formatting code": 

 token = xml_result["GetSessionsResponse"][0]["SessionKeysResult"][0]["IterationToken"][0]
 results = { "iteration_token" => token }

In this case, change the "Result type" to hash. "Service_results" would then be:

 {"iteration_token"=>"91286e2557483993505661edef5435690000000000001234"}