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

  • Name: The name used to identify a saved RestRequest configured instance.
  • Comments: Some comments about this saved RestRequest configured instance.
  • Service url: The HTTP URL to reach the remote service.
  • Rest method: The REST method among: get, post, delete, put
  • Basic auth login: The account name to access the remote service via basic authentication (optional).
  • Basic Auth Password: The account password to access the remote service via basic authentication (optional).

  • Certificate authentication section

  • SSL Client Certificate File Path: The path to the SSL Client certificate file.
  • SSL Client Key File Path: The path to the SSL Client Key file.
  • SSL Client Key Passphrase: The SSL Client certificate passphrase.
  • SSL CA Certificate File Path: The path to the SSL CA Certificate file.
  • SSL Verification: If selected SSL verification will be used instead of login and password authentication.

  • Trigger and polling settings

  • Polling frequency: Polling interval in seconds. If not set, no polling is done.
  • Polling stop condition code: Ruby code condition to stop the polling. By default, return true meaning stop now.
  • 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.
  • 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.
  • 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.
  • Header parameters: Define specific name/value pairs for the HTTP request headers.
  • Content type: Type of the request content among: jpg, xml, gif, text, json, pdf (for post and put requests).
  • Http form post?: Use an HTTP form to build the POST request body. If checked, the Post parameters box is displayed.
  • Post parameters: Name/value pairs to define the HTTP form parameters.
  • Post request body: Specify the POST body content. The content format must fit the defined content type.
  • Response type: Type of the response content among: json, xml, text
  • Request timeout: Optional. The timeout duration (in seconds) to wait before giving up on a request. By default, there is no timeout
  • Return Code for Network failure: Optional. In case of Network failure the default return code is returned as -1. If custom return code is needed please enter here. If empty return code is needed, please enter the value as "-100"
  • Processed outputs: Name/type pairs to add as outputs of this plugin.
  • Processed outputs code: Ruby code executed after the response is treated (received, formatted and the polling stopped). Used to populate the processed outputs pairs

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:

  • Service_url: The HTTP URL to reach the remote service.
  • Post_parameters: Name/value pairs to define the HTTP form parameters (if 'Http form post?' is selected).
  • Post_body: Post request body (if 'Http form post?' is not selected).

Optional Inputs:

  • Basic_auth_login: The account name to access the remote service via basic authentication.
  • Basic_auth_password: The account password to access the remote service via basic authentication.
  • Header_parameters: HTTP request header parameters.
  • Processed_outputs_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.
  • PUT_file_path: File path if Rest method is 'put' and Post request body not filled in.
  • Save Output to file: Check this box if the output needs to be saved to a file.
  • Write response to this file: The response will be written to this file.

Outputs Description

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

  • Service_result: The raw response as a string.
  • Response_header: The http header of the response as a hash.
  • XML_result: The XML parsed response as a hash. Only present if the response type is xml.
  • JSON_result: The JSON parsed response as a hash. Only present if the response type is json.
  • Formatted_result: The formatted response as an array after the extracting and formatting code have been applied.

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.