Integration Object

Introduction

This article provides detailed design information about the 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 Objects.
  • For a real-world example of how to to build and use connected systems and integrations, see the Integration Tutorial.

Authentication

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.

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.

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.
Connected System The connected system to use. The connected system represents the external system or service and the authentication method that the integration will use to connect to that service.

Note: 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.
  • 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. 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.
Content Type The content type of the body that will be sent with the HTTP request.
  • JSON (application/json)
  • XML (application/xml)
  • Text (text/plain)
  • Custom: Define a custom content type using the provided field.
Content type applies only to requests with a 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.

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
Update security Yes No No No
Delete object Yes No No No
FEEDBACK