The capabilities described on this page are included in Appian's standard capability tier. Usage limits may apply. |
This page provides detailed design information about an HTTP Integration design object and its configuration options.
The information below applies most directly to HTTP and OpenAPI integrations. If you are using a pre-built connected system, the fields you see may be different.
Note: External systems connected to Appian require Transport Layer Security (TLS) 1.2 or above. If you are trying to connect to an older system that only supports TLS 1.0 or 1.1, follow the steps in the Post-Install Configurations page.
Each integration has the following properties.
Property | Description |
---|---|
Name | The name that will be used when executing an integration. Follow the recommended naming standard when creating this name. |
Description | Supplemental information about the integration that is displayed in the expression editor and in the objects grid of some Designer views. |
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.
Field | Description |
---|---|
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 http:// or https:// .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. |
Authentication |
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 query parameters that will be appended to the URL using the format ?name1=value1&name2=value2 .
|
Ignore query parameters with empty values | Determines whether or not query parameters with null or empty values will be appended to the URL. When checked, developers can use a single integration object for an endpoint with optional query parameters. |
Headers | The HTTP headers that will be added to the request.
|
Ignore HTTP headers with empty values | Determines whether or not HTTP headers with null or empty values will be added to the request. When checked, developers can use a single integration object for an endpoint with optional HTTP headers. |
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. Size limitations
|
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. |
Remove fields with null or empty values from generated JSON | Checking this box removes all fields with values that are null, empty strings, or empty arrays from the generated JSON request body. This behavior matches the removeNullOrEmptyFields parameter of the a!toJson function. This is important for certain web services, such as those that follow the OData protocol. Some web services treat fields with null values differently from fields that aren't included in the request body at all. Omitting a field may mean "don't modify the field," while sending a null value for that field would mean "write a null value to the field." Note: This field is only shown when the request body Content Type is set to JSON. |
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:
Selecting the binary option enables the integration to stream and download a binary file from the response body to create an Appian document. These documents can bes as large as 250 MB. It also sets the Usage field to Modifies data. 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), with the limitation that base64 strings longer than 4,000 characters are truncated. 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 fv!success , fv!error , and fv!result to reference the default integration outputs.
|
Error Message | Return an error message when this integration success criteria returns false. Use fv!success , fv!error , and fv!result to reference the default integration outputs. Use a!integrationError() to create the custom error message.
|
Enable HTTP request/response logging for this integration object | This field enables HTTP request/response logging for this integration. Integration calls will only ever be logged to integration_req_resp_activity.log if it is enabled in both the integration object and the Admin Console.The HTTP request/response logs may contain sensitive data or credentials. Before enabling HTTP request/response logs, it's important to understand the integration logging guidelines below. |
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 that enable HTTP request/response logging are much easier to troubleshoot when integrations fail. However, it's important to understand the safeguards we have in place before deciding whether a specific integration should be logged.
There are a number of safeguards in place to ensure that HTTP request/response logging doesn't store sensitive data when used correctly:
APPIAN_HOME/logs/perflogs/http-requests-and-responses/
subdirectory and the integration_req_resp_activity.log
log are only accessible by system administrators. This prevents any privilege escalations for designers who shouldn't be able to see certain integrations.Authorization
, X-Amz-Security-Token
, or Credential
."<binary>"
."<binary>"
.There are three cases under which you should not enable HTTP request/response logging for an integration:
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.
Field | Data Type | Description |
---|---|---|
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 Content-Type response header. |
statusCode | Number (Integer) | The HTTP status code that was returned. For example, 200 for a successful request. |
The error output contains the information about an unsuccessful request. An Integration error will output the following fields:
Field | Data Type | Description |
---|---|---|
title | Text | The general error summary. |
message | Text | The specific error message. |
detail | Text | The details about the error. |
Designers can use fv!success
, fv!error
, and 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, its 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 role map of an integration controls which developers can see or modify it and its properties. By default, integrations inherit the security of the folder that they are saved in. However, after creating the integration, you can disable that inheritance and modify the integration's security. See Editing Object Security to modify an integration's security.
The following table outlines the actions that can be completed for each permission level in an integration's security role map:
Actions | Administrator | Editor | Viewer | Deny |
---|---|---|---|---|
Execute the integration | Yes | Yes | Yes | Yes |
View the integration definition | Yes | Yes | Yes | No |
Duplicate the integration | Yes | Yes | Yes | No |
Test request | Yes | Yes | Yes | No |
Update the integration definition | Yes | Yes | No | No |
View the security | Yes | Yes | No | No |
Rename the integration | Yes | Yes | No | No |
Update the security | Yes | No | No | No |
Delete the integration | Yes | No | No | No |
Developers with Viewer permissions to this object can duplicate it. There are two ways to duplicate an object:
Once you select the Duplicate option, you will see the following dialog:
You can only duplicate the most recent version of an object. If you have unsaved changes and attempt to duplicate the object from within the designer, the most recent saved version of the object will be duplicated without the unsaved changes. A banner appears when there are unsaved changes to remind you before duplicating.
The integration object has limits on both the request body and the response body to ensure proper use.
Binary and base64 encoded documents have higher limits than plain text because they are streamed, and so they stay out of memory.
Note: The 75 MB base64 limits apply to the combined total of all documents in a single request/response. This means you can send one 75 MB file, or three 25 MB files, but you cannot exceed 75 MB across all the files that are sent. These documents do not count towards the 5 MB body limit.
Request body limits are determined by the Content Type value in the Request Body section.
Request Body Content Type | Request Body Limit |
---|---|
JSON (application/json) | 5 MB + 75 MB of base64 |
XML (application/xml) | 5 MB + 75 MB of base64 |
Document (auto-detect) | No limit. Best practice is to limit your binary request body to 250 MB. |
Multipart Form Data (multipart/form-data) | 5 MB, no limit on documents. Best practice is to limit total size of documents for a single multipart request to 250 MB. |
Text (text/plain) | 5 MB |
Custom | 5 MB |
Response body limits are determined by the Response Body Parsing value in the Response section.
Response Body Parsing | Response Body Limit |
---|---|
Return raw response body | 5 MB |
Convert JSON to Appian value | 5 MB + 75 MB of base64. Note: base64 strings longer than 4,000 characters are truncated. |
Convert binary to Appian document | 250 MB |
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.
Note: Base64 can only be sent when an Appian value is entered and automatically converted to JSON or use the . If you use a!toJson() to construct the JSON string, documents will not be converted to base64 or streamed.
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.
Note: Base64 can only be sent when a CDT is entered and automatically converted to XML. If you use toxml() to construct the XML string, documents will not be converted to base64 or streamed.
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 250 MB 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:
Integration Object