Make REST Calls Through Workflow Steps

You can add Execute REST Call steps to a workflow or to a workflow module that will then be added to a workflow.

Execute REST Call steps allow you to use a REST Get, Post, Put, Patch, or Delete action in workflows to interact with third-party REST servers or with Commander installations (version 8.0 or higher).

Some example use cases for this step include:

  • Making a request to an IPAM server to get an available IP. When the IP is returned in the response, it can be passed to a subsequent workflow step that'll assign it to the VM to be deployed.
  • Making a REST request to a third-party server for a specific attribute (for example, getting a VM attribute from vCenter). When the VM attribute is returned in the response, it can then be passed to another workflow step that'll set the attribute on the VM.
  • Using the Commander API to export workflow definitions in either JSON or YAML formats (in this case, you would use a GET on /workflow-definitions). See Commander API Reference for information on the Commander API.

Access:

Configuration > Command Workflows

Configuration > Self-Service > Approval tab

Configuration > Self-Service > Completion tab

Available to:

Commander Role of Superuser and Enterprise Admin

  1. On the Steps page of one of the workflow or workflow module configuration wizards, click Add > Execute REST Call.
  2. In the details section, change the step's default name of "Execute REST Call" if you want.
  3. For Step Execution, indicate whether you want the step to run automatically (the default behavior) or run only when specific conditions are met. To make a step conditional, select Execute when conditions are met, then click Edit and define the condition. See Make Workflow Steps Conditional for more details.
  4. For Response, specify whether the returned REST response should be captured as a comment. When you capture the response as a comment, you can use that output as the input to a subsequent Set Custom Attribute step. For more information, see Use Script Output as Input to Workflow Steps. To learn how to retrieve a REST response in subsequent workflow steps without capturing the response in a comment, see Custom Workflow Variables.
  5. For When Request Fails, indicate what to do if the call fails:
    • Mark the step as failed and don't proceed
    • Skip the step and go to the next step in the workflow

    If a retry step is added to this Execute REST Call step, and it's set to Mark as Failed, the workflow will retry the failed step. See Add Retry Steps to Workflows for details.

  6. If required, for Credentials, choose or add the system credentials that are required to establish a connection with the REST endpoint.
  7. For URL, enter the URL to access to the resource that you want to make the REST call to.

    In any text field that supports variables, click to open the script editor and select variables for the current context.

  8. For Action, select the REST action to use for the step. The following actions are supported:
    • Get
    • Post
    • Put
    • Patch
    • Delete
  9. For Content Format, select whether you want to use a JSON or XML payload for the REST call.
  10. For Header, optionally, insert any metadata for the REST call. You may be required to add metadata here if the REST endpoint requires additional data in the form of a header.

    Each entry must be a key value pair on separate lines, for example: 

    Date: Fri, 29 Jun 2019 11:11:11 GMT
Accept-Language : en-US
  11. For Payload, optionally, enter the payload contents in the proper JSON or XML format. If you don't insert a payload, an empty payload may automatically be added for a POST, if required.

    You may also use environment variables in the text.

  12. For Result Filter, optionally, add a JSON path, XPath or regex expression to filter the returned results.

    You can use result filtering to receive a limited set of resources from the API that match a set of filters instead of the entire, potentially verbose response. This is useful if you want to pass only a specific value or property from the returned data (for example, a ticket id) into another workflow step.

  13. For Success Codes, define what HTTP response numbers will indicate that the REST call has succeeded.

    You may specify numbers between 100 and 600 as ranges or specific numbers. For example, "100-200, 300".

  14. If required, continue to add steps, and when you've finished, click Next.
  15. Continue to configure the workflow or workflow module, as required.

    For more information, see: