Graphlogic.ai documentation

Overview of BotBuilder and its tabs

External Requests tab

The External Requests tab is a tab where you can create and manage

@External Request⁠

s that can be used in

@Agent⁠

Navigating to the External Requests tab

There are two ways to navigate to the External Requests tab:

Go to the Resources tab and click on the External Requests button.

Go to the Agent Designer and open the External Requests tab.

List of External Requests

The External Requests tab displays a list of all the

@External Request⁠

⁠

Name displays the name of the

@External Request⁠

⁠

Alphabetical sort button — clicking on this button changes the sorting order from A-Z to Z-A and vice versa.

⁠

Method and URL — the destination URL where the

@External Request⁠

should be sent and the HTTP method of the

@External Request⁠

⁠

In use — indicates whether the

@External Request⁠

is being used in

@Agent⁠

⁠

Each

@External Request⁠

used in

@Agent⁠

s is marked with a checkmark and a Clarify button.

⁠

Clicking on the Clarify button displays icons of

@Agent⁠

s that use the

@External Request⁠

⁠

Searching for External Requests

Searching by Request Name

To search for

@External Request⁠

s by name, enter the desired value in the search field.

The list will display only the

@External Request⁠

s that contain the search string in their name.

⁠

Searching by Request Usage

Searching by

@External Request⁠

usage in the

@Agent⁠

s is done using the In use and Not in use filters:

Clicking the In use button displays only the

@External Request⁠

s that are used in the

@Agent⁠

⁠

Clicking the In use button replaces the Not in use filter with the Agent filter — a filter by

@Agent⁠

Clicking the Agent button opens the search panel by

@Agent⁠

⁠

To find

@External Request⁠

s used in specific

@Agent⁠

s, click on the desired

@Agent⁠

s in the list.

Clicking the Not in use button displays the

@External Request⁠

s that are not used in the

@Agent⁠

⁠

Creating, Editing, and Deleting External Requests

Creating an External Request

To create a new

@External Request⁠

, follow these steps:

Go to the list of

@External Request⁠

Click on the Create new button.

⁠

Clicking the button will open a form on the right panel for creating a new

@External Request⁠

Fill in the fields on the tabs of the form to provide the necessary details for the

@External Request⁠

Main Tab

The Main tab contains basic data for the

@External Request⁠

⁠

Name — the name of the

@External Request⁠

. The maximum length of the field is 1000 characters.

Description — the description of the

@External Request⁠

. The maximum length of the field is 1000 characters.

Method — the HTTP method for the

@External Request⁠

. The default method is GET.

GET

POST

PUT

PATCH

DELETE

HEAD

Endpoint — the webhook address to which the

@External Request⁠

should be sent. The maximum length of the field is 1000 characters.

Format of the value:

String

⁠

@Context Variable⁠

in the format {{var}}

⁠

@Expression⁠

@Expression with Control Structure⁠

. More details:

Using Syntax in External Request⁠

⁠

Headers Tab

On the Headers tab, you can add headers to the

@External Request⁠

⁠

Header — the name of the header. The maximum length of the field is 1000 characters.

Value — the value of the header. The maximum length of the field is 1000 characters.

Format of the value: plain text,

@Context Variable⁠

@Expression⁠

@Expression with Control Structure⁠

Query Parameters Tab

On the Query Parameters tab, you can specify parameters that will be appended to the URL of the

@External Request⁠

⁠

Parameter — the name of the parameter. The maximum length of the field is 1000 characters.

Non-Latin characters can be used in the parameter name. The value of the parameter will be encoded when the

@External Request⁠

is sent.

Value — the value of the parameter.

Format of the value: plain text,

@Context Variable⁠

@Expression⁠

@Expression with Control Structure⁠

Non-Latin characters can be used in the value. The value of the parameter will be encoded when the

@External Request⁠

is sent.

Data Tab

On the Data tab, you can specify data in JSON or XML format that will be sent in the

@External Request⁠

body.

⁠

Data type — the format of the data to be sent in the

@External Request⁠

body.

Default format: JSON

Formats:

JSON

XML

Data — a field for adding the

@External Request⁠

body template that will be sent. The maximum length of the field is 1000 characters.

Format:

When the data type is JSON: arbitrary text.

When the data type is XML: XML syntax. Tag case is important — <var></Var> will be considered an unclosed tag and the request will not be executed

Substitution of

@Context Variable⁠

@Expression⁠

@Expression with Control Structure⁠

In the request body template, you can specify a

@Context Variable⁠

in the format {{ var }},

@Expression⁠

@Expression with Control Structure⁠

, the values and results of which will be substituted when the request is executed. Learn more: Using syntax in External Request.

If the

@Context Variable⁠

cannot be found in the

@Chat Context⁠

, an empty value will be substituted.

If an error occurs during the evaluation of the

@Expression⁠

@Expression with Control Structure⁠

(e.g., division by 0), the

@External Request⁠

will not be sent, and the following

@Context Variable⁠

s will be created in the

@Chat Context⁠

⁠

@error⁠

= "Template rendering (request options) error occurred."

⁠

@request_success⁠

= False

⁠

@response_status_code⁠

= 499

⁠

@raw_response⁠

= ""

Value Format for

@Context Variable⁠

For Data type: JSON:

The value of a text variable is substituted into the template without quotes. If it is necessary to send a text value in JSON, it should be enclosed in quotes — "{{ var }}".

For example, if the string '89222203909' is stored in the variable {{ phone }} in the

@Script⁠

, then

when executing a request with Data = { "phone_num": {{ phone }} }, the body { "phone_num": 89222203909 } will be sent.

when executing a request with Data = { "phone_num": "{{ phone }}" }, the body { "phone_num": "89222203909" } will be sent.

For Data type: XML:

The variable should be written in an XML tag using curly braces {{ }} and considering the case. For example:

⁠

Response Tab

On the Response tab, you configure the parsing of responses to an

@External Request⁠

into

@User Context Variables⁠

When parsing a request response, the variables specified in the Value field are not

@Context Variable⁠

s, but are references to the body and headers objects (parts of the request response) and their properties.

⁠

Data type — format of received data (BODY from Response)

Default format: JSON

Formats:

JSON

XML

TEXT

⁠

The tabular part is an array of Variable - Value pairs for parsing data from the body and headers of the response to an

@External Request⁠

into

@User Context Variables⁠

for their use in the

@Script⁠

⁠

Variable — the name of the User context variables into which the value will be written. The maximum length of a field value is 128 characters. The name of User Context Variables must comply with the naming requirements for User Context Variables.

Value — key or Xpath path to the xml tag from the response body or headers, the value of which will be written to the

@Context Variable⁠

. The maximum length of a field value is 1000 characters. Once the maximum value is reached, no further characters are entered into the field;

It is possible to parse from the body and headers of the response:

body. — parsing from the request body;

headers. — parsing from request headers.

Value format: you can use

@Expression⁠

@Expression with Control Structure⁠

Important: access to the key of an object, if its name matches the name of
Reserved methods of objects⁠
, occurs through square brackets and quotes. Example: {{ data["keys"] }}

Important: a limitation has been implemented on the size of the body received in response to an external request: if the body size exceeds
@Limit on the size of the received body in response to an External Request ⁠
, then it is replaced with an empty body {}.

Examples of parsing the response body and headers into a

@Context Variable⁠

Example of a JSON body and parsing it in the

@Slot⁠

settings:

{

“par”: “value”,

“content”:

{

“par1”: “value1”,

“array”: [

{

“par2”: “value2”,

{

“par3”: “value3”,

}

]

}

⁠

Example of an XML body and parsing it in the

@Slot⁠

settings:

⁠

Example of an TEXT body and parsing it in the

@Slot⁠

settings:

For the TEXT type, only the entire body can be parsed.

⁠

Test Tab

On the Test tab you can test the operation of the

@External Request⁠

When creating a new

@External Request⁠

, before filling in the

@External Request⁠

parameters, the cURL field is not filled in.

⁠

When you open an existing

@External Request⁠

, cURL is generated automatically.

⁠

Refresh cURL — a button that, when clicked, updates the request in the cURL field on the Request tab in accordance with the

@External Request⁠

settings.

Test cURL — a button that, when clicked, sends the request generated in the cURL field to the external system.

Displaying the status of the request — the response received after sending the request. The color depends on the type of status received:

Successful status: 200 OK — green;

⁠

Statuses with warnings: from 201 to 399 — yellow;

⁠

Errors: from 400 and above — red.

⁠

Request section — the section contains data for testing

@External Request⁠

cURL — generated from the settings Incoming cURL request.

Update request from cURL — a button that, when clicked, updates the

@External Request⁠

from cURL fields.

When you click the button, a modal confirmation window appears:

⁠

To confirm the action, you must press the YES button. In this case, cURL validation occurs:

If there is no Endpoint or an incorrect cURL structure, an Invalid cURL error will be displayed and a pop-up notification Could’t parse cURL, request settings have not been updated.

⁠

If cURL is correct, the

@External Request⁠

settings will be updated: the fields on the Headers, Query Parameters, Data tabs will be cleared, and new information from cURL will be inserted into them. For example, if there are headers in the

⁠

, but there are no headers in the cURL field, then when you click Update Request from cURL, the current headers from the

⁠

will be removed and nothing will appear in their place.

Response section — the section contains the external system’s response to the request.

⁠

Before clicking the Test cURL button, the section is not available for opening (since the test request has not been sent and there is no response yet)

⁠

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.