This article provides detailed design information about an HTTP Integration design object and its configuration options.
The information below applies most directly to HTTP Integrations. If you have created an integration using a non-HTTP connected system, the fields you see may be different.
Each integration has the following properties.
|Name||The name that will be used when executing an integration. Names are case-insensitive and must be unique across interfaces, integrations, expression rules, constants, and functions.|
|Description||Supplemental information about the integration that is displayed in the inline help within the expression editor and the application contents grid.|
|Save In||The rule folder that the integration is saved into.|
|Rule Inputs||Rule inputs are used to pass data into the integration.
|Integration Definition||The integration is defined using the configuration pane of the integration designer.|
The configuration pane of the integration designer allows you to define the HTTP request details for your integration.
|Enter connection details below/ Use an existing connected system||Determines whether the integration will use a shared connection configuration from a connected system.
|URL||The HTTP URL that will be called. URL must begin with
Note: If you need to connect to this URL using a proxy server, that configuration can be enabled in the Admin Console. This field is not shown when using a connected system.
|Base URL||The base URL from your connected system. This field is not shown when entering connection details directly.|
|Relative Path||Used to specify the endpoint for a given operation. Relative Path will be appended to Base URL to form the URL for your integration.This field is not shown when entering connection details directly.|
|URL Preview||The URL for your integration given the current rule inputs. The URL Preview is determined by evaluating the relative path expression and appending it to the end of the connected system’s base URL.|
|Connected System||The connected system being used. This connected system represents the external system or service, and contains the base URL and authentication details that the integration will use to connected to that service. This field is not shown when entering connection details directly.|
Although basic authentication can be configured directly from an integration, connected systems are the best way to manage authentication. Using a connected system gives designers access to additional authentication options and allows them to manage authentication for several integrations in one place.
Note: This field is not shown when using a connected system.
|Username||The username to use for the authentication. This value is encrypted and supports environment specific configuration.
Note: This field is only shown when using basic authentication.
|Password||The password to use for the authentication. This value is masked, encrypted, and supports environment specific configuration.
Note: This field is only shown when using basic authentication.
|Send credentials preemptively instead of waiting for a 401 authentication challenge||Determines whether or not authentication credentials are sent only after a 401 Not Authorized response or, when selected, before the system has challenged.
Note: This field is only shown when using basic authentication.
|Method||The HTTP method with which to call the URL. Available options are "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", and "TRACE".|
|Timeout (sec)||The time, in seconds, after which an integration should time out and throw an integration error if a response hasn't been returned. This time pertains to the entire integration runtime (prepare + execute + transform). If left blank, the integration will run indefinitely until a response is returned or a connection error terminates the call.|
|Usage||The type of interaction that the HTTP request has with data in the external system.
This field is automatically set to Modifies data and disabled when an integration response is configured to convert binary or base64 to Appian documents.
|Parameters||The HTTP query parameters that will be appended to the URL using the format
|Headers||The HTTP headers that will be added to the request.
|Body||The body that will be sent with the HTTP request. This field can be used to send documents as either binary data or Base64 data. The format of the body should match the defined content type.
|Content Type||The content type of the body that will be sent with the HTTP request.
|Automatic Request Body Conversion||Checking this box causes the integration to automatically convert Appian values to the selected Content Type. If JSON is selected, you can pass either a dictionary or CDT as the request body. If XML is selected, you will need to use a CDT.
This checkbox also enables you to send Appian documents to other systems as base64. When the dictionary or CDT contain documents, those documents will be converted to base64 and sent inline with the request body.
Note: This field is only shown when the request body Content Type is set to JSON or XML.
|Response Body Parsing||If the service returns a binary or JSON response body, the response body can be converted to an Appian value. The following options are available:
If you see Convert JSON to Appian Value (prior version) for the Response Body Parsing, it means your integration was migrated from an earlier version of Appian that converts the JSON using a!fromJson_19r2(). You could choose to convert it to Convert JSON to Appian Value, but that may cause issues with parts of your application that rely on the integration. Because of this, for existing integrations we recommend continuing to use Convert JSON to Appian Value (prior version).
|Document Name and Extension||When an integration is configured to convert a binary response body to an Appian document, this field specifies the document name and/or extension. It is recommended to provide an extension at design time in order to ensure its accuracy.
If this field contains period(s), the document extension will be set to everything after the last period and the document name will be set to everything before the last period. So profilePicture.jpg would set the document name to profilePicture and the extension to jpg.
If this field doesn’t contain a period, the document name will be set to the entire field value and Appian will try to infer an extension from the response using the Content-Disposition and Content-Type HTTP headers. So profilePicture would set the document name to profilePicture and the extension would be inferred.
Note: This field is only shown when Response Body Parsing is set to Convert binary to Appian document.
|Convert base64 values to Appian documents||When Response Body Parsing is set to Convert JSON to Appian value, checking this box enables the integration to convert base64 values in a JSON response body to Appian documents. Once checked, further configuration will be required.
Checking this box enables the integration to stream up to 75MB of files as base64 in a single response body (one 75MB file, three 25MB files, etc). It also sets the Usage field to Modifies data and exposes a table, allowing you to specify the Response Body Location of each file in the JSON response body and (optionally) provide a Name for that document.
The Response Body Location dropdown contains the structure of the most recently received response body. At runtime, selected locations that are found in the response body will be converted to Appian documents. Locations that aren’t found in the response body will be ignored. This allows the grid to support optional document fields.
The Name field specifies the name and/or extension for each document. It is recommended to provide an extension for each document at design time in order to ensure their accuracy. If this field contains period(s), the document extension will be set to everything after the last period and the document name will be set to everything before the last period. So profilePicture.jpg would set the document name to profilePicture and the extension to jpg. If no extension is specified, Appian will try to infer an extension by using the Apache Tika library to analyze the bytes.
Note: This field is only shown when Response Body Parsing is set to Convert JSON to Appian value.
|Save Document(s) In||When an integration is configured to receive documents in the response, this field determines the document folder in which to save those documents. This can be configured using an expression, allowing the designer to set document security per integration call. Each user who will call an integration must have at least Editor permission to the selected folder.
Note: This field is only shown when an integration is configured to pull back documents in the response as binary or base64 values in a JSON response body.
|Error Handling||Override error handling to customize error messages or update the criteria for success to check for error messages in the body. The following options are available:
|Success Criteria||Return false when this integration should return an error. Use
|Error Message||Return and error message when this integration success criteria returns false. Use
Certain integration fields contain sensitive values like passwords. These values are managed differently depending on whether they are defined directly or are defined using expressions:
a!scsField()is not supported (instead, use a connected system to share credentials across multiple integrations).
Integrations return a result, an error, and a connected system as their output. To learn how to use these outputs, see Call an Integration.
The result output contains the HTTP response details.
|headers||Any Type||The list of HTTP response headers.|
|statusLine||Text||The HTTP response status line, containing the HTTP protocol version and response status code.|
|body||Any Type||The body of the HTTP response. If the HTTP response returns a JSON body, Appian can convert this to an Appian value by enabling automatic parsing. This allows Designers to use dot notation or indexing without the need to create a wrapper rule or expression first. Response bodies over 5 MB cannot be processed and will cause the integration to return an error.|
|contentType||Text||The content type of the HTTP response body, as specified in the
|statusCode||Number (Integer)||The HTTP status code that was returned. For example,
The error output contains the information about an unsuccessful request. An Integration error will output the following fields:
|title||Text||The general error summary.|
|message||Text||The specific error message.|
|detail||Text||The details about the error.|
Designers can use
fv!result to create custom error messages using a!integrationError(). Otherwise, a default error message is used after an unsuccessful request
When an OAuth connected system is used, it's value will be stored as part of the integration output. This value is used to generate an authorization link when a user needs to obtain a new access token.
When an OAuth connected system is not used for an integration, the value is null.
Each time you modify and save an integration, a new version is created. All objects that use the integration will use the latest version. All versions are accessible to designers who can view the integration, and an integration can be reverted back to a previous version at any time.
For information on how to manage object versions, see Managing Object Versions.
The security rolemap of the integration controls who can see or modify the integration definition and properties. However, integrations can be evaluated by any user regardless of their defined role in the security rolemap.
The following actions can be completed by each role:
When using a connected system with a base URL attached, designers should construct the URL for an integration using the Relative Path field.
These fields are only displayed when Inherit Base URL is selected. If you would prefer not to leverage the base URL for an integration, you can select Build Base URL from Scratch.
Designers can send documents in the request body as binary. To do so, they must first set the content type to Document (auto-detect) and enter a document in the request body.
In this example, we cast an integer to type document, but this can also be a constant pointing to a document or a rule input of type document.
When the integration is executed, the content type is automatically detected and the document is streamed as binary data.
Designers can send Base64 documents inline with JSON using a dictionary, a CDT, or a list of either. For this example, we will use a dictionary.
When the integration is executed, the dictionary is automatically converted to JSON and the documents are streamed as Base64 data.
Designers can send Base64 documents inline with XML using a CDT. First, they must create the CDT, structured like the XML they want to send and containing one or more fields of type document.
Once the CDT is created, you can configure the integration request body.
When the integration is executed, the CDT is automatically converted to XML and the documents are streamed as Base64 data.
Designers can configure an integration to pull a binary document from external systems. To do so, you will need to configure the integration response.
When the integration is successfully executed, a document will be created with the given name and extension and saved to the selected folder. Integrations can stream a binary file as large as 75MB from the response body. Because integrations that pull documents are automatically set to modify data, they must be called as a smart service. This means they can only be called in a saveInto parameter, web API, or process model.
When calling the integration from a process model, map a process variable of type Document to the output AC!Result.body:
When calling the integration from a web API or a saveInto on an interface, use the onSuccess parameter to save the document in fv!result.body to a variable:
Designers can configure an integration to convert base64 values in a JSON response body to Appian documents. To do so, you will need to configure the integration response.
Next, check the checkbox. In addition to disabling Usage and setting it to Modifies data, this will expose an empty grid and a disabled folder picker. As the instructional text states, you will need to run a test that returns successfully to proceed with configuration. At that point, the grid and picker will become enabled.
At runtime, configured locations that are found in the response body will be converted to Appian documents. Configured locations that aren’t found in the response will be ignored. This allows the grid to support optional document fields.
When the integration is successfully executed, each document will be created with the given name and extension and saved to the selected folder. Integrations can stream up to 75MB of files as base64 in a single response body (one 75MB file, three 25MB files, etc). Integrations that pull documents are automatically set to modify data, they must be called as a smart service. This means they can only be called in a saveInto parameter, web API, or process model.
When calling the integration from a process model, you can create a CDT for the response and map it to AC!Result.body. Alternately, you can map a process variable of type Document to a custom output for each document location:
When calling the integration from a web API or a saveInto on an interface, use the onSuccess parameter to save documents to variables: