Integration Object

Introduction

This article provides detailed design information about an HTTP Integration design object and its configuration options.

  • To learn how to use the integration designer to configure, test, and troubleshoot integrations, see Create an Integration.
  • To learn how to call an integration from other places in your application, see Call an Integration.
  • To learn how integrations and connected systems work together, see Connected System Object.
  • To learn how to use connected system templates to connect to different systems, see Connected System Templates.
  • For a real-world example of how to to build and use connected systems and integrations, see the Integration Tutorial.

The information below applies most directly to HTTP Integrations. If you have created an integration using a non-HTTP connected system template, the fields you see may be different.

HTTP Authentication

Basic

HTTP basic authentication is supported for Integrations, Connector Functions, HTTP File Download Smart Service, and HTTP File Upload Smart Service. When connecting with other systems, these objects and features can be used to easily connect with other systems.

Both connected systems and secure credentials stores can be used to store basic authentication credentials.

OAuth 2.0

Integrations support OAuth 2.0. OAuth 2.0 settings can be configured in a Connected System and used within an integration.

API Key

Integrations support API key authentication. Although API keys can be configured in the integration headers or parameters, the only way to securely configure an API key is by using a Connected System.

HTTP Properties

Each integration has the following properties.

Field Description
Name The name that will be used when executing an integration. Names are case-insensitive and must be unique across interfaces, integrations, expression rules, query 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.
  • Name: The name that is used when referencing the input within the integration definition, such as ri!input, or when passing arguments by keyword. Input names are case insensitive and must be unique within a given integration.
  • Type: The type of the rule input.
  • Array: Rule inputs can be either a single value or an array of values.
Integration Definition The integration is defined using the configuration pane of the integration designer.

HTTP Integration Definition

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.
  • Enter connection details below: The connection details will be unique to this integration and will not be shared using a connected system.
  • Use an existing connected system: This integraton will use a connected system and will inherit the connection details it provides. When selected, fields with values that are inherited from the connected system will be hidden.
You should use a connected system when configuring multiple integrations that connect to the same external service.
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 The type of authentication to use for the HTTP request.
  • None: No specific authentication will be applied to the request. You can provide custom authentication values in the URL, parameters, or headers as required by the external system. Client certificate/mutual SSL authentication can be enabled by uploading client certificates in the Admin Console. Services that use self-signed or internal SSL certificates can be enabled by uploading trusted server certificates in the Admin Console.
  • Basic: HTTP Basic authentication will be applied to the request using the username and password provided.
Note: This field is not shown when using a connected system. Integrations requiring OAuth 2.0 Authorization must use 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".
Usage The type of interaction that the HTTP request has with data in the external system.
  • Queries data: The request retrieves data but does not make any changes.
  • Modifies data: The request may create, update, or delete data in the external system.
Integrations that query data can be used in any expression. Integrations that modify data can only be used in a saveInto parameter, Web API, or process model. To learn how to call an integration, see Call An Integration.
Parameters The HTTP query parameters that will be appended to the URL using the format ?name1=value1&name2=value2.
  • Name: The parameter name.
  • Value: The parameter value.
Parameter names and values will be URL encoded before being added.
Headers The HTTP headers that will be added to the request.
  • Name: The header name.
  • Value: The header value.
Default headers will be added automatically but can be overridden by adding an explicit header with the same header name.
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.
  • Request bodies over 5 MB cannot be processed and will cause the integration to return an error. However, the file size of documents being sent do not count towards this limit.
  • The combined size of the files in the request body of a single integration cannot exceed 75MB.
Content Type The content type of the body that will be sent with the HTTP request.
  • JSON (application/json)
  • XML (application/xml)
  • Document (auto-detect)
  • Multipart Form Data (multipart/form-data)
  • Text (text/plain)
  • Custom: Define a custom content type using the provided field.
Content type applies only to requests with a body. See the page on content types for more information.
Automatic Request Body Conversion When the content type is set to XML or JSON, a checkbox appears beneath the integration request body. When enabled, the integration will automatically convert Appian values to the selected format. A CDT can be converted to JSON or XML. A dictionary, a list of dictionaries, and a list of CDTs can also be converted to JSON.

When the checkbox is enabled and the CDTs or dictionaries contain documents, those documents will be converted to Base64 and sent inline with the request body.
Automatic Output Parsing If the service returns a JSON result, the response body can be converted to an Appian value. The following options are available:
  • Convert the JSON Response body to an Appian value
  • Return the raw 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:
  • Use default error handling
  • Override and define all error conditions
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 and 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.

Encrypted Values

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:

  • Values entered directly are encrypted and will not be included in the package when the integration object is exported. Use an import customization file to set environment-specific values when importing into other Appian environments.
  • Expressions should be used only when you cannot enter values directly. Appian does not manage encryption or environment-specific import for values populated by expressions and a!scsField() is not supported (instead, use a connected system to share credentials across multiple integrations).

Outputs

Integrations return a result, an error, and a connected system as their output. To learn how to use these outputs, see Call an Integration.

Result

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.

Error

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

Connected System

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.

Versions

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.

Security

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:

Actions Administrator Editor Viewer Deny
Evaluate Yes Yes Yes Yes
View properties/definition Yes Yes Yes No
Test request Yes Yes Yes No
Update properties/definition Yes Yes No No
View security Yes Yes No No
Rename object Yes Yes No No
Update security Yes No No No
Delete object Yes No No No

Examples

Using Relative Path

When using a connected system with a base URL attached, designers should construct the URL for an integration using the Relative Path field.

  1. Base URL should be used to store a consistent prefix for the URLs of all an integrations for that connected system. Base URL is set on the connected system.
  2. Relative Path specifies the endpoint for a given operation. It is fully expressible, allowing for a dynamic URL based on rule inputs.
  3. URL Preview is determined by evaluating the relative path and appending it to the connected system’s base URL. This field shows you how Relative Path and Base URL will be combined at runtime to build the integration's URL.

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.

Sending a Binary Document

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.

images/Binary_Configuration.png

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.

images/Binary_Output_Request_Body.png

Sending Base64 Inline with JSON

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.

images//Base64_Inline_w_JSON_Request_Body_Annotated.png

  1. Set the content type of your request body to JSON (application/json).
  2. Ensure that the checkbox for automatic request body conversion is enabled. Base64 can only be sent when an Appian value is entered and automatically converted to JSON. If you manually construct the JSON string, documents will not be converted to Base64 or streamed.
  3. Enter a dictionary containing one or more documents. In this example, we cast integers to documents, but these can also be constants pointing to documents or rule inputs of type document. In fact, if you can pass in the whole dictionary as a rule input if you want to.

When the integration is executed, the dictionary is automatically converted to JSON and the documents are streamed as Base64 data.

images/Base64_Inline_w_JSON_Output.png

Sending Base64 Inline with XML

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.

images/Base64_Inline_w_XML_CDT.png

Once the CDT is created, you can configure the integration request body.

images/Base64_Inline_w_XML_Request_Body_Annotated.png

  1. Set the content type of your request body to XML (application/xml).
  2. Ensure that the checkbox for automatic request body conversion is enabled. Base64 can only be sent when a CDT is entered and automatically converted to XML. If you manually construct the XML string, documents will not be converted to Base64 or streamed.
  3. Enter the CDT you created. In this example, we cast integers to documents, but these can also be constants pointing to documents or rule inputs of type document. In fact, you can pass in the whole CDT as a rule input.

When the integration is executed, the CDT is automatically converted to XML and the documents are streamed as Base64 data.

images/Base64_Inline_w_XML_Output.png

FEEDBACK