Integration Gateway

The Integration gateway facility allows you to define custom endpoints that can support custom authentication methods, request validation and rate limiting.

Integration gateway serves as an alternative to sink endpoints.

These endpoints can be used to define a custom endpoint for incoming webhooks, to process data provided by some external integration, or to proxy requests to another service.

Most of the basic operations can be achieved with the built-in functionality; more advanced operations can be implemented with simple JavaScript code snippets or workflows.

Defining a New Endpoint

To define a new endpoint, navigate to your Corteza instance (for example http://latest.cortezaproject.org/) and click on the "admin area" application.

Figure 1. The screenshot shows the app selector and the admin area application.

In the admin area, navigate to the System Integration Gateway sub-page. From the admin area, you can create and update your endpoints, as well as manage their access control.

Figure 2. The screenshot shows the route list screen.

When you click on the new button, a new screen will appear where you need to provide the base parameters of your endpoint.

Figure 3. The screenshot shows the user interface for creating a new endpoint.

Endpoint defines the path for the endpoint,
method defines the HTTP method for the endpoint.

The endpoint will be accessible under $BASE_URL/api/gateway$YOUR_ENDPOINT. To exemplify; the /test-endpoint endpoint for the https://latest.cortezaproject.org instance is available as https://latest.cortezaproject.org/api/gateway/test-endpoint.

You can specify different HTTP methods on the same route, but they need to be specified as different endpoints, ie. GET /customer and PUT /customer being two different integration gateway endpoints.

When you submit the forum, an additional "filter list" section opens below the base parameters. These filters allow you to validate and process requests, as well as defining the response.

Subsequent sections explore specific filters in more depth; what they do, and how they should be used.

Figure 4. The screenshot shows the user interface for attaching filters to the endpoint.

Request Validation

Request validation is done by using prefilters. prefilters allow you to validate the request and determine if the given endpoint should process it.

It is currently not possible to use the built-in authentication facility to authenticate requests. This feature will be added in the future.

Query parameters

The query parameters prefilter allows you to define a condition which asserts if the request can be processed by this endpoint based on the query parameters.

The query parameters are passed into the expression evaluation engine as they were provided. To exemplify; the query parameters ?param1=value1&param2=value2 would be referenced as param1 and param2 in the expression.

Refer to the expression reference for details regarding to writing these expressions.

The following example checks whether the given HTTP request defines the token query param of "super-secret-value".

Endpoint definition:

endpoint: /test-query
method: GET
query parameters prefilter expression: token == "super-secret-value"

An example of an HTTP request that conforms to the filter:

curl -X GET $BASE_URL/api/test-query?token=super-secret-value

An example of an HTTP request that does not conform to the filter:

curl -X GET $BASE_URL/api/test-query?token=some-other-value-i-guessed

Multi-word and multi-value query parameters can not be used currently.

Header

The header prefilter allows you to define a condition which asserts whether the request can be processed by this endpoint based on the request’s headers.

All system defined headers are passed into the expression evaluation engine as provided. User-define headers will automatically be converted into the snake-case + PascalCase format. To exemplify; test-header becomes Test-Header and test becomes Test.

The following header test: value would be referenced as Test in the expression.

Refer to the expression reference for details regarding writing these expressions.

The following example checks if the given HTTP request defines the Token header of "super-secret-value".

Endpoint definition:

endpoint: /test-query
method: GET
header prefilter expression: Token == "super-secret-value"

An example of an HTTP request that conforms to the filter:

curl -X GET $BASE_URL/api/test-query \
  -H 'Token: super-secret-value'

An example of an HTTP request that does not conform to the filter:

curl -X GET $BASE_URL/api/test-query \
  -H 'Token: some-other-value-i-guessed'

Multi-word and multi-value headers can not be used currently.

Profiler

The profiler prefilter enables a specific endpoint to gather useful statistics on an incoming route, such as headers, request body, content length, and request URI.

The prefilter can be added after any Query parameters or Header prefilter in order to enable the request to go through any authentication checks that might exist on a route.

See more on adding a profiler prefilter on the profiler page.

Request Processing

Request processing is done using processers. A processer defines the core business logic that the endpoint performs. Corteza allows you to process arbitrary payloads, such as a structured JSON or a binary attachment.

Table 2. A list of available processers:
Workflow processer	The workflow processer allows you to bind a workflow to the endpoint. Refer to the workflow processing page for details regarding the interaction.
Payload processer	The payload processer allows you to handle the request’s payload with the help of JavaScript. Refer to the Process Requests with JavaScript section for more details.

Response Preparation

Response preparation is done using postfilters. Postfilters allow you to finalize the request lifecycle depending on the result of the processing.

Table 3. A list of available postfilters:
Redirection	The redirect postfilter enriches the response payload with the required redirect HTTP headers.
Default JSON response	The JSON response postfilter enriches the response headers with the `application/json` content type and JSON encodes the processing results.

Debugging

System Logs

Enable debug logging in your .env file. Refer to the DevOps guide for details.

Inspecting Docker Logs

By default, Corteza logs are accessible via Docker logs. To access these logs, you need to firstly navigate to the directory where your Corteza instance resides in.

An example of navigating to the Corteza instance directory:

cd /opt/deploy/{CORTEZA_INSTANCE}/

You can use the docker-compose logs server command to access the logs output by the server.

Refer to the docker-compose logs documentation for available flags. Using docker-compose logs -f --tail=20 server will follow the logs (new logs will be appended at the bottom) and limit the output to last 20 logs.

A truncated example of running the log command:

docker-compose logs -f --tail=20 server

server_1  | 12:53:14.862        DEBUG   rbac    rbac/service.go:102     allow delete for corteza::compose:record/245030892240891907/245030893465497603/246932114543603715       {"bypass": [], "context": [], "common": [245030892072923139], "authenticated": [245030891334791171], "anonymous": [], "identity": 250804535289769987, "indexed": 63, "rules": 420}

You can also use grep or log filtering to show only specific logs. Refer to the DevOps guide for details regarding logging.

An example of using grep to show only debug logs:

user@server:/opt/deploy/{CORTEZA_INSTANCE}/$ docker-compose logs -f --tail=20 server | grep DEBUG
server_1  | 13:52:29.636        DEBUG   rbac    rbac/service.go:102     allow triggers.manage for corteza::automation:workflow/248229091554160643
Last updated 2021-09-27 18:01:45 +0200
Some content has been disabled in this document