HTTP Trigger

A HTTP Trigger is used when you want to trigger a Process using HTTP or HTTPS requests. The HTTP Endpoint is hosted by the Frends Agent, using the operating system's HttpListener interfaces. The Agent can be configured to listen for requests on multiple ports. Each hosted HTTP Trigger will have its own path for triggering just the specific Process. The difference between HTTP and API Triggers is that the API Trigger requires you to configure and bind an OpenAPI Specification Operation.

The HTTP Trigger has similar parameters to the API Trigger due to the similarities of using HTTP/HTTPS.

The HTTP Method determines which methods the Trigger URL can be called with. Allowed values are GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH and ANY. ANY allows any method to go through, while the others allow only the defined method.

All URLs configured for an Agent Group need to be unique in combination with the method as overlapping paths with identical HTTP methods will cause errors. This means that you can use the same URL endpoint with different Processes as long as you are using different HTTP methods. For instance, you can have a Process using endpoint foo/ with POST method and a Process using the same endpoint foo/ but with GET method.

The paths may contain variables as route parameters (inside the path: runmyprocess/{variable}) or as query parameters (in the end of the path: runmyprocess?id=1)

For example, if you have

This will register a Trigger that listens on the address https://myfrendsagent.example.org:9998/runmyprocess/{myvariable}

If you call the Trigger with the following URL:

https://myfrendsagent.example.org:9998/runmyprocess/anyValueForMyVariable?anothervariable=1&yetanother=foo

the following references and their values will be available in the Process:

The Allowed protocols for the HTTP Trigger can be defined to accept requests with HTTP, HTTPS or both. If a request is made with a protocol that is not allowed, the reply will be Forbidden (403).

The Authorization has the same options as an API Trigger apart from OAuth2:

Like in an API Trigger, if there is need to allow a certain page to trigger a Process, it is possible to do so with the Allow requests from these origins (CORS) flag enabling cross-origin resource sharing (CORS). Check the "Allow requests from these origins" setting, and define the allowed origins in the textbox. The * character allows calls from all origins. Multiple origins can be provided separated with a colon(,) or semicolon(;).

Note: if the call does not come from the default port, it must be included in the origin. The origin making the call must also support CORS.

You can choose to mark a HTTP Trigger as public by checking the Public - will be accessible on API Gateways setting. As the option says, this means the Trigger Endpoint will be published on API gateways. Private Triggers can only be accessed from the actual execution Agents. This way you can e.g. limit some APIs to be used only from your internal network.

You can process the HTTP request as raw bytes if you turn on the Pass content to process as unparsed, Base64 encoded byte array option. In this case, the HTTP message body will be left unparsed. Instead, the request will be passed as is, as a byte array (serialized as a Base64 string), accessible via the #trigger.data.httpContentBytesInBase64 reference.

Note: if the setting is turned on, the #trigger.data.httpBody reference will not be available.

A Process can return a response for the user before the Process is finished. This functionality is enabled by adding an Intermediate return Element to the Process. When this Element is executed the caller will receive a HTTP response from the Process. This can for example be used when calling a long-running Process and the caller should be notified that the long-running Task has started.

The HTTP Trigger returns the result of the executed Process as the HTTP response. The response varies according to the following conditions. When the result of the Process is a string, the string is set as the body of the response. If it was an object, it will be returned either as JSON or XML depending on the request's ACCEPT header or JSON by default. For example ACCEPT: application/XML would produce an XML response, while ACCEPT: application/json would produce a JSON response.

If the result is an object with the properties HttpStatusCode and Content, the result will be mapped to a response followingly:

The Process Elements return, Intermediate return and Throw all have the option to generate a pre-defined HTTP response. See HTTP Response results in Parameter Editor.

When using HTTP Trigger, remember to change the return or Throw from Expression to HTTP response, since it has to be changed manually.

The next article is Introduction to Queue Trigger