HTTP Trigger

Simple handling of HTTP requests in Frends.

In order to launch a Process in response to a HTTP request, HTTP Trigger can be used.

You can learn more about Triggers in general here.

What is HTTP Trigger?

HTTP Trigger starts the Process in response to an incoming HTTP request. This is useful for API integrations, allowing external systems to invoke Frends Processes via web requests. HTTP Trigger does not contain OpenAPI specification or API Management features, the Process acts as a standalone API endpoint.

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 HTTP Trigger, you need to configure the allowed HTTP method, URL endpoint the Trigger listens to, as well as the allowed HTTP protocols and authorization policies. With these values set and the Process activated, the Agent will forward any matching HTTP requests to your Process and triggers it.

Configuration

To set up an HTTP 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 HTTP Trigger.

HTTP method

The HTTP method this Process listens to, such as POST, GET, DELETE or PATCH. Set to ANY by default, allowing all HTTP requests to trigger the Process if the URL matches.

URL

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 defined here in the Trigger is what comes after it, such as myprocesses/test-process.

You can also define path variables here using curly brackets, for example customers/{customerid}/users would provide a Trigger reference value for customerid for your Process.

The URL should not start with slash, it is implicitly added to the full URL. 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

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.

Public - will be accessible on API Gateway

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

Pass content to Process as unparsed, Base64 encoded byte array

Toggle switch to enable receiving the incoming HTTP request as raw binary data. Enabling this allows the raw data to be read through #trigger.data.httpContentBytesInBase64 reference value, but also means that #trigger.data.httpBody reference value will not be available.

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, HTTP Trigger provides the following additional values.

#trigger.data (Frends.ExecutableProcess.CaseInsensitivePropertyTree)

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

#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.httpHeaders (Dictionary<String, String>)

HTTP headers included in the request.

#trigger.data.httpMethod (String)

HTTP method used to perform the request.

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

Dictionary containing both the path parameters and query parameters from the initiating HTTP request.

Path parameters defined in the Trigger URL can be accessed with dot notation, such as #trigger.data.httpParameters.MyParameter.

Deprecated. Use #trigger.data.pathParameters and #trigger.data.queryParameters instead.

#trigger.data.httpRequestUri (String)

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

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

Dictionary containing the path parameters from the initiating HTTP request.

Path parameters defined in the Trigger URL can be accessed with dot notation, such as #trigger.data.pathParameters.MyParameter.

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

Dictionary containing the query parameters from the initiating HTTP request.

#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 OAuth token, if OAuth is defined as the authentication method.