Start integrating with ONEiO for free!
SIGN UP

Endpoint Type Configuration Guide - Custom REST

In this document, you will find detailed info about Custom REST Endpoint Type. This Endpoint Type is a Self-Service type, so users can add them without a need to reach out to ONEiO Support.

If you want to take a look at an example usage of the configuration, check out the article How to use the Custom REST Endpoint type.

 

Table of Contents

  1. General
    1. Authentication
    2. Basic
    3. OAuth
    4. Token
    5. Certificate
  2. Inbound from your system to ONEiO
    1. Receiver Settings
    2. Inbound Replacement Settings
    3. Response Settings
    4. Entity Type Resolving
    5. General Polling Configuration
    6. Inbound Attachments
    7. Attachment Download Settings
  3. Outbound from ONEiO to your system
    1. REST Settings
    2. Outbound Attachments
    3. Attachment Upload Settings
  4. Entity Type
    1. Response Handling
    2. Polling Configuration

 

General

 

General_1.png

 

Field Default value
Status Sets the status of the endpoint as Active/Suspended. The Suspended status would queue all the messages received and to be sent. Setting it back to Active would release all queued messages.  Active
Name The name of an endpoint. It is recommended to use short words since this name is used in displays throughout ONEiO.  
Base URL The base address of your REST API. You can test the HTTP connection by clicking the "Test Connection" button. Note that this function does not test the authentication, only if ONEiO can reach the endpoint, i.e., establish a network connection.  
Timezone The timezone of your system in relation to the outbound messages it sends to ONEiO. That is relevant if you want ONEiO to parse date type attributes which is useful for automatic conversion in the mapping process. UTC
Global Datetime Pattern

Date time pattern ONEiO uses to read DateTime fields and how ONEiO sends out DateTime fields.

The valid pattern is according to the DateTimeFormat. Additionally, the value of EpochTime or EpochTime_s can be used when the inbound date-time is in milliseconds or seconds since Epoch.

yyyy-MM-dd'T'HH:mm:ssZZ

 

Authentication

Method Supported by ONEiO authentication methods when sending messages towards your system. The available options are Basic, OAuth v2, Token and Certificate.  

Basic

Status Enables or Disables sending the credentials in the "Authorization" HTTP header.  
Username  Username of the integration user.  
Password Password of the integration user.  


OAuth

Status Enables or disables the OAuth mechanism.  
OAuth2 Client Id The OAuth client Id   
OAuth2 Client Secret The OAuth client secret  
OAuth2 Token URL The URL where the authentication token is taken from. Usually ends with /token  
OAuth2 Scope A comma-separated string of scope used for getting the token.  
OAuth2 Grant Type

The supported mechanism grant types:

RESOURCE_OWNER_PASSWORD (default)

CLIENT_CREDENTIALS

 

OAuth2 Authentication Scheme The authentication scheme used for retrieving the token. The possible values are header, query, and form. The default is header.  
OAuth2 Additional Parameters Additional parameters are sent when requesting the token. Parameters are separated with a semicolon and key and values with an equals sign.  

Token

Status
Enables token authentication
 
Token URL URI that will be used to authenticate  - accepts message header placeholders, like ${systemUri}  
HTTP Method HTTP method used to request a token  
HTTP Body

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 Headers

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 "\".

 

Token Request Header Key Name of the header that will contain the token  
Token Request Header Value Content of the header that will contain the token - supports token placeholder ${token}  
Response Token Path

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.


 

Refresh Status List of status split by "," that will refresh token when returned by message call  

Certificate

Status Enables/disables client certificate authentication.  
Client Certificate Data A base64-encoded string containing either a PKCS12 file or an unencrypted PEM-formatted private key and certificate.  
Client Certificate Password A password is needed if the data contains an encrypted PKCS12 file.  

 

Inbound from your system to ONEiO

Inbound_1.png

Your System -> ONEiO

Mechanism The mechanism for communication. Defines whether ONEiO is receiving messages from your system or polling your system for changes, or a combination of those two. 


Receiver Settings

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.

Authentication Method Supported by ONEiO authentication methods when receiving messages from your system. The options are Basic, Token, and OAuth v2. 
ONEiO Receiver QA The URL of the ONEiO REST receiver in the QA environment.
ONEiO Receiver PROD

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

Username

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

Authentication Token

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

Client Id

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

Inbound Content-type

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

Whitelist Filtering

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.

Representation

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.

Inbound Replacement

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

Request Method

HTTP method to be used when requesting replacement.

Request URI

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

Request Body

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

Request Headers

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

Response Template

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

Response Content-Type

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.

Response Status Code

Defines HTTP status code of a response by ONEiO.


Entity Type Resolving

Entity Type Element

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

Fixed 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

Transformer Defines the transformation type based on the response from the API of your system. Possible options are XML or JSON.
Strategy Defines the strategy for the polling application. Possible options are
Last Date Change (Default), Last Date Unsorted, Daily, Request Date, Stateless, and Entity State
Operation

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

Interval The interval between each poll is in milliseconds.


Inbound Attachments

Method

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. 

Access Method

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.

Duplicate Filtering Enables the function at ONEiO to filter the attachments in case they have already been "seen", i.e., we already received and parsed them at an earlier stage or they have been integrated by ONEiO.
Parent Element

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.

Actual Element

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.

Content-type Element

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

Filename Element

The name of the element that contains the filename

Data Element

The name of the element that contains the Base64 encoded attachment


Attachment Download Settings

Request URI

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 

Request Method

HTTP method to be used when downloading attachment

Request Headers

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 "\".

Request Body

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

Response Content-Path

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.  

 

Outbound from ONEiO to your system


REST Settings

Outbound Content-type Decides the content that is used in the outbound message. Possible options are JSON, XML, Multipart form-data and Application/x-www-form-urlencoded
Outbound Response Content-type Tells ONEiO the content type that the API will use in the sync response.
HTTP method of Create HTTP method used with CREATE messages. This means the very first message towards this endpoint of a certain ID. (e.g. start of a new conversation)
Target for CREATE Resource used with CREATE messages. This means the very first message towards this endpoint of a certain ID. The used in the call URI will be the combination of the base URL of the endpoint and this value.
HTTP method for Update HTTP method used with UPDATE messages. This means all the next messages towards this endpoint of a certain ID.
Target for UPDATE Resource method used with UPDATE messages. This means all the next messages towards this endpoint of a certain ID. The used in the call URI will be the combination of the base URL of the endpoint and this value.
Unrecoverable HTTP error codes

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.

HTTP Client Read Timeout

Read timeout for the client in milliseconds.

HTTP Client Connection Timeout

Connection timeout for the client in milliseconds.


Outbound Attachments

Method

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

Access Method

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.

 

Parent Element

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.

Actual Element

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

Content-type Element

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

Filename Element

The name of the element that contains the filename

File Extension Element

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.

Data Element

The name of the element that contains the Base64 encoded attachment


Attachment Upload Settings

Request URI

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

Request Method

HTTP method to be used to upload the attachment

Request Headers

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 "\".

Response Content Type

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

Request Content-Type

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  

Response Identifier Path

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

 

Entity Type

[Your Entity Type]
Entity Type Defines the entity type, an immutable property.
Display Name
Defines the display name of an entity that will be featured in messages, routing rules, etc. 
Inbound Mechanism Selecting "PULL" will toggle the polling configuration on an entity level.
Allow Missing Id for Updates By default, ONEiO needs to have information about the entity Id to be able to update it. This property overrides the behavior in a case when your API will handle the request based on other properties.


Response Handling

HTTP Success Codes

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

Id Element The path to the attribute containing the ID information in the synchronous response from the API of your system.
Success Element

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

Success Values

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

Error Element

The path to the attribute containing error information.


Polling Configuration

Status

Toggles the polling mechanism. 

HTTP Method

HTTP method of a polling request.

URI

HTTP target URI of a polling request.

Content Type

 The content-type HTTP header property of a polling request

HTTP Header

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 "\". 

HTTP Body

The body of the polling HTTP request.

Request Date Format

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

Request Timezone

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

Start Date

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. 

Entity Path

The path to the entity in the polling response. 

Id Element

The path to the Id attribute in the polling response.

Last Updated Element

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

Response Date Format

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.

Response Timezone

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

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Please sign in to leave a comment.