Skip to main content
Version: v5.0

REST connector

A REST connector allows you to make HTTP requests flexibly and quickly, to get data and pass it to the next step.

For a REST connector, you must pass a URL and an authentication object with one of the following Authentication mechanisms or Auth Schemes:

  • No Auth
  • Basic Auth
  • Bearer Token
  • OAuth2 Client Credentials
  • OAuth2 Client Credentials as JSON body
  • OAuth2 Password Grant

The following code displays a basic REST connector example:

"_actualparams": {    "_url": "<url>",    "_auth": {        "_type": "BasicAuth",        "_params":{            "_username": "<username>",            "_password": "<password>"        }    },    "to": "json",    "fileName": "<File Name With extension>"}

REST connector parameters#

Depending on the authentication you use, your REST connector contains the following parameters:

  • _url: Required parameter. Enter the request URL that points to the data you want to fetch as a string.

  • _auth: Required parameter. Pass an authentication object with the following two keys:

    • _type: Required parameter. Enter one of the following authentication schemes as a string:

      • NoAuth
      • BasicAuth
      • BearerToken
      • OAuth2ClientCreds
      • OAuth2PasswordGrant
      • OAuth2ClientCredsJSON

      For more information, see REST connector code examples for each authentication scheme

    • _params: Required parameter if you use any authentication scheme, except NoAuth. For the value, pass an object that contains the authorization parameters and values for your authentication type and enter their values as strings.

      Auth schemeRequired parametersRequired
      No Auth  
      Basic Auth_usernameYes
      _passwordYes
      Bearer Token_tokenYes
      OAuth2 - Client Credentials_tokenUrlYes
      _clientIdYes
      _clientSecretYes
      _scopeOptional
      OAuth2 - Password Grant_tokenUrlYes
      _clientIdYes
      _clientSecretYes
      _scopeOptional
      _usernameYes
      _passwordYes
      OAuth2 - Client Credentials As JSON Body_tokenUrlYes
      _clientIdYes
      _clientSecretYes
      _scopeOptional

  • to: Optional parameter. To define the response format you want to return, for the value, enter one of the following formats:

    • json: Retruns the response as a JSON Object
    • text: Returns the response as a string
    • file: Stores the response data to a file, uploads the file to the file service, and returns the fileId and fileVersionId
    • xml2js: Parses inbound XML and returns a JavaScript ObjectFor more information on response examples, see to parameter responses

  • fileName: Optional parameter. If value of to field is file then fileName can be specified in the actual params which will be used to store the file in file services with the specified file name.

  • args: Optional parameter. Pass arguments, such as a HTTP request method or header information, to the HTTP request with an _args object. 

        "_args": {        "method": "POST", //If you do not add this parameter, the default is GET.        "body": "{\"key\":\"value\"}",        "headers": {            "Accept": "application/json",            "Content-Type": "application/json"        }    }

REST connector code examples for each authentication scheme#

Refer to the following code examples when you create your REST connector, depending on the authentication scheme you use:

Basic Auth#

"_actualparams": {    "_url": "<url>",    "_auth": {        "_type": "BasicAuth",        "_params":{            "_username": "<username>",            "_password": "<password>"        }    },    "to": "json",    "fileName": "<File Name With extension>"}

BearerToken#

"_actualparams": {    "_url": "<url>",    "_auth": {        "_type": "BearerToken",        "_params":{            "_token": "<token>",        }    },    "to": "json",    "fileName": "<File Name With extension>"}

OAuth2ClientCreds#

"_actualparams": {    "_url": "<url>",    "_auth": {        "_type": "OAuth2ClientCreds",        "_params":{            "_tokenUrl": "<token>",            "_clientId": "<clientId>",            "_clientSecret": "<clientSecret>",            "_scope": "<scope>",        }    },    "to": "json",    "fileName": "<File Name With extension>"}

OAuth2PasswordGrant#

"_actualparams": {    "_url": "<url>",    "_auth": {        "_type": "OAuth2PasswordGrant",        "_params":{            "_tokenUrl": "<token>",            "_clientId": "<clientId>",            "_clientSecret": "<clientSecret>",            "_username": "<username>",            "_password": "<password>",            "_scope": "<scope>",        }    },    "to": "json",    "fileName": "<File Name With extension>"}

OAuth2ClientCredsJSON#

"_actualparams": {    "_url": "<url>",    "_auth": {        "_type": "OAuth2ClientCredsJSON",        "_params":{            "_tokenUrl": "<token>",            "_clientId": "<clientId>",            "_clientSecret": "<clientSecret>",            "_scope": "<scope>",        }    },    "to": "json",    "fileName": "<File Name With extension>"}

to parameter responses#

If you use the optional to parameter, the following objects return in the response if you set the value to either file, json, or text.

file#

{    "rest_conn_result": {        "fileId": "<fileId>",        "fileVersionId": "<fileVersionId>"    }}

json#

{    "rest_conn_result": {        "userId": 1,        "id": 1,        "title": "delectus aut autem",        "completed": false    }}

text#

{    "rest_conn_result": "String Response Here"}

Xml2js#

Input

<xml>  <userId>1</userId>  <id>1</id>  <title>delectus aut autem</title>  <completed>false</completed>

Response

{    "rest_conn_result": {        "fileId": "<fileId>",        "fileVersionId": "<fileVersionId>"    }}

Creating a rest_connector orchestrator payload#

  1. Create a JSON object with the following properties and the values you want to define:

    • _name
    • _description
    • _namespaces
    • _usertype
    {    "_name": "Rest Connector",    "_description": "Rest Connector Calls",    "_namespaces": [        "$current_project._namespaces"    ],    "_userType": "xlsx_import",}

  2. Add a _params property with an empty object as its value. In the object, add a tasks property with an empty array as its value.

    ...    "_params": {        "tasks": []    }

  3. Add your first task to the tasks array as an orchestrator component with the following properties:

    • _orchcomp: Enter rest_connector as the value.

    • _name: Describe what your task component does.

    • _sequenceno: Enter an integer to order the task in the sequence of tasks.

      ...    "_params": {        "tasks": [            {                "_orchcomp": "rest_connector",                "_name": "Copy assets relationships from previous version",                "_sequenceno": 1,            }        ]    }

  4. In the orchestrator component, add an _actualparams property with an authentication object as its value. For more information on authentication objects for each authentication scheme, see REST connector code examples for each authentication scheme.

    ...    "_params": {        "tasks": [            {                "_orchcomp": "rest_connector",                "_name": "Copy assets relationships from previous version",                "_sequenceno": 1,                "_actualparams": {                    "_url": "<url>",                    "_auth": {                        "_type": "NoAuth"                    },                "to": "json"                }            }        ]    }

  5. Add more orchestrator components to the tasks array. Ensure that you order the sequence numbers correctly.

Result: A complete orchestrator with sequenced tasks, including a rest connector and a scripting task. For a complete example, see the following code:

{    "_name": "Rest Connector",    "_description": "Rest Connector Calls",    "_namespaces": [        "$current_project._namespaces"    ],    "_userType": "xlsx_import",    "_params": {        "tasks": [            {                "_orchcomp": "rest_connector",                "_name": "Get telemetry data from data aggregation platform",                "_sequenceno": 1,                "_actualparams": {                    "_url": "http://telemetry.com/api",                    "_auth": {                        "_type": "BasicAuth",                        "_params": {                            "_username": proj_1.username,                            "_password": proj_1.username.pwd                        }                    },                    "to": "json"               }            }            {                "_orchcomp": "default_script_target",                "_name": "Store telemetry data in the item service",                "_sequenceno": 2,                "_actualparams": {                    "userType": "iaf_telem_store",                    "_scriptName": "storeTelem",                                    }            }        ]    }}

IP addresses for Rest Connector calls#

Allowing or denying IP addresses#

To allow or deny specific IP address, you can add the following properties in the config.json file:

  • ALLOW_IP_ADDRESS_LIST: IP address to allow
  • DENY_IP_ADDRESS_LIST: IP address to deny

Blocked IP addresses for Rest Connector calls#

The following IP addresses are blocked for Rest Connector calls:

IP address rangeTypeReason for blockExample
10.0.0.0 – 10.255.255.255Private IPv4Used for local private networks within an organization that are not routable on the internet10.10.10.10
172.16.0.0 – 172.31.255.255Private IPv4Used for local private networks within an organization that are not routable on the internet172.16.20.30
192.168.0.0 – 192.168.255.255Private IPv4Used for local private networks within an organization that are not routable on the internet192.168.1.100
100.64.0.0 – 100.127.255.255Shared Address SpaceUsed for Carrier-Grade NAT (CGN) or large-scale deployments in shared infrastructures100.64.10.20
10.0.0.0 – 10.255.255.255Private IPv4Used for local private networks within an organization that are not routable on the internet10.20.30.40
100.64.0.0 – 100.127.255.255Shared Address SpaceUsed for Carrier-Grade NAT (CGN) or large-scale deployments in shared infrastructures100.65.66.67
127.0.0.0 – 127.255.255.255LoopbackUsed to send messages back to the same device, typically for testing purposes127.0.0.1
169.254.0.0 – 169.254.255.255Link-localLink-local addresses are automatically assigned to network interfaces when no IP address is configured and are used for communication within a single subnet.169.254.1.2
172.16.0.0 – 172.31.255.255Private IPv4Used for local private networks within an organization that are not routable on the internet172.31.50.60
192.0.0.0 – 192.0.0.255IETF Protocol AssignmentsReserved for IETF protocol assignments192.0.0.1
192.0.2.0 – 192.0.2.255DocumentationReserved for documentation and specification examples192.0.2.100
192.88.99.0 – 192.88.99.255IPv6 to IPv4 RelayIPv6 to IPv4 relay anycast addresses used for 6to4 relay192.88.99.10
192.168.0.0 – 192.168.255.255Private IPv4Used for local private networks within an organization that are not routable on the internet192.168.254.1
198.18.0.0 – 198.19.255.255Benchmark TestingReserved for network benchmark tests198.18.10.20
198.51.100.0 – 198.51.100.255DocumentationReserved for documentation and specification examples198.51.100.1
203.0.113.0 – 203.0.113.255DocumentationReserved for documentation and specification examples203.0.113.100
224.0.0.0 – 239.255.255.255MulticastUsed to send messages to multiple recipients at the same time224.0.0.1
233.252.0.0 - 233.252.0.255MulticastUsed to send messages to multiple recipients at the same time233.252.0.1
240.0.0.0 – 255.255.255.254ReservedReserved for future use240.0.0.100
255.255.255.255BroadcastUsed to send messages to all hosts on the attached network255.255.255.255