Endpoint Type Configuration Guide - Custom REST

The supported mechanism grant types:

RESOURCE_OWNER_PASSWORD (default)

CLIENT_CREDENTIALS

JWT

HTTP body of the token request - supports ${username} and ${password} placeholders.

If content type "application/x-www-form-urlencoded" is needed, the user should encode the body by himself, with the exception of the username and password placeholders, which will be encoded automatically.

HTTP header used in the token request, if needed.

The syntax should be like this: (key=value;key2=value2;key3=va\;lu\=e).

If ";" or "=" need to be used in the header values, they need to be escaped with "\".

Path of the token using structured path. Supports XML and JSON responses.

If the token is returned as text, this property should not exist at all.

When we're getting a JSON response that is just a quoted string, we need to have this property set to empty (= "") or "/", both will work.

If the Receiver Settings aren't shown in your Custom REST endpoint, first select any other mechanism in the authentication method and select the mechanism you intend to use.

Then, select the Authentication Method. You will be now able to the Receiver Settings section containing the Receiver URIs and generate new password button.

The URL of the ONEiO REST receiver in the PROD environment.

Username generated by ONEiO. The button to the right will generate the password.

The authentication token needs to be inserted into the URL as a query parameter.

Client ID generated by ONEiO. The button on the right will generate the client secret. 

What kind of transformation is done to inbound messages. The possible values are JSON, XML (Default), www_form_urlencoded, and multipart form data

A comma-separated list of conditions that must all match in order to allow the inbound message to be processed. Each contains an attribute name, operation, and value. Supported operation types are:

= (or ==) for EQUALS

!= for NOT EQUALS

IN which evaluates to true if any of the values in the list are equal to the value compared to.

Defines the representation of the attributes when parsed by ONEiO from the original payload. Which in turn affects the path for mapping an element. I.e., dot (.) versus slash(/) notation. See more about the attributes representation in this article.

Enables or disables inbound replacement. Inbound replacement will replace the inbound message completely with the response that is fetched from the given URL, based on configuration. The inbound message must be replaced by a message having the same content type, e.g. XML to XML, JSON to JSON. 

Inbound Replacement Settings

HTTP method to be used when requesting replacement.

URI to be used when requesting replacement (supports placeholders).

Body to be used when requesting replacement (supports placeholders).

HTTP headers to be used when requesting replacement

Syntax: (key=value;key2=value2;key3=va\;lu\=e).

If you need to add ";" or "=" to the values, they need to be escaped with "\".

Response Settings

Allows to create a template for a message ONEiO would respond to a request from your system.

Defines a content-type for the result of the reply template processing. Does not need to be set if the response content-type should be the same as the request content type.

Defines HTTP status code of a response by ONEiO.

Entity Type Resolving

The element in the inbound message we can reference as the Entity Type.

For use when there is no element representing the entity type in the inbound payload or to use a fixed entity type. 

Set one of the existing configured entities as fixed in these cases (i.e. Incident).

General Polling Configuration

Handle the polling strategies differently based on the date comparison used by the target API to prevent losing messages. Possible options are > (Greater Than) and => (Greater Than or Equal)

The default value depends on the strategy:

Last Date Change: Greater Than

Daily: Greater Than,

Last Date Unsorted: Greater Than

Request Date: Greater Than or Equal,

Otherwise: Greater Than

Inbound Attachments

Defines if the attachment data is part of the inbound message fully (i.e., base64 data element) or if there is a need for an additional download action. 

Defines the way that the system will iterate over the list of attachments as seen in the inbound message:

Array - The attachment objects are in a JSON array

Element Name - Each attachment object is in a separate field and the field name is indexed.

Single Element - There is only a single attachment element. I.e. not inside an array nor indexed.

The name of the parent element that contains all the actual attachment elements. You can give a static path for the element as well, e.g. data.attachments would mean that the element is a child of data element and is named attachments.

The name of the actual attachment element whose child elements contain the actual data, empty string tries getting the attachments directly from the path of the Parent Element.

The name of the element that contains the content type of the file. 

The name of the element that contains the filename

The name of the element that contains the Base64 encoded attachment

Attachment Download Settings

URL from where the attachments will be downloaded. The value of this property can contain placeholders that could be some value in the attachment representation in the inbound message 

HTTP method to be used when downloading attachment

The HTTP headers that will be used in the attachment download.

The syntax should be like this: (key=value;key2=value2;key3=va\;lu\=e).

If you need to add ";" or "=" to the values, they need to be escaped with "\".

Body of the HTTP request done to download an attachment. If no body is needed, e.g. we're just doing an HTTP get to a URL, then this property should not be configured at all

When the response to the HTTP request to download an attachment isn't directly the file itself, this property is used to configure a path where the attachment content is taken from. It is assumed that the attachment is in Base64 format.  

List of numeric HTTP response codes that are to be handled as non-recoverable when sending messages to your REST API. If ONEiO receives an error code that is not on the list, it will retry the message automatically, indefinitely. If ONEiO receives an error code that IS on this list, the message will result in an error. Values are separated by a comma.

Read timeout for the client in milliseconds.

Connection timeout for the client in milliseconds.

Defines how ONEiO handles the outbound attachments. The possible options are Inline Base64, Upload, and Multipart Form Data.

Defines the way that the system will iterate over the list of attachments when forming the outbound message:

Array - The attachment objects are in a JSON array

Element Name - Each attachment object is in a separate field and the field name is indexed.

Single Element - There is only a single attachment element. I.e. not inside an array nor indexed.

The name of the parent element that contains all the actual attachment elements. You can give a static path for the element as well, e.g. data.attachments would mean that the element is a child of data element and is named attachments.

The name of the actual attachment element whose child elements contain the actual data, empty string places the attachments directly under Parent Element.

The name of the element that contains the content type of the file. 

The name of the element that contains the filename

Name for the element that contains the file extension of the attachment. If the attachment doesn't have an extension at all, an empty value is put in the element.

The name of the element that contains the Base64 encoded attachment

Attachment Upload Settings

The URL to where the attachments will be sent. It accepts placeholders, such as content type and filename. 

HTTP method to be used to upload the attachment

HTTP headers that will be used in the attachment upload request.

The syntax should be like this: (key=value;key2=value2;key3=va\;lu\=e).

If you need to add ";" or "=" to the values, they need to be escaped with "\".

The content type of the response returned on the request to upload an attachment

Replace the content type of file service with a fixed one if configured when uploading attachments.

If this property is not set it will use the one set on file service at ONEIO  

Path in the response that contains the identifier object of the response, like id, or token.

Defines a comma-delimited list of HTTP codes representing a success of an operation. (i.e. 200,201,202)

The path to the attribute containing the status of a successful operation. This property is mutually exclusive with the "Id Element".

Defines a comma-delimited list of values representing a successful operation.

The path to the attribute containing error information.

Polling Configuration

Toggles the polling mechanism. 

HTTP method of a polling request.

HTTP target URI of a polling request.

 The content-type HTTP header property of a polling request

Defines all the HTTP headers of a polling request.

Syntax: (key=value;key2=value2;key3=va\;lu\=e).

Characters "=" and ";" if present in the value of a header need to be escaped with "\". 

The body of the polling HTTP request.

The format of the last changed date parameter in the polling request. The syntax is according to the DateTimeFormat with the additional support of Unix Epoch TIme in milliseconds and seconds as EpochTime and EpochTime_s. 

The timezone of the last changed date parameter in the polling request. 

The value of the last changed date parameter in the initial polling request. If not defined the current time will be used in the initial query. 

The path to the entity in the polling response. 

The path to the Id attribute in the polling response.

The path to the last changed date attribute in the polling response.

The format of the last changed date attribute in the polling response. The syntax is according to the DateTimeFormat with the additional support of Unix Epoch TIme in milliseconds and seconds as EpochTime and EpochTime_s.

The timezone of the last changed date attribute in the polling response.