HTTP Triggers allow you to trigger Processes by 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.

Parameters

HTTP Method

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 trough, while the others allows only the defined method. 

Url

All paths configured for an Agent group need to be unique in combination with the method, overlapping paths will cause errors. 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

  • Agent running on host myfrendsagent.example.org

  • Agent configured to use port 9998

  • HTTP Trigger configured as runmyProcess/{myvariable}

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: 

#trigger.data.pathParameters.myvariable = anyValyeForMyVariable
#trigger.data.queryParameters.anothervariable = 1
#trigger.data.queryParameters.yetanother = "foo"

Allowed Protocols

HTTP triggers can be configured 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).

Authentication

HTTP triggers can use four different kinds of authentication:

  • None - No authentication at all

  • Basic - Authenticate with HTTP basic authentication

  • Certificate - Use a client certificate to authenticate

  • Api key - Authenticate with an API key

We strongly recommend to use authentication only over HTTPS. 

Basic authentication authenticates the user either against the Active Directory or the local users. Which one is used depends on the Frends Agent service user. If the 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. The user name 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 authentication requires that the client certificate is valid for the Frends Agent user on the agent machine. Also the issuer for the certificate needs to be found in the agent user's Client Authentication Issuers certificate store.

Api key authentication uses an API key together with Rulesets to determine if the client has access to an url. For more information, see API keys.

Allow requests from these origins (CORS) 

If there is need to allow a certain page to trigger a process, it is possible to do with 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.

Public / private HTTP triggers

You can choose to mark a HTTP trigger public by checking the "Public - will 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. 

Pass content to process as unparsed, Base64 encoded byte array

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.

Trigger Reference List

  • #trigger.data.httpParameters  Dictionary<string, string> of parameters passed in the URL, both route and query parameters. (e.g. anotherVariable...)
    DEPRECATED - Use pathParameters or queryParameters to access the path and query parameters.

  • #trigger.data.queryParameters  Dictionary<string, string> of passed HTTP query parameters

  • #trigger.data.pathParameters  Dictionary<string, string> of passed path parameters

  • #trigger.data.httpHeaders  Dictionary<string, string> of passed HTTP request headers (e.g. Host, Accept..).

  • #trigger.data.httpBody  HTTP request body as a string

  • #trigger.data.httpMethod  HTTP method type (e.g. GET, POST..).

  • #trigger.data.httpRequestUri  Request URI (e.g.                     https://myfrendsagent.example.org:9998/runmyprocess/anyValueForMyVariable?anothervariable=1).

  • #trigger.data.httpClientIp  IP of the client as a string

  • #trigger.data.cookies   Cookies associated with the request as a Dictionary<string,string>

  • #trigger.data.username  The username associated with the caller. Only set if authentication is used. The following values are passed for the different types out authentications:
    Api Key: The name of the api key
    Basic authentication: The provided username
    Certificate: The certificate's SubjectName.Name field

  • You can try to access an optional reference from any of the references (e.g. #trigger.data.httpHeader.foo ) and if it is found the value will be returned and if not the value will be set to null.

Intermediate Response

A Process can return a response for the user before the Process is finished. This functionality is enabled by adding a Intermediate result 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.

HTTP Response Formatting

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 requests 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:

  • HttpStatusCode  Reponse status code (int)

  • Content  The body of the response (string)  

  • ContentEncoding  The encoding for the body, e.g. utf-8 (string)

  • ContentType   ContentType header value, e.g. application/xml or application/json (string)

  • HttpHeaders   Response headers (KeyValuePair[])

Http response

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.

          

          

            

Did this answer your question?