Parent topic: Plugin Help Content
Plugins / Plugin Help Content

REST Request Action Plugin



Overview

This plugin periodically executes a REST query to a web service. It can be used for a one-off request or as a polling mechanism.

Saved Parameters Description

Inputs Description

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

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

Mandatory Inputs:

Optional Inputs:

Outputs Description

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

Supported Actions

None

Dependencies

None

Operating Instructions

Overview:

This action generates a REST request to a remote service and handles the response.

Example HTTP URL:
http://127.0.0.1/aspera/orchestrator/workflow_reporter/workflows_list/0
Parameters can be passed into the HTTP URL with the "?" and "&" notation like the following:
 http://localhost/aspera/orchestrator/work_orders/initiate/xml?login=admin&password=aspera&work_order[workflow_id]=1

Or they can be passed in the HTTP request body. Select a post rest method in this case (rather than get). Either use a HTML form (select "Http form post?") and define a name/value pair for each post parameter. Or fill the Post request body with your content.

The authentication can be done directly in the URL (with login/password as shown above) or in by specifying a 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.

Specify the content type for this body (e.g. xml, json, etc). Specify the type of the response (e.g. xml, json, raw text). This will condition the type of the output.

If xml is selected, the response is XML parsed and the 'xml_result' variable is populated with the parsed result as a hash. Same for a json content with the 'json_result' variable. If text is selected, no parsing is done and the 'result' variable holds the raw response as a string.

If needed, specify name/type pairs for processed outputs. An output is created for each of these pairs. Then use "Processed outputs code" to populate these output parameters according to this syntax:

outputs['<variable name>'] = <some code> to assign the variable from xml_result or json_result or result

Example: 

 outputs['name'] = xml_result['name'][0]

Polling:

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

Set a polling frequency to enable this feature (e.g. 5 for 5 seconds periodicity).

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

Example XML response:

<?xml version="1.0"?>
 <GetResponse>
    <status>complete</status>
    <name>john</name>
 </GetResponse>

After XML parsing (if an XML response type is selected), xml_result holds the following: 

{"name"=>["john"], "status"=>["complete"]}

Example polling stop condition: 

xml_result['status][0] == 'complete' rescue nil

This will repeat the request until the status in the parsed xml result is equal to 'complete'

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).

Specify in "Result records extracting code" the Ruby code to extract an array of things out of the response (xml_result, json_result or result).

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.

Example with this XML response:

<?xml version="1.0"?>
 <workflows time="2014-10-31 14:52:40 UTC" action="list" id="0">
    <workflow id="1" name="create file" latest_revision_id="1"
    </workflow>
     <workflow id="2" name="custom ruby" latest_revision_id="2"
    </workflow>
  </workflows>

After XML parsing (if xml reponse type is selected), xml_result holds: 

{'workflow' => [{"name"=>"create file", "id"=>"1", "latest_revision_id"=>"1"}, {"name"=>"custom ruby", "id"=>"2", "latest_revision_id"=>"2"}]}

With "Result records extracting code" = return xml_result['workflow']

The extracted array will be the following with two records:

[{"name"=>"create file", "id"=>"1", "latest_revision_id"=>"1"}, {"name"=>"custom ruby", "id"=>"2", "latest_revision_id"=>"2"}]

With "Record formatting code" = return {"id"=>record["id"],"name"=>record["name"]}

Each record will be stripped of the latest_revision_id

Formatted_result output will hold: 

[{"id"=>"1", "name"=>"create file"}, {"id"=>"2", "name"=>"custom ruby"}]

With "Record identification code" = return "#{record["id"]}"

If keep trigger ongoing is selected, the trigger will identify records by their ID only.

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

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 Formatted_result.

Parent topic: Plugin Help Content