REST Bot API

In SimpleOne, REST Bot Engine allows you integrate with third-party services (such as messengers, AI systems, and so on) to solve various business tasks depending on the demand. For example, when an incident is created, the responsible group receives notification to the specific messenger with the specified subject.

To integrate with the third-party service, complete the following steps:

1. Configure the third-party service (register if needed, get an authorization token, check the API documentation).
2. Create a bot type record.
3. Configure the REST methods used to interact with the third-party service.
4. Configure a bot instance.
5. Set up the routing parameters.
6. Set up the routing rules.

Create a bot type

---

A bot type is a connecting element for the bot methods and bot instances. When created, you can easily specify which bots can use configured methods, and vice versa.

To create a new bot type, complete the steps below:

1. Navigate to Bots API → Bot Types.
2. Click New and specify a Name for the bot type.
3. Click Save or Save and exit to apply the changes.

Configure REST bot methods

---

Configure the REST API methods provided by the third-party system to interact with it. The bot methods are bound to the routing rules and routing parameters.

To create and configure a new bot method, complete the following steps:

1. Navigate to Bots API → Bot Methods.
2. Click New and specify a Name for a bot type.
3. Click Save or Save and exit to apply the changes.

Bot methods form fields

Field	Mandatory	Description
Name	Y	Specify a method name.
URL Suffix	N	Specify a relative path in addition to the request URL. The full URL of the request consists of the constant part specified in the URL field of the bot instance and of this URL suffix.
Request method	N	Specify the request method. Available options: GET POST To add more request method, add more choice options for this field.
Bot type	N	Specify the bot type that can use this method.
State parameter	N	Define the parameter that shows whether the request is successful or not. The field stores a string the response body must return for the request to be considered successful. If left empty, the request is always considered successful (except for errors on the instance).
Headers	N	Specify the method headers if necessary. Variables in the angle brackets are allowed. In the following example, the variable substitutes the token from the bot instance: authorization:Bearer <token>; Content-Type:application/json
Body	N	Specify the body of the request. Variables in the angle brackets are allowed. In the following example, the message is sent out to the messenger channel defined by the variable <routing_parameter_0> and routed to the thread in this channel defined by the variable <routing_parameter_1>. The content of this message is defined by the <content> variable. These variables should be defined in the Bot Routing Rule. The numeration of the routing parameters starts with 0.

Body example

{
"channel": "<routing_parameter_0>",
"text": "<content>",
"thread_ts": "<routing_parameter_1>",
}

Configure a bot instance

---

Create a bot instance to continue the integration process (use bot methods, routing rules).

To create a new bot, complete the steps below:

1. Navigate to Bots API → Bots.
2. Click New and specify a Name for a bot type.
3. Click Save or Save and exit to apply the changes.

Bot form fields

Field	Mandatory	Description
Name	Y	Specify the bot name.
Bot type	Y	Specify the bot type. It includes methods that this bot can use.
Token	N	Specify a token if the bot has authorized access to a third-party service. This token should be provided by the API provider.
URL	Y	Specify a URL for making requests. This part of the URL is permanent, unlike the URL suffixes specified for each bot method.

Configure routing parameters

---

The routing parameters are used in the bot's routing rules to make them more specific.

The main purpose of this functionality is to set up a correlation between a column value when the bot routing rule is triggered, and a column value used in the request body.

To create a routing parameter, complete the steps below:

1. Navigate to Bots API → Routing Parameters.
2. Click New and specify a Name for a bot type.
3. Click Save or Save and exit to apply the changes.

Routing Parameter form fields

Field	Mandatory	Description
Bot method	Y	Specify the method related to this routing parameter.
Column value	Y	Specify a column value for additional routing.
Parameter value	N	Specify the value for the parameter that substitutes the <routing_parameter> variable in the request body for the record that has the Column value in the specified column. You can create more than one parameter. They should be numbered starting from 0: routing_parameter_0 routing_parameter_1

Configure bot routing rules

---

The Bot routing rules table contains conditions and rules to trigger; when conditions are met, the trigger executes a request to the external service. The request history is in the Related Lists area for each record.

To create a new bot routing rule, complete the steps below:

1. Navigate to Bots API → Bot Routing Rules.
2. Click New and specify a Name for a bot type.
3. Click Save or Save and exit to apply the changes.

Bot Routing Rule form fields

General

Field	Mandatory	Description
Name	Y	Specify a routing rule name.
Active	N	Select this checkbox to activate the rule.
Bot	Y	Specify the bot for which you need to configure the routing rule.
Bot method	Y	Specify a related bot method.
Business rule	N	The business-rule is generated automatically after the record is saved. It is based on the parameters defined in the Bot and Bot method fields. This business rule triggers events in the system that meets the rule conditions. When updating the routing rule, the business rule updates automatically. When deleting the routing rule, the business rule deletes automatically.
Table	Y	Specify the table on which the routing rule works on.
Routing by column	N	Specify the columns that refer to the routing parameters. When you have to match more than one routing parameter with relevant columns, the columns should be stated in this field in the same order as the routing parameters in the request body.
Use Response	N	Select this checkbox when the processing of the designated REST response is needed. When selected, the Use Response tab appears on the form.

When to Run

Field	Mandatory	Description
Action Insert	N	Select this checkbox if the routing rule should perform actions when inserting a new record.
Action Update	N	Select this checkbox if the routing rule should perform actions when updating existing records.
Action Delete	N	Select this checkbox if the routing rule should perform actions when deleting existing records.
Order	Y	Specify the routing rule processing order.
Condition to run	N	Create a condition to meet to trigger the routing rule. Use the condition builder to build a filter that you needs. You can create complex AND and OR filters. An empty condition always returns true.

Content

Field	Mandatory	Description
Advanced content	N	Select this checkbox if the content transferred to the <content> variable must be dynamic. When selected, the Content script field appears.
Content script	N	Specify the dynamic content that should be transferred to the <content> variable. Enter your script and return the string value of the content using the return directive.
Content	N	Specify the static (some text or instruction) content that should be transferred to the <content> variable.

Use Response

Field	Mandatory	Description
Response parameter	Y	Specify a path to the necessary response parameter from the response body. Example: ts.user.id
Write to table	Y	Specify a table where the parameter is stored.
Write to column	Y	Specify a table column where the parameter is stored.
Source mapping column	Y	Specify the table column where the routing rule triggers. Specify the Source mapping column and Target mapping column fields if the resulting table is another one than the table where the request is triggered.
Target mapping column	Y	Specify the table column to put the request result. It works in the following way: The request result is recorded into the Write to table table record where the values in the Source mapping column and Target mapping column columns match. The value in the Source mapping column column of the Write to table should match the value of the Target mapping column of the Write to table. If the values do not match, an error is thrown. It also appears in the Bot Request History table.

Bot request history

---

To check out the history of the requests to the third-party services, complete the following steps:

1. Navigate to Bots API → Bot Request History.
2. Click the record you need to read.

Bot Request History form fields

Field	Description
Record	The record ID on which the request was generated.
State	The request state. Available options: Sent – the request is sent and processed successfully; third-party service did not throw any exceptions. Error – the request is sent and processed with errors displayed in the Response field. Sending – the request is sent and is waiting for the answer from the API provider. If no answer is received in 10 minutes, the request state is changed to Error automatically.
Bot Routing Rule	The bot routing rule on which the request has been generated.
URL	The URL of the request specified.
Method	The method of the request specified.
Headers	The headers of the request specified.
Body	The body of the request specified.
Response	The request response. It is used for debug or troubleshooting. You can find the errors returned by third-party REST API, and arisen on the server-side when a request was created or sent.