Incoming request handling (exec)

Overview

Handles incoming requests using service scripts.

The following handling options are possible.

Role application handler

The request must be authorized under a user account; the role application service script is started as the handler. The role application is selected based on the Referer header, which contains the role application URI:

Referer: http://<ServerIP[:Port]>/app/<RoleappFolder>

This header is generated automatically by the browser for requests from the web application.

External system webhook handler.

The request must contain an Authorization header with the value Bearer <local_token>, where <local_token> is the token_local field value from the integration channel. The service script corresponding to the integration channel is started as the handler.

Authorization: Bearer cabcf10d692d5f8f386974d435997ea5

Requests

HTTP verb Endpoint Description

POST

/exec

Starting the incoming request handler with body transfer

GET

/exec

Starting the incoming request handler


Starting the incoming request handler with body transfer

Request

An arbitrary JSON object is placed in the request body. It will be available in the initiated service script handler as start parameter 4. Parameters are available at any time via the expression function startparam(N), where N is the parameter number. The script handler receives in launch parameters:

Table 1. Script handler parameter values
Function Description

startparam(1)

JSON representation of the request-related role application or integration channel entity.

startparam(2)

Method name from the HTTP request. Always "POST".

startparam(3)

URL from the HTTP request. Always "/exec".

startparam(4)

JSON object with the request body. If something else is passed in the body, it is also available.

startparam(5)

List of headers from the HTTP request.

startparam(6)

IP address of the HTTP request sender.

startparam(7)

HTTP request protocol. Always "http".

Example request
POST /exec HTTP/1.1
Referer: http://192.168.1.2:5800/app/folder/index.html
Content-Type: application/json; charset=utf-8

{
  "method": "myMethod1",
  "m_param": 1,
  "dt": "2019-11-01T11:01:59Z",
  "abc": "cuckoo",
  "isSmth": true,
  "a": [1,5,"aaa"],
  "o": {
    "x": 1,
    "y": "abc",
    "z": {
      "z1": [],
      "z2": {},
      "z3": null
    }
  }
}
Request parameters

The request may have an optional ?timeout=<sec> parameter in the URL query string. If present, integer values greater than zero are accepted. This parameter can only reduce the script completion wait time. The maximum wait time is configured in the opts.recv_timeout field of the corresponding entity (roleapp or integration_point for type public) or in the recv_timeout field of the corresponding type section (not public) of the webservices.json file.

Response

The response is returned after the initiated script handler completes. As a result of the script or a group of nested scripts, local variable values take final values. Some variable values are used when preparing the HTTP response. Matching is by variable name:

Variable name Purpose

response_code

HTTP response code, default 200.

response_headers

Additional response headers in JSON format. By default an empty string and only standard HTTP headers. If the standard Content-Type header is absent among the specified headers, its value defaults to application/octet-stream.

response_content

Response body. Absent by default.

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Some-Header: header value

Response body

Starting the incoming request handler

Request

The script handler receives in launch parameters:

Table 2. Script handler parameter values
Function Description

startparam(1)

JSON representation of the request-related role application or integration channel entity.

startparam(2)

Method name from the HTTP request. Always "POST".

startparam(3)

URL from the HTTP request. Always "/exec".

startparam(5)

List of headers from the HTTP request.

startparam(6)

IP address of the HTTP request sender.

startparam(7)

HTTP request protocol. Always "http".

Example request
GET /exec HTTP/1.1
Referer: http://192.168.1.2:5800/app/folder/index.html
Content-Type: application/json; charset=utf-8
Request parameters

The request may have an optional ?timeout=<sec> parameter in the URL query string. If present, integer values greater than zero are accepted. This parameter can only reduce the script completion wait time. The maximum wait time is configured in the opts.recv_timeout field of the corresponding entity (roleapp or integration_point for type public) or in the recv_timeout field of the corresponding type section (not public) of the webservices.json file.

Response

The response is returned after the initiated script handler completes. As a result of the script or a group of nested scripts, local variable values take final values. Some variable values are used when preparing the HTTP response. Matching is by variable name:

Variable name Purpose

response_code

HTTP response code, default 200.

response_headers

Additional response headers in JSON format. By default an empty string and only standard HTTP headers. If the standard Content-Type header is absent among the specified headers, its value defaults to application/octet-stream.

response_content

Response body. Absent by default.

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Some-Header: header value

Response body