LISTEN

Creates a new endpoint on your service that listens for incoming http requests. Use at the start of a data flow with the IF operator.

Properties

Method
listen_method

The http request method for which the listening endpoint will accept requests.

valid options
GETCommonly used when retrieving information.
POSTCommonly used when sending data to the server.
PUTCommonly used to completely replace an existing record.
PATCHCommonly used to partially replace an existing record.
DELETECommonly used to delete an existing record.
COPYCommonly used to create duplicate of an existing record
HEADSimilar to a GET request, but the response only contains a header.
OPTIONSCommonly used when describing the communication options of the endpoint.
LINKCommonly used to establish a data reference between records.
UNLINKCommonly used to remove a data reference between records.
PURGECommonly used to delete cached resources.
LOCKCommonly used to restrict access to a specified record.
UNLOCKCommonly used unrestrict access to a specified record.
PROPFINDCommonly used when retrieving properties from a web resource.
VIEW

Primary Authentication
listen_auth

The reference to the authentication protocol used to restrict access to the listener to only those who provide the required credentials. Add authorization records to your project. Please see Project Authorizations for more info.

Endpoint URL Path
listen_customPath

The url path where your endpoint is listening on your Instalink account.

Accept Files
listen_acceptFiles

When enabled, the endpoint will accept file uploads.

Record Identifier Template ${}
listen_recordIdentifierTemplate

A searchable index of your incoming requests to the endpoint. This is important to set to make it easier to read your service logs. Accepts the templating syntax.

Use Namespace for Input
listen_useNamespace

When enabled, all data sent to the listener will be assigned to the key as defined in listen_namespace. By default the data is added to the root process data and is accessible by whatever keys may be provided in the request body. You should enable this if the request body is not expected to be an object with keys.

Input Namespace
listen_namespace

The key that will contain the data of the inbound request body.

Count Items Path
listen_countRecordsPath

A path into the input data to count the total number of records received for processing. The count is recorded in the Outbound Call Record for the request.

Collect Index Keys Path
listen_indexKeysPath

A path into the input data to record identifiers that will be indexed as part of the Outbound Call Record enabling the record to be searchable by the identifier.

Enable CORS
listen_enableCors

When enabled, the endpoint will respond with headers necessary to enable Cross-Origin Resource Sharing (CORS). CORS is a security protocol implemented by modern browsers that requires a server to opt-in to allow access to it from web pages served under domain's outside of its own. Effectively, enabling this option will grant web pages hosted under other domains access to this endpoint.

More information on CORS can be found at https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS.

CORS Allow Origin
listen_corsAllowOrigin

When CORS is enabled, sets the value of the Access-Control-Allow-Origin header. This header restricts the domains for websites that may access this endpoint. A value of "*" allows access from any origin.

CORS Allow Methods
listen_corsAllowMethods

When CORS is enabled, sets the value of the Access-Control-Allow-Methods header. This header restricts the HTTP request methods that may be used to access this URL. A value of "*" allows any HTTP method to be used. Acceptable methods may be provided as a comma-separated list (e.g. "POST, PUT, PATCH").

CORS Allow Headers
listen_corsAllowHeaders

When CORS is enabled, sets the value of the Access-Control-Allow-Headers header. This header restricts the HTTP headers that a web page is allowed to include in any requests made to this endpoint. A value of "*" allows any header to be provided. Acceptable headers may be provided as a comma-separated list (e.g. "X-Custom-Header, X-Other-Custom").

CORS Expose Headers
listen_corsExposeHeaders

When CORS is enabled, sets the value of the Access-Control-Expose-Headers. This header restricts the response headers that scripts in a web page are permitted to read. A value of "*" allows all headers returned in the response to be accessed. Permitted headers may be provided as a comma-separated list (e.g. "X-Custom-Header, X-Other-Custom").

CORS Max Age Seconds
listen_corsMaxAge

When CORS is enabled, sets the value of the Access-Control-Max-Age header. This header informs the browser the number of seconds that it may cache the results of CORS preflight requests. The value must be a non-negative integer (e.g. "600" to permit caching for 10 minutes).

CORS Allow Credentials
listen_corsAllowCredentials

When CORS is enabled and this option is enabled, an Access-Control-Allow-Credentials will be returned in the response with a "true" value. This option allows web pages to send credentials (cookies) to this endpoint.

Additional Authentications
authorizations

References to the project authorization records that are available to LISTEN actions in order to create permissioned requests.

Authorization
authorizations[].projectAuthorizationId

A reference to the Project Authorization that will be applied to this endpoint. Authorizations are commonly reused throughout a project and can be set up in the project settings view.

Accepted Files
acceptedFiles

A set of records that define the parameters of what file uploads a LISTEN action will allow.

Key
acceptedFiles[].key

The identifier of the file that is expected to be uploaded.

Max Size Per File
acceptedFiles[].maxFileSize

The maximum size, in bytes, that any individual file may be that is sent to the LISTEN action. Leave blank to allow any size file.

Max Files Per Request
acceptedFiles[].maxFiles

The maximum number of files that will be accepted by the listen request.

Observers
observers

A set of records that define mechanisms for inspecting success and error log occurrences as they occur.

Active
observers[].active

When enabled the observer will monitor the data flow for success and error occurrences.

Title
observers[].testTitle

The label that identifies the test results in the admin panel observers report.

Description
observers[].testDescription

A system generated description of what the test is evaluating, how often it runs, and what will occur when an alert or all clear is triggered.

Iteration (Minutes)
observers[].testInterval

How often, in minutes, the observer test will execute.

Duration (Minutes)
observers[].testPeriod

The timespan before the test execution that will be included in the evaluation.

Test Type
observers[].testType

The operator that determines how to analyze the success and error logs.

valid options
Percentage of requests with a success log
PERCENT_WITH_SUCCESS
Test for a specific percentage of all requests that had a success logged.
Percentage of requests with an error log
PERCENT_WITH_ERROR
Test for a specific percentage of all requests that had an error logged.
Total number of requests with a success log
TOTAL_WITH_SUCCESS
Test for a specific total number of all requests that had a success logged.
Total number of requests with an error log
TOTAL_WITH_ERROR
Test for a specific total number of all requests that had an error logged.

Condition
observers[].testCondition

The threshold operator that is applied to the test.

valid options
More Than
GOES_ABOVE
The percentage or total of logged actions has risen above the defined threshold.
Less Than
DROPS_BELOW
The percentage or total of logged action has fallen below the defined threshold.

Value
observers[].testValue

The threshold that must be met in a specific occurrence of a test to trigger an action

Consecutive Occurrences
observers[].testThreshold

The number of consecutive occurrences that the test has been met to trigger an action.

In Alert State
observers[].inAlarm

Indicates whether the observer has presently encountered conditions which have triggered an alert state.

Last Alert Time
observers[].lastAlarm

The most recent date and time when the observer was in an alarm state

Last All Clear Time
observers[].lastClear

The most recent date and time when the observer entered an all clear state.

Publish message on alert
observers[].publishOnAlert

When enabled the observer will send messages to the associated subscription topic when the observer enters an alert state.

Publish message on clear
observers[].publishOnClear

When enabled the observer will send messages to the associated subscription topic when the observer enters the all clear state.

Alert Topic
observers[].alertMessageTopic

The message subscription list to send messages to when the observer enters an alert state.

Alert Message Title
observers[].alertMessageTitle

When the observers enters the alert state the message sent to subscribers will contain this value as the subject.

Alert Message Content
observers[].alertMessageContent

When the observers enters the alert state the message sent to subscribers will contain this value as the message content.

Clear Topic
observers[].clearMessageTopic

The message subscription list to send messages to when the observer enters an all clear state.

Clear Message Title
observers[].clearMessageTitle

When the observers enters the all clear state the message sent to subscribers will contain this value as the subject.

Clear Message Content
observers[].clearMessageContent

When the observers enters the all clear state the message sent to subscribers will contain this value as the message content.

Form Fields
formFields

A set of records that define input fields for Instalink forms within the admin panel.

Field Key
formFields[].key

The key that will be used for the form field when submitting to the server.

Data Type
formFields[].dataType

The type of form field for this input

valid options
Text
text
A short-form text input field.
Long Text
text:long
A long-form text input field.
Checkbox
boolean
A checkbox that can be set to on or off.
Date and Time
time:datetime
A date and time selection form field.
Hidden
hidden
A hidden form field with a preset value.
Password
text:password
A password form field with the input value obscured for security.
File
file
A file upload form field.
Consumer Profile
profile
A selector for a consumer profile used for authentication.

Default Value
formFields[].defaultValue

The initial / default value for the form field.

Label
formFields[].label

A label for the form field that will be included in the form.

Required
formFields[].isRequired

When active, the form will not be allowed to be permitted if no input has been received for this form field.

Parameter Documentation <HTML>
formFields[].documentation

Utilized when generating documentation for the endpoint. HTML is permitted.