External REST API Integration Help Documentation

Owned by Christina
Last updated: Jul 07, 2022
5 min read

The External API Integrator tool contains an Endpoints tab which stores API endpoints, methods and an authentication token (added in Request Header via Custom Parameters). Once the tool is configured, configure an External API Integrator pipeline step that will integrate with their tools to make a RESTful API call.

Tool Registry Setup

  1. In Tool Registry, click ‘+ New Tool’ button to create a new External API Integrator tool.

  2. Locate the External API Integrator tool and click ‘Select Tool’ button.

  3. Provide a Tool Name and any other values and click ‘Create’ button to save the new tool.

  4. Navigate to the Endpoints tab and click the ‘+ New External API Integrator Endpoint’ button to configure a new Endpoint.

5. Complete the ‘Create New External API Integrator Endpoint’ form.

Name - Provide a custom name for the Endpoint.
Type - Provide an Endpoint Type. Choose from Access Token Generation, Call Operation, Connection Validation, or Operation Status Check.
Request Type - Select Request Type. Choose from Get, Post or Put.
URL - Provide the respective URL, dependent on Request Type.

 

6. Provide EndPoint Field Configuration values:


Request Header - Use Authorization Bearer Token

Token Type - Choose a Long Lived Bearer Token or Short Lived Bearer Token.
Authorization Token Custom Parameter - If you are required to include a header token, it must first be added to Custom Parameters (saved in Tool Registry) in order to be selected from this drop-down. Authorization Tokens must be encrypted Custom Parameters. Do not include "Bearer" in the Custom Parameter. This field is not required if you have an API token. You can add the API token to Request Body.

Query Parameters

Response Body

Response Body Type - Choose from Array, Boolean, Object or String.
Field Name - Provide the field name.
Field Type - Choose from Array, Date, Object or String.

API Configuration

If Query Parameters exist, provide Value.

Evaluation Rules

Evaluation Option - Select API Response Evaluation or Status Code from the drop-down.

  • Status Code - Evaluate connection based on the status code.

    • Filter - Choose Is Equal To or Is Not Equal To from the drop-down.

    • Value - Provide a value to evaluate. The Value can be equal to a specific value or ‘object', ‘array’, ‘boolean’ or ‘string’.

  • API Response Evaluation - Evaluate the connection based on the response of evaluation rules.

    • Filter - Choose Equals, Does Not Equal, Is Not Null or Is Null.

    • Value - Provide a value to evaluate. The Value can be equal to a specific value or ‘object', ‘array’, ‘boolean’ or ‘string’.

7. Provide a Description for the Endpoint (optional).

8. Click the ‘Create’ button to save the Endpoint.

The External API Integrator tool can now be configured in a pipeline step.

Follow these guidelines to successfully configure an External API Integrator pipeline step in the pipeline.

Pipeline Step Setup

  1. In the pipeline workflow, create a new step. Provide values for fields in the Step Setup form and select ‘External API Integration’ from the Tool drop-down.

  2. Click the ‘Save’ button to save the new tool. Now you can configure the step.

  3. Click the gear icon (⚙︎) to open the Pipeline Step Configuration settings.

     

Pipeline Step Configuration

External API Integrator Tool - Select a configured External API Integrator Tool from the drop-down. This is fetched from the Tool Registry.

Note: Successful Completion Evaluation Rules take precedence over In Progress Evaluation Rules. If the response does NOT match either the Successful Completion OR In Progress Evaluation Rule, it will be considered a failure. The Pipeline will continue running while it meets the In Progress Evaluation Rules until it meets the criteria for Successful Completion or until the Pipeline Run timeout is reached.

Connection Check

  • API Configuration - To verify the connection, enable the ‘Validate Connection’ toggle. Select the Connection Validation Endpoint configured in the External API Integrator Tool in the Endpoints tab.

  • Connection Validation Evaluation Rules - Set evaluation rules for Connection Validation Evaluation Rules.

Call Operation

  • API Configuration - Select the Call Operation Endpoint and Query Parameters to evaluate.

  • Successful Trigger Evaluation Rules - Set evaluation rules for the Call Operation.

Status Check

The Status Check rules evaluate the API call upon completion.

  • API Configuration - Select the Status Check Endpoint and Request Body to evaluate.

  • In Progress Evaluation Rules - Set evaluation rules for the Status Check In Progress state.

  • Successful Completion Evaluation Rules - Set evaluation rules for the Status Check upon successful completion.