SOAP Request Listener



Overview

This action plugin provides the ability to wait for a SOAP message and extract its content.

Saved Parameters Description

Parameter Description
Comments Comments about what the action does or why it is configured that way.
Keep ongoing? If checked, the containing workflow will be cloned after each trigger event, ensuring that the workflow executes every time a SOAP message is received.
Polling frequency By default, the queue is probed every 5 seconds for a new message. That polling frequency can be changed to any number of seconds.
Callback ID mode Indicates how the SOAP call received is matched with a listening step. Valid options are workflow, step, action_id, runtime, or preset.
  • workflow: The action that will receive the SOAP call is identified by the workflow in which it is contained.
  • step: The action that will receive the SOAP call is identified by its workflow step. This is similar to "Workflow" but offers the ability to differentiate between different steps within the same workflow that could be listening to different SOAP messages.
  • action_id: The action that will receive the SOAP call is identified by its template ID and is thus independent of the surrounding workflows, since the same template can be used in different workflows.
  • runtime: The ID is provided by external parameters provided at runtime; for example, the name of the file being processed in a previous step.
  • preset: The ID is either hardcoded or can be a based on external parameters provided at runtime (dynamic attributes are supported): for example, the name of the file being processed.
Preset ID value The callback ID to be used; only if preset is selected. Dynamic attributes such as <%=file_name%> can be used.
Processed outputs A list of additional outputs can be specified.
Note: Those outputs will be set to nil, unless some code is provided to set them in the Processed outputs code text area.
Processed outputs code Ruby code can be inserted it to assign values to the named processed outputs as entried in the '@outputs' hash. Values from the SOAP call received can be used, they are accessible thru the @header, @xml_payload and @remote_address variables.

Input Description

The list of inputs depends on the configuration of the SoapRequestListener action template. If dynamic attributes are used in the Callback ID preset, each of them will be a required input.

Run-time call back ID: Mandatory if Callback ID mode is set to runtime - the identifier to use to match the listener with a SOAP event.

Outputs Description

    • Remote_address: The IP address of the SOAP call sender
    • XML_payload: The raw XML as a string of the SOAP call message.
    • Header: The header structure as a hash of the SOAP call message
    • Body: The body structure as a hash of the SOAP call message

Additionally, all the outputs specified in the Processed outputs will be returned, with their value as computed by the code specified in Processed outputs code.

Operating Instructions

This plugin provides the ability to wait until a SOAP message is received.

The SOAP message are to be sent to an endpoint on the Orchestrator server. The endpoint contains an identifier that enables the routing back to the proper workflow and step.
  • A typical endpoint will be the following:
    http://<orchestrator_address>/aspera/orchestrator/soap_listener/aspera_call/callback_id
  • The SOAP action is
    SOAPAction: "/soap_request_listener/api/Trigger"
  • A WSDL like the following can be generated:
    http://<orchestrator_address>/aspera/orchestrator/soap_request_listener/wsdl
  • The action is Trigger. Note though that the end point will need to be modified as it depends on the callback ID defined in the plugin settings. An accurate WSDL can be generated by providing as parameters the appropriate information.
    Parameters are the following:
    • Address (optional, by default the orchestrator server address will be computed)
    • Port (optional, by default the port will be pulled from the computed orchestrator server address)
    • Protocol (optional, by default the protocol will be pulled from the computed orchestrator server address)
    • callback_id_mode (optional - Valid options are workflow, step, action_id, runtime, or preset. If not already provided, a qualified callback_id must be provided, which also means the callback_identifier must be prefixed properly to indicate its mode.
    • callback_identifier (Optional: If not provided, a placeholder will be used)
    • parameter_name (Optional: If the request wants to provide a text value in a field, the field name can be provided, otherwise none will be expected). For example:
      http://<orchestrator_address>/aspera/orchestrator/soap_request_listener/wsdl? protocol=http&address=localhost&port=3000&parameter_name=jobID&callback_id_mode=preset&callback_identifier=1234
The format for the callback ID depends on the callback ID mode selected. Below are the format options
Mode Format Example
workflow w<the_workflow _id> w19 if the workflow ID is 19
step s<the step name without special characters or space (- and _ are conserved)> sWaitforcall-back if the step name is Wait for call-back
action ID a<the action plugin configuration/template ID> a5 if the template/configuration ID is 5
preset p<the preset ID> pencoding_tron if preset was set to encoding_<%=File.nakedname(video_file)%> and the input video_file received the value /processing/tron.avi
real-time rt<the value of the input Run-time call back ID > rtencoding if the input Run-time call back ID received the value encoding
As an example, let's assume we use the preset callback ID mode and the preset is hardcoded to 1234. The SOAP endpoint to send the message will look something like the following:
 http://localhost:3001/aspera/orchestrator/soap_listener/p1234 
Response example:
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:ActionWebService">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:Trigger soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
      <file><path>/tmp/baba.avi</path>
      <type>trailer</type><isci>BABA0RUM</isci>
      <duration>00:00:30.25</duration>
      <genre>epic</genre><genre>scifi</genre>
      </file>
   </soapenv:Body>
</soapenv:Envelope>
Note: Even though the wsdl did not specify a message structure, one can be provided anyway, as long as the sending system lets it through.
If the processed outputs target_path of type string and genre of type array are configured, the code to extract those values in the Processed outputs code section will look like the following:
@outputs['target_path'] = @body['file'][0]['path'][0]
@outputs['genre'] = @body['file'][0]['genre'] rescue []
The resulting output would be:
genre: ["epic", "scifi"] 
target_path: /tmp/baba.avi