REST Invocation Event

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

  1. Ensure HTTPS or HTTP is enabled. If neither port is enabled, the event rule cannot be created and a warning or err

  2. Define an Event Rule  using the REST Invocation Event trigger. The Event trigger appears in the Rule Builder.

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

  4. In the Endpoint box, provide the name of the endpoint.

  5. 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).

  6. For Authentication options, click Configure. The REST Invoke Authentication dialog box appears.

  7. 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")

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

  9. 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.

  10. 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")

$urlfirstQueryItemByNymber = $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")

$bodyfirstQueryItemByNymber = $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=$urlFirstQueryItemByNymber

    urlFirstQueryItemByNumberKey=$urlFirstQueryItemByNumberKey

    urlFirstQueryItemByNumberValue=$urlFirstQueryItemByNumberValue

    urlFirstQueryItemByName=$urlFirstQueryItemByName

    bodyQuery=$bodyQuery

    bodyFirstQueryItemByNumber=$bodyFirstQueryItemByNymber

    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"