The HTTP output in ArcGIS Velocity allows you to send features and other text to an HTTP endpoint through POST, PUT, or DELETE requests. A request is sent for each output feature sent to the output.
Example
An analyst configures an HTTP output to send features in a custom JSON format to a designated webhook.
Usage notes
Keep the following in mind when working with the output:
- When sending JSON in a request body, wrap the JSON with the Text() Arcade expression to properly format the JSON.
- When using the HTTP output, it is important to understand the velocity of the data. Each record sent to the output generates a separate request. This can quickly overload the capacity or rate-limiting settings of a web server. Use the HTTP output for incidents expected to occur infrequently.
- When using Open Authorization (OAuth) authentication, the following apply:
- The HTTP output type supports authentication using OAuth 2.0 for HTTP endpoints that follow the Client Credentials or Password grant types. These OAuth grant types follow a pattern that includes the configuration of an HTTP request to fetch an access token, and, optionally, configure a request to use a refresh token to retrieve new access tokens. During the configuration of the access token request, you are prompted to identify the access token and optional refresh token, as well as expiration JSON key fields from the response of the OAuth authorization server. If an expiration is selected, you must define the expiration type (duration or timestamp) and units. To configure an expiration timestamp that is expressed as a string, set the expiration unit to Other and specify the date format by adding an expiration date formatting string. If a refresh token is specified without expiration, the feed attempts a refresh token request if the main data request fails twice in a row.
- If a refresh token is identified from the access token request, you must use the $refreshToken global variable to define where the refresh token is used in the configuration of the refresh token request. Optionally, the $accessToken global variable is available to be used in the refresh token request. Both $refreshToken and $accessToken global variables are available for referencing in the POST body, URL parameters, and Custom headers parameters.
- When returning to the configuration of the data request, you must use the $accessToken global variable to define where the access token is used. This is often in an Authorization custom header with the Bearer $accessToken value.
- Access tokens can be stored as JSON Web Tokens (JWT). If you are using a JWT for the access token, turn on the option to Use JWT format. Velocity decodes the token and if the payload includes an exp claim, this value is automatically used as the expiration time. The exp is the expiration timestamp of the access token in epoch seconds.
The HTTP output enables users to dynamically populate the URL or custom header values from field values. This allows users to construct endpoint URLs, custom headers, and URL parameters that are specific to each record being processed.
Users can reference field values in the URL, Custom headers, and URL parameters using one of the following formats:
- $feature.fieldName for standard field names.
- $feature['field name'] when the field name contains spaces.
To support connection testing and validation, sample values must be provided for each referenced field used in the URL, Custom headers, or URL parameters. These values are used during analytic validation and while testing the connection to the target system. At runtime, Velocity replaces each placeholder with the corresponding attribute value from the current record.
Assume your analytic includes a field named sensor_id. You can define the output URL as https://yourAPIURL.com/$feature.sensor_id. For a record where sensor_id = 1234, the output resolves to https://yourAPIURL.com/1234. The same pattern can be used for Custom headers and URL parameters.
- When sending an Arcade expression that includes attribute fields in the request body, sample values are required to evaluate the expression. Use the Sample values drop-down to provide representative values for any attribute fields that are referenced in the Arcade expression.
Parameters
The following are the parameters for the output:
| Parameter | Description | Data type |
|---|---|---|
| URL | The URL over which the output requests are sent. | String |
| HTTP method | The HTTP method for the request. Choices include POST, PUT, and DELETE. | String |
| POST body | The JSON Arcade expression. | Arcade Expression |
| Content-Type | The content-type header for outgoing requests. Choices include the following:
| String |
| Authentication type | Choose between None (no authentication), Basic, or OAuth authentication option. If the Basic authentication option is configured, additional fields appear, prompting you to type your username and password. If the OAuth authentication option is configured, a pop-up window appears, allowing you to configure the following:
Once the above are specified, the connection is tested. You must click to identify the access token (and optionally, the refresh token and expiration value) in the JSON response. If a refresh token value is specified, an additional pop-up window appears, allowing you to configure the following:
Once the above are specified, the connection is tested. You must click to identify the access token and refresh token in the JSON response. | Various parameters |
| URL parameters | Optional URL parameters that are included in the URL of the HTTP request sent to the specified website. While parameters can also be set in the URL parameter above, the URL parameters entered here as separate parameters override any matching parameter specified in the URL parameter. URL parameters defined in this parameter are always URL encoded. | Key-Value pair |
| Custom headers | Optional custom headers that are included in the HTTP request sent to the specified website. For example, custom headers can be used to specify a third-party API key or authorization header. | Key-Value pair |
| Additional logging | Optionally, turn on logging for raw HTTP requests and responses issued by Velocity. Note:This parameter should only be turned on for troubleshooting and turned off when troubleshooting is complete. Once turned on, start the analytic and the debug level logs are available on the analytic logs page. If necessary, contact Esri Technical Support for assistance with troubleshooting. | Boolean |
| Sample values | Allows users to define sample data for each field referenced by $feature.fieldName or $feature['fieldName']. These values are required for connection testing and validation. | Key-Value pair |
Considerations and limitations
Consider the following when using the output:
- When using the OAuth authentication option, keep the following in mind:
- Multiple requests to an authorization server and the associated data endpoint occur when creating an output. Some APIs implement rate limiting for certain requests and this can affect output creation.
- For security reasons, the access token requests POST body must be reconfigured when editing the authentication parameters.
- The web server must be externally accessible on the internet.