API Trigger

Connect your Processes to fullblown APIs.

In order to connect a Process to an API and launch a Process in response to a HTTP request to that API, API Trigger can be used.

You can learn more about Triggers in general here.

What is API Trigger?

API Trigger, like HTTP Trigger, the Process is started in response to an incoming HTTP request. Unlike HTTP Trigger, API Trigger requires OpenAPI specification to be created in API Management before this can be used. Fields defined in API spec are included automatically as Trigger variables in the Process.

Usage

To use a Trigger in your Process, add it to your Process canvas, and connect it to the beginning of your Process using a Sequence flow. If you are using multiple Triggers in your Process, all Triggers must connect to the same shape, which is also the first non-Trigger shape in your Process.

Once added to your Process, you can change the Trigger's type to match your requirement and give it a unique name. By default, the Trigger's type will provide a corresponding name for the Trigger. You can then configure the parameters for the chosen Trigger type.

To use an API Trigger, you first need to have or create an API using API Management in Frends. Once you have an API endpoints specified, you can create a new Process directly from the API Management to use API Trigger connected to that API and endpoint, or add a new API Trigger shape to your Process, and select which API and endpoint it links to.

Once connected to an API, the settings for endpoint URL, method and authentication are set for the Process, and with these values set and the API and Process activated, the Agent will forward any matching HTTP requests to your Process and triggers it.

Configuration

To set up an API Trigger, add the shape to Process canvas and connect it as part of your Process. After that, you can select the Trigger type and configure the parameters for it.

The common parameters available for all Triggers are explained on the Trigger reference page. The following configuration parameters are available for API Trigger.

Select API operation

Searchable dropdown menu from where an existing API and endpoint can be chosen to link this Process to. Setting this value is mandatory, and after it has been set, the Trigger cannot be changed.

Alternatively, linking a Process from API Management to an endpoint will set this value automatically to the chosen API endpoint.

HTTP method

Read only value in API Trigger. Value is set in API definition for the chosen endpoint.

The HTTP method this Process listens to, such as POST, GET, DELETE or PATCH.

URL

Read only value in API Trigger. Value is set in API definition for the chosen endpoint.

URL endpoint the Trigger listens to. The base URL and port, such as myfrends.example.com:9998, is defined by the Agent Group, and the endpoint shown here in the Trigger is what comes after it, such as myprocesses/test-process.

As an example, Full URL for a Process with myprocesses/test-process URL would be https://myfrends.example.com:9998/myprocesses/test-process.

Allowed protocols

Option to select whether to listen to HTTP, HTTPS or both protocols.

Authorization

Read only value in API Trigger. Value is set in API definition for the chosen endpoint.

Option to select how requests are authorized. Supported methods include Basic, API Policy and Certificate.

Basic

Basic authentication authenticates the user either against the Active Directory or the local users, depending on the Frends Agent service user. If the Frends Agent uses a local user account, users are authenticated against the local machine users.

If the Agent uses an AD user account, users are authenticated against the AD users. Username and password need to be encoded with UTF-8 before being converted to Base64 for the basic authentication header. Basic authentication is not supported on Cloud Agents by the platform, but it is possible to check authentication headers in Process.

Certificate

Certificate authentication requires that the client certificate is valid for the Frends Agent user on the Agent machine. Also, the issuer of the certificate needs to be found in the Agent user's Client Authentication Issuers certificate store.

This is available for Windows Agents only. Cross-platform Agents require manually enabling client certificate support.

API Policy

API Policy authentication utilises the API Policies from API Management to authenticate the incoming requests to the endpoint. While most common method is to use API key within the API Policy, it's also possible to define OAuth authentication or public access through this option.

Allow requests from these origins (CORS)

Toggle switch and input field to enable cross-origin requests from specified domains to trigger the Process. List all the domains requests are allowed from as a comma or semicolon separated list. Asterisk (*) allows all domains to make requests to this endpoint. Disabled by default, disallowing cross-origin requests.

Private - will not be accessible on API Gateway

Toggle switch to disallow the endpoint to be visible in API Gateway, allowing the requests to trigger this Process only from the requests coming from the same executing Agent and internal network. Disabled by default, making it possible to trigger the Process from public internet.

OpenAPI Document

Displays the API definition for the endpoint this Trigger is linked to as a read only field. API definition is shown in YAML format.

Do not log trigger parameters

Toggle option that when enabled, hides the Trigger parameters from being logged in Process Instances.

Reference Values

In addition to the default Trigger reference values, API Trigger provides the following additional values.

#trigger.claimsprincipal (System.Security.Claims.ClaimsPrincipal)

The ClaimsPrincipal initialized from the access token used as authentication.

#trigger.data (Frends.ExecutableProcess.CaseInsensitivePropertyTree)

Object containing the data derived from input parameters and the resulting data from processing the Trigger.

#trigger.data.body (Object)

HTTP request body. If the body was in JSON format, its fields will accessible using dot notation, such as #trigger.data.body.MyField.

#trigger.data.header (Dictionary<String, String>)

HTTP headers included in the request. If the headers were defined in API definition, automatic casting will be attempted. If the parameter has a default value and the request does not contain the parameter, the default value will be passed to the Process. Header parameters defined in the API definition are always populated in the Trigger, even if no value is provided.

Header parameters defined in the API definition can be accessed with dot notation, such as #trigger.data.header.MyParameter.

#trigger.data.httpBody (String)

HTTP request body as a string.

#trigger.data.httpClientIp (String)

IP address where the request is originating from.

#trigger.data.httpCookies (Dictionary<String,String>)

HTTP cookies provided with the request.

#trigger.data.httpMethod (String)

HTTP method used to perform the request.

#trigger.data.httpRequestUri (String)

Specifies which URL was being requested, including the path and query parameters.

#trigger.data.path (Dictionary<String, String>)

Dictionary containing the path parameters from the initiating HTTP request.

If the parameters were defined in API definition, automatic casting will be attempted. If the parameter has a default value and the request does not contain the parameter, the default value will be passed to the Process. Path parameters defined in the API definition are always populated in the Trigger, even if no value is provided.

Path parameters defined in the API definition can be accessed with dot notation, such as #trigger.data.path.MyParameter.

#trigger.data.query (Dictionary<String, String>)

Dictionary containing the query parameters from the initiating HTTP request.

If the parameters were defined in API definition, automatic casting will be attempted. If the parameter has a default value and the request does not contain the parameter, the default value will be passed to the Process. Query parameters defined in the API definition are always populated in the Trigger, even if no value is provided.

Query parameters defined in the API definition can be accessed with dot notation, such as #trigger.data.query.MyParameter.

#trigger.data.username (String)

Username of the caller, if authentication was used. Value depends slightly by the authentication method used.

Basic

Local or AD username of the authenticated user.

Certificate

The certificate's SubjectName.Name field.

API Policy

Name of the used API key, if API key is defined as the authentication method.

Anonymous if public access (no authentication) is enabled.

Identity of the access token, if OAuth is defined as the authentication method.