Rest API connector

[ | version 3.1]

Connector

The connector is permitted for use of the platform background agent.

Connector processing type: Both (Row by row & Bulk), Default type: Row by row!

The Rest API connector allows you to communicate with other REST services using the HTTP protocol with basic request types, i.e. GET, POST, PUT, PATCH and DELETE. It also supports many of the most commonly used authentication methods (OAuth2, Token, NTLM,...).

Configuration

Rest API connection

Base URL

The base URL of the connection. The request uses a combination of the Base URL in this parameter with the Endpoint URL path.

Base URL and Endpoint URL path in the System

If you input an absolute path into both the Base URL and Endpoint URL path, the system simply concatenates them as strings, potentially resulting in unsuccessful endpoint calls.

https://dx.xeelo.net

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

https:/server.com/${input.Uri}/

Ignore SSL Certificates

If set, will ignore SSL certificates. Can be used if the remote API does not have a signed certificate.

Authorization Method

Supported authorization methods:

None - no authorization is used
Basic - username and password (see Documentation).
Token - authorization using a provided token
OAuth2 - an authorization framework that exchanges credentials for an authorization token to be used (see Documentation).
NTLM - Windows NT LAN Manager authentication protocol (see Documentation). Microsoft does not recommend NTLM for new implementations due to security concerns. It is used for backward compatibility.
NTLM Ticket - More secure than just NTLM, credentials are negotiated for the access token. No need to send credentials for every request (see Documentation).

Username

Defines the login name that is used for connection authentication.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

Password

Define the password that is used to authenticate the connection.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

Domain

Define the NTLM domain that is used for connection authentication.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

Authorization token

Define the authorization token that is used to authenticate the connection.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

OAuth2 token endpoint

Define the OAuth2 token endpoint that is used to obtain the authorization token.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

api/endpoint/token/${input.token}

OAuth2 token expiration

Define the expiration of the OAuth2 token in minutes.

OAuth2 request headers

Headers to include in the OAuth2 request. If no Content-Type header is set, its value application/x-www-form-urlencoded will be automatically included.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

OAuth2 request body

Defines the body of the OAuth2 token request that is sent to the OAuth2 token endpoint.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

NTLM ticket endpoint

Defines the NTLM ticket endpoint that is used to retrieve the authorization ticket.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

api/ntlm/${input.Endpoint}/

NTLM ticket request beaders

Headers to include in the NTLM ticket request. If no Content-Type header is set, its value application/json will be automatically included.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

NTLM ticket username

Defines the login name to be used to authenticate the NTLM connection ticket.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

NTLM ticket password

Defines the password to be used to authenticate the NTLM connection ticket.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

NTLM ticket domain

Define the domain that is used for NTLM connection ticket authentication.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

NTLM ticket request body

Define the NTLM ticket request body that is sent to the NTLM ticket endpoint.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

NTLM ticket request result path entry

The result path in the JSON response object where the NTLM ticket is returned, i.e. result.data for the response:

{
    "result":
    {
        "data": "string token"
    }
}

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

result.data.${input.Property}

Request header ticket attribute

Defines the request header attribute key where the returned NTLM ticket will be stored.

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. This placeholder only works when the input has a single line.

${input.NTLMAttribute}

Rest API endpoint

Basic request types

The following table lists the supported HTTP methods. Additional configuration options are available based on the selected request type

Request type	CRUD
POST	Create
GET	Read
PUT	Update / Replace
PATCH	Update / Modify
DELETE	Delete

Headers

Specify custom headers to be used with the HTTP request in the form of key/value pairs. For more information, see this link HTTP documentation.

It is not necessary to specify all headers, some are default based on the chosen data content type (Accept, Content-Type).

Header Key	Value	Description
Accept	application/json	format of response which will be received (requested API must support this)
Content-Type	application/json	content body format to be used

Endpoint

The endpoint specifies a Path with parameters to query the requested resource from the Host defined in the connection configuration. The combination of Host and Path is the requested URI.

Base URL and Endpoint URL path in the System

If you input an absolute path into both the Base URL and Endpoint URL path, the system simply concatenates them as strings, potentially resulting in unsuccessful endpoint calls.

Example

api/endpoint/getData?dataId=1
api/endpoint/create

Input data can be referenced using placeholders, i.e. ${input.ObjectID} will be replaced by the value in the ObjectID property of the input. However, except for the Data configuration, this placeholder only works when the input has a single line.

Example

api/endpoint/${input.Method}

Timeout

The number of seconds to wait before terminating the request. The default value is set to 100.

Request Type

Supported HTTP request methods:

RequestType	CRUD
POST	Create
GET	Read
PUT	Update / Replace
PATCH	Update/Replace
DELETE	Delete

DataContent Type

The format that will be used for the request body when sending a request and also for the response (Content-type and Accept will be set to application/json or application/xml by default).

XML Header

An XML header element to be added to the XML content in the request body

Example

<?xml version="1.0" encoding="UTF-8" ?>

An XML footer element that is added to the XML content in the body.

Data

The request body, which should be in the format defined in the DataContentType (XML, JSON,...) or defined using the HTTP Content-Type header, which can be filled in the Headers property.

Input data can be referenced using placeholders:

${input.ObjectID} will be replaced by the value in the ObjectID property of the connector''s input data.
The ${input} placeholder will be replaced by the integer value of the input data.

{
    "Task": ${input.Task},
    "IsActive": ${input.IsActive}
}

or

${input}

Using placeholders

The placeholders can be used to access the input data and dynamically create the contents of the request body or to modify the configuration. If the input schema is selected, its data can be accessed by following placeholders:

Placeholder	Description
`${input}`	Replaced by whole input
`${input.property}`	Replaced by a single property of input

Input data can be referred by using placeholders:

${input.ObjectID} will be replaced by the value in the ObjectID property of the input data connector.
${input} will be replaced by the integer value of the input data.

Placeholders for creating body content

The body content can be configured directly or can be generated based on the input using placeholders. The resulting JSON or XML (based on configuration) will also take into account the data type of the input columns. For example, the numbers in the JSON are as numbers (without double quotes).

Assume the connector input data is in the following format:

ID (Number)	Name (String)	Items (Complex)
1	Alice	`[{"ID":1},{"ID":2}]`
2	Bob	`[{"ID":3},{"ID":4}]`

Examples of using single cell placeholders to create a request body for the JSON format. You can also serialize Complex or JSON types in this way.

{
  "CustomerID": ${input.ID},
  "CustomerName": ${input.Name},
  "IsActive": true,
  "ItemIDs": ${input.Items}
}

will generate request body

[
  {
    "CustomerID": 1,
    "CustomerName": "Alice",
    "IsActive": true,
    "ItemIDs": 
    [
      {"ID":1},
      {"ID":2}
    ]
  },
  {
    "CustomerID": 2,
    "CustomerName": "Bob",
    "IsActive": true,
    "ItemIDs": 
    [
      {"ID":3},
      {"ID":4}
    ]
  }
]

or whole body placeholder

${input}

generates the following request body that uses the property names as column names from the input schema

[
  {
    "ID": 1,
    "Name": "Alice",
    "Items":
    [
      {"ID":1},
      {"ID":2}
    ]
  },
  {
    "ID": 2,
    "Name": "Bob",
    "Items":
    [
      {"ID":3},
      {"ID":4}
    ]
  }
]

for input where there is only one line, the following placeholder

${input.Items}

generates an array of rows of type Complex

[
  {"ID":1},
  {"ID":2}
]

or XML format supports single cell placeholders so following settings

<Customer><Name>${input.Name}</Name></Customer>

will generate

<Customer><Name>Alice</Name></Customer>
<Customer><Name>Bob</Name></Customer>

with a combination of XML header and XML footer. It can generate the following XML where the Root element Customers is used.

<Customers>
    <Customer><Name>Alice</Name></Customer>
    <Customer><Name>Bob</Name></Customer>
</Customers>

Placeholders for other configuration properties

You can use the single cell placeholder for other string configuration properties, which can be wrapped with additional text. This allows you to dynamically change the path of the request for the endpoint. But for these configuration properties, the placeholders are replaced only by the first line of input data.

Example

api/endpoint/${input.Method}

Follow redirect

If this option is enabled, the web browser automatically redirects you to a new URL if redirection is detected on the page (for example, an HTTP 301 or 302 response). This setting can be useful to ensure that you are automatically redirected to the correct page when a URL change occurs.

Fail on error response

If this option is enabled, the application performing the query discards the server response if it returns an error code. In other words, throw error for non 2xx response. This option can be useful in situations where it is important to respond immediately to errors and not continue processing the query further.

Output Format Type:

Select returned data type:

Base64 - data will be returned as Base64 string
Text - data will be returned as plain text - use OutputEncoding property to set output data character encoding type
JSON - data will be returned as a JSON object

Output Encoding

The character encoding used to convert bytes to text.

Input & Output Schema

Input

Data schema is optional

The connector does not expect a specific schema. The required data structure can be achieved by correct configuration. Although the selected connector doesn't require a schema generally, the individual integration task step may need to match the output data structure of the preceding task step and use a data schema selected from the repository or create a new input schema.

Output

The result of the API call is stored in the Content, ContentText or ContentJSON of the output schema.

There are tree possibilities for output data format:

Base64 - data will be Base64 encoded and returned into output property Content
Text - data will be encoded with selected OutpuEncoding into output property ContentText
JSON - data will be encoded and returned into output property ContentJSON

In addition to the content, the output also contains the StatusCode and Headers of the response. For more information about status codes, see the document HTTP response status codes. and the HTTP Headers headers.

Rest API output (ver. 2.1.0)

Column	Data type	Allow null	Description
StatusCode	string	No	HTTP response status code
Headers	`Rest API header 1.0.0`	Yes	Received HTTP headers as key/value pairs
Content	Base64	Yes	Serialized content of HTTP response into Base64
ContentText	string	Yes	Serialized content of HTTP response into string

Example output data for OutputFormat set to Base64

StatusCode: `String`	Content: `Base64`	Headers: `Rest API Header 1.0.0`
201	ewogICAgIlN1Y2Nlc3MiOnRydWUKfQ==	Output headers data

Output headers data

Key: `String`	Value: `String`
Transfer-Encoding	chunked
Connection	keep-alive
Cache-Control	private
Date	Thu, 17 Feb 2022 19:58:36 GMT
Server	nginx/1.14.1
X-AspNet-Version	4.0.30319
X-Powered-By	ASP.NET

where decoded response Content is:

{
    "Success":true
}

Example output data for OutputFormat set to Text

StatusCode: `String`	ContentText: `String`	Headers: `Rest API Header 1.0.0`
201	{ "Success":true }	Output headers data

Output headers data

Key: `String`	Value: `String`
Transfer-Encoding	chunked
Connection	keep-alive
Cache-Control	private
Date	Thu, 17 Feb 2022 19:58:36 GMT
Server	nginx/1.14.1
X-AspNet-Version	4.0.30319
X-Powered-By	ASP.NET

Example output data for OutputFormat set to JSON

StatusCode: `String`	ContentJSON: `JSON`	Headers: `Rest API Header 1.0.0`
201	{ "Success":true }	Output headers data

Output headers data

Key: `String`	Value: `String`
Transfer-Encoding	chunked
Connection	keep-alive
Cache-Control	private
Date	Thu, 17 Feb 2022 19:58:36 GMT
Server	nginx/1.14.1
X-AspNet-Version	4.0.30319
X-Powered-By	ASP.NET

where decoded response ContentJSON is:

{
    "Success":true
}

Release notes

3.1.7

Base URL labels and descriptions.

3.1.2

This version introduces an extended logging interface that enables the logging of events.

Enhancements:

New Log Hub Rules Template: Introduces the Advanced REST API connector event - reconnect, enhancing the connector's functionality.
Improved Logging for Reconnect Events: The connector now accurately logs the selected redirect message into the TaskRunLog. All essential information about reconnect events is now captured, facilitating easier monitoring and debugging for both company-level and admin-level users. With the introduction of multi-level logging, up to four entries may be recorded for a single event, providing a detailed view across user levels for improved transparency and troubleshooting.

3.0.3

Fixed shared nuget package versions.

3.0.2

Fixed right processing of nullable properties.

Rest API connector

Connector

Configuration

Rest API connection

Base URL

Ignore SSL Certificates

Authorization Method

Username

Password

Domain

Authorization token

OAuth2 token endpoint

OAuth2 token expiration

OAuth2 request headers

OAuth2 request body

NTLM ticket endpoint

NTLM ticket request beaders

NTLM ticket username

NTLM ticket password

NTLM ticket domain

NTLM ticket request body

NTLM ticket request result path entry

Request header ticket attribute

Rest API endpoint

Basic request types

Headers

Endpoint

Timeout

Request Type

DataContent Type

XML Header

XML Footer

Data

Using placeholders

Placeholders for creating body content

Placeholders for other configuration properties

Follow redirect

Fail on error response

Output Format Type:

Output Encoding

Input & Output Schema

Input

Output

Rest API output (ver. 2.1.0)

Example output data for OutputFormat set to Base64

Output headers data

Example output data for OutputFormat set to Text

Output headers data

Example output data for OutputFormat set to JSON

Output headers data

Release notes

3.1.7

3.1.2

3.0.3

3.0.2

Feedback

Was this page helpful?