REST Invocation Event

(Require EAM and HTTPS) The REST Invocation event is used to call up a specific endpoint, such as a remote webhook, or for non-administrative users to execute an event rule for inbound traffic.

NOTE: You do NOT need the REST API enabled to use this event trigger

If you are using a PowerShell script for the authentication or verification, The PowerShell authentication script has to set the HTTP.AuthSuccess variable to "true." The PowerShell script for signature checking has to set the HTTP.SignatureValid variable to true.

This new feature has nothing to do with the internal REST API functionality, but instead allows EFT administrators to expose or create "endpoints" that when accessed will trigger defined actions within the event rule. Additionally, the requests will go through either the HTTP or HTTPs protocol and NOT via our REST API protocol.

See also the sample PowerShell action for REST invocation, EFT response, and The list of variables EFT populates below.

To use the REST Invocation Event

Ensure HTTPS or HTTP is enabled. If neither port is enabled, the event rule cannot be created and a warning or err
Define an Event Rule using the REST Invocation Event trigger. The Event trigger appears in the Rule Builder.

Click the linked text, /endpoint, to open the REST Invoke dialog box.

In the Endpoint box, provide the name of the endpoint.
In the Expect at least box, provide the number of parameters required in the URL query. When this is defined, the Invoke would only trigger if the set amount of URL parameters are passed, For example https://192.168.100.165/endpoint?Value&Value2&Value3 is passing three parameters in the URL. If Expect at least is set to 2, then this would trigger the event rule because it at least 2 parameters are passed (but you can pass as many as you need).
For Authentication options, click Configure. The REST Invoke Authentication dialog box appears.

Under Authentication Type, click an option:

None - No authentication is required. When configured for None, any call to the EFT server that contains the endpoint will trigger the event rule.
Basic Auth - Use Basic authentication:

Credentials, provide the Token and Secret. (Copy and paste the token and secret generated by the provider, such as Twilio. They are case sensitive.) When using token/secret you must pass the defined token/secret within the URL request to the EFT server.
Clients and Permission Groups, click the folder icon, then move the Site user/groups that you want to Permit Execution. User/Group supports EFT users or groups defined in EFT.

PowerShell script - Click Configure and then point to a PowerShell script. The PowerShell script has to set the HTTP.AuthSuccess variable to "true":

$EFT_CONTEXT.SetVariable("HTTP.AuthSuccess", "true")

For signature Verification options, click Configure. The REST Invoke Verification dialog box appears.

The default is Disabled. To specify a different verification type. click PowerShell script, click Configure to select your script. then click OK. (The PowerShell script for signature checking has to set the HTTP.SignatureValid variable to "true." See the sample below.
Add Conditions (optional) and Actions (for example, Send email or write to a file), then click Apply.

EFT Response

The response includes an HTTP response code, and optionally, JSON payload with modified context variables.

By default, EFT responds with "200 OK." To modify the response code, set the HTTP.Response.Code variable. The body goes to HTTP.Response.Body.

EFT populates the following context variables

URL query:

HTTP.Request.Url.Query -- Raw query
HTTP.Request.Url.Query.Count -- number of items in the query
HTTP.Request.Url.Query[1] -- the first item (e.g file=untitled.txt)
HTTP.Request.Url.Query[1].Key -- the first item name (eg "file")
HTTP.Request.Url.Query[1].Value -- the value of the first item (e.g. "untitled.txt")
HTTP.Request.Url.Query[file] -- the value of the item named "file"

For the query items in the body (for POST requests with the content-type: application/x-www-form-urlencoded)

HTTP.Request.Body.Query
HTTP.Request.Body.Query.Count
HTTP.Request.Body.Query[1]
HTTP.Request.Body.Query[1].Key
HTTP.Request.Body.Query[1].Value
HTTP.Request.Body.Query[file]
HTTP.Request.Raw -- the whole request
HTTP.Request.Verb -- HTTP verb (GET, PUT, POST etc)
HTTP.Request.Url -- full path including query string
HTTP.Request.Url.Endpoint only endpoint path (e.g up to the '?' character if present)
HTTP.Request.Headers.Count -- total number of headers
HTTP.Request.Headers.Raw -- all headers separated by newline character
HTTP.Request.Headers[content-type] -- a header value by name
HTTP.Request.Headers[1] -- the first header name and value
HTTP.Request.Headers[1].Key -- the first header name
HTTP.Request.Headers[1].Value -- the first header value
HTTP.Request.Body.Raw -- raw body of the request
HTTP.Request.Body.Json.user.name -- value of the JSON payload (if present) by name. here you access the user.name field. Array fields are accessible via brackets like in javascript (e.g userrs[3])

Sample PowerShell action

Below is a sample PowerShell action that retrieves all context variables and outputs them back as a JSON, which you can use for testing.

$urlquery = $EFT_CONTEXT.GetVariable("HTTP.Request.Url.Query")

$urlqueryCount = $EFT_CONTEXT.GetVariable("HTTP.Request.Url.Query.Count")

$urlfirstQueryItemByNumber = $EFT_CONTEXT.GetVariable("HTTP.Request.Url.Query[1]")

$urlfirstQueryItemByNumberKey = $EFT_CONTEXT.GetVariable("HTTP.Request.Url.Query[1].Key")

$urlfirstQueryItemByNumberValue = $EFT_CONTEXT.GetVariable("HTTP.Request.Url.Query[1].Value")

$urlfirstQueryItemByName = $EFT_CONTEXT.GetVariable("HTTP.Request.Url.Query[a]")

$bodyquery = $EFT_CONTEXT.GetVariable("HTTP.Request.Body.Query")

$bodyqueryCount = $EFT_CONTEXT.GetVariable("HTTP.Request.Body.Query.Count")

$bodyfirstQueryItemByNumber = $EFT_CONTEXT.GetVariable("HTTP.Request.Body.Query[1]")

$bodyfirstQueryItemByNumberKey = $EFT_CONTEXT.GetVariable("HTTP.Request.Body.Query[1].Key")

$bodyfirstQueryItemByNumberValue = $EFT_CONTEXT.GetVariable("HTTP.Request.Body.Query[1].Value")

$bodyfirstQueryItemByName = $EFT_CONTEXT.GetVariable("HTTP.Request.Body.Query[c x]")

$HttpRequestRaw = $EFT_CONTEXT.GetVariable("HTTP.Request.Raw")

$Verb = $EFT_CONTEXT.GetVariable("HTTP.Request.Verb")

$Url = $EFT_CONTEXT.GetVariable("HTTP.Request.Url")

$Endpoint = $EFT_CONTEXT.GetVariable("HTTP.Request.Url.Endpoint")

$headersCount = $EFT_CONTEXT.GetVariable("HTTP.Request.Headers.Count")

$headersRaw = $EFT_CONTEXT.GetVariable("HTTP.Request.Headers.Raw")

$ContentType = $EFT_CONTEXT.GetVariable("HTTP.Request.Headers[content-type]")

$FirstHeader = $EFT_CONTEXT.GetVariable("HTTP.Request.Headers[1]")

$FirstHeaderKey = $EFT_CONTEXT.GetVariable("HTTP.Request.Headers[1].Key")

$FirstHeaderValue = $EFT_CONTEXT.GetVariable("HTTP.Request.Headers[1].Value")

$BodyRaw = $EFT_CONTEXT.GetVariable("HTTP.Request.Body.Raw")

$BodyJsonFirstItem = $EFT_CONTEXT.GetVariable("HTTP.Request.Body.Json.first")

$response = @{

urlQuery=$urlQuery

urlFirstQueryItemByNumber=$urlFirstQueryItemByNumber

urlFirstQueryItemByNumberKey=$urlFirstQueryItemByNumberKey

urlFirstQueryItemByNumberValue=$urlFirstQueryItemByNumberValue

urlFirstQueryItemByName=$urlFirstQueryItemByName

bodyQuery=$bodyQuery

bodyFirstQueryItemByNumber=$bodyFirstQueryItemByNumber

bodyFirstQueryItemByNumberKey=$bodyFirstQueryItemByNumberKey

bodyFirstQueryItemByNumberValue=$bodyFirstQueryItemByNumberValue

bodyFirstQueryItemByName=$bodyFirstQueryItemByName

HttpRequestRaw=$HttpRequestRaw

Verb=$Verb

Url=$Url

Endpoint=$Endpoint

Headers=$Headers

ContentType=$ContentType

FirstHeader=$FirstHeader

FirstHeaderKey=$FirstHeaderKey

FirstHeaderValue=$FirstHeaderValue

BodyRaw=$BodyRaw

BodyJsonFirstItem=$BodyJsonFirstItem

}

$json = $response | ConvertTo-Json

$EFT_CONTEXT.SetVariable("HTTP.Response.Body", $json)

Examples

In development testing and QA, we used curl to make HTTP or HTTPs calls to the EFT Server.

Making an HTTP REST request using curl:

HTTPs: When using HTTPs and a self signed certificate, curl will be unable to accept the certificate; therefore, you will need to add --insecure to the request, as shown below.

curl.exe --insecure https://<username>:<password>@<IP>:<PORT>/<endpoint>

curl.exe --insecure https://Ivan:test@192.168.100.165:443/QA

HTTP:

curl.exe http://<username>:<password>@<IP>/<endpoint>

curl.exe http://Ivan:test@192.168.100.165/QA

Passing parameters via the request:

In order to pass multiple parameters, the endpoint needs to include them: Multiple query string parameters via curl - Squirrel Code - Electric Imp Forums

For example if you set EFT to expect at least 5 URL requests, then the curl request would be as follows:

curl --insecure "https://192.168.100.166:443/QA?One&Two&Three&Four&Five"

Copyright © Fortra, LLC and its group of companies.
All trademarks and registered trademarks are the property of their respective owners.
v8.2.1 | 202409270221 | September 2024