Create an HTTP Integration

Introduction

In this page, you will learn how to create and configure an HTTP integration, as well as how to use the integration designer to test and troubleshoot problems.

• To learn about integration objects and their configuration options, see Integration Object.
• To learn about connected system objects and their configuration options, see Connected System Object.
• To learn how to call an integration from other places in your application, see Call an Integration.
• For a real-world example of how to build and use integrations, see the Integration Tutorial.
• To learn how to use different types of connected systems to connect to different systems, see Connected Systems.

Create the HTTP integration object

To create an integration in Appian:

1. Open the destination application for the new integration.

2. In the Build view, click New > Integration.

3. Select a creation method:

   • Use a connected system.
   • Create from scratch (HTTP only).
   • Duplicate existing integration.

4. Configure the following properties:

   

   Property	Description
   Connected System	Browse to and select a connected system. This property is only present if you selected Use a connected system.
   Integration to Duplicate	Browse to and select the existing integration you want to copy. This property is only present if you selected Duplicate existing integration.
   Name	Enter a name that follows the recommended naming standard.
   Description	(Optional) Enter a brief description of the integration.
   Save In	Browse to and select an existing folder to store the integration object, or click Create New Rule Folder to create and select a new folder for the object.

5. Click Create. Appian displays the new integration for editing.

Design guidance

As you continue to modify and define your integration, you may encounter guidance. Appian design guidance reinforces best practice design patterns that should be implemented in your objects. Guidance is calculated while editing expressions within the integration or when a precedent of the integration is updated.

When a recommendation or warning is triggered you'll see an indicator icon in the header (A) and next to the corresponding line in the expression editor (B).

Click on the icon in the header to learn more about the suggested guidance (C) and how it can be addressed.

If a recommendation is not applicable to your use case, you can Dismiss (D) that individual recommendation for that integration. Learn more about recommendation dismissal. Warnings cannot be dismissed and should always be addressed to avoid complications when the logic in the object is executed.

Integration design guidance is also visible outside of the object on the Health Dashboard.

See design guidance for the full list of possible guidance.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Configure the HTTP integration definition

The configuration pane of the integration designer allows you to define the HTTP request details for your integration.

For more information about the integration definition fields, see Integration Objects.

1. Select whether you want to use an existing connected system to share connection details across multiple integrations. If you created this integration directly from a connected system then this option will already be selected and the connected system will be pre-populated.
   

2. Fill out the Connection details. If you are using an existing connected system, select a Connected System using the picker. Otherwise, provide the Authentication details (if applicable) directly, as shown below.
   

3. Add Parameters and Headers.
   

4. If the selected Method supports it, define the Request Body and Content Type.
   

Content Type selection

The Content Type field must be configured for integrations where the Method is set to POST, PUT, PATCH, or DELETE. Although the Content Type field is configured in the Body section of the configuration pane, it's actually sent as an HTTP header. This field indicates the media type of the resource(s) defined in the request Body. The selection is based upon the web service that you're integrating with. See the Content Types section for more information.

Add automatic parsing

Once you've configured the integration definition, it's a good idea to configure response body parsing to automatically convert the JSON response body to an Appian value.

Instead of having to write a wrapper rule, automatic parsing will convert the results into an Appian value. This will allow you to use dot notation and index() in another expression simply by passing in an integration rule.

Enable HTTP request/response logging

Finally, you should decide whether to enable HTTP request/response logging for the integration.

Ensure that you are familiar with the integration logging guidelines before making this decision.

If you do choose to enable HTTP request/response logging, it will only write to the integration_req_resp_activity.log log if that functionality is also enabled in the Admin Console. The dynamic message below the checkbox will tell you whether HTTP request/response logging is enabled for your environment.

Test the integration

Once you've finished configuring the integration definition, you'll want to test the integration and view details about the request and response.

1. Click Test Request. The Result tab displays the Time taken for each phase of the integration and the resulting Value.
   

2. If an error occurs, the Result tab also displays the error details and recommended Next Steps.
   

3. The HTTP Request tab displays the raw request sent to the external system.
   

4. The HTTP Response tab displays the raw response received from the external system.
   

Add custom error handling

By default, an integration will return an error when it's unable to connect or when the external system responds with an HTTP error status code. Even when the HTTP call succeeds, you may still need to check for error messages or unexpected content before using the response in your application.

You can add custom error handling to an integration within the Error Handling section

1. Select Override and define all error conditions.
2. In the Success Criteria field, write an expression that returns true.
3. In the Error Message field use a!integrationError() to construct a custom error message.

Instead of returning an unwanted success status, the integration will return an error, allowing you to more easily handle future error handling.

Define inputs

After the integration is tested, you can define inputs that will allow you to reuse this object throughout your application.

1. Expand the inputs pane on the right hand side of the integration designer.

2. Click the + button in the top right-hand corner.

3. Configure the input Name, Description, Type, and whether or not it is an Array from the grid. You can also change the order of inputs using the up and down arrows.
   

4. If you have one or more inputs, you can enter values for each input in the test inputs pane. These values are used when testing the integration.
   

5. To save the current input values as a set of default test values, click the Set as default test values link below the grid. Once set, the default values will be saved with the integration.

Content types

When configuring an HTTP integration with a body, you must choose a value in the Content Type dropdown list. In all cases, this dropdown selection will set the "Content-Type" header on your request. The sections below provide more information on the individual content types and what they mean in the context of the integration.

JSON (application/json)

JavaScript Object Notation (JSON) is a lightweight data-interchange format that is commonly used for RESTful web services. It is structured as an array of objects where an object is a collection of name/value pairs. In many ways, JSON objects are similar to Appian dictionaries. When this value is selected, you can enter an Appian dictionary or CDT into the expression editor and Appian will automatically convert it to JSON. You should not use this content type when sending primitive types. You can also upload base64 documents inline with JSON.

Note that the charset will automatically be set to UTF-8. If you need to override this, add a custom HTTP header to the request with the name Content-Type and the value application/json.

The request body cannot exceed 5 MB. However, this does not include the up to 75 MB of base64 documents that can be streamed.

XML (application/xml)

eXtensible Markup Language (XML) is a data-interchange format that is commonly used for SOAP web services, though it is also compatible with REST. It is composed of nested units called elements that form data structures similar to Appian dictionaries and complex data types. When this value is selected, you can enter a CDT into the expression editor and Appian will automatically convert it to XML. You should not use this content type when sending primitive types. You can also upload base64 documents inline with XML.

Note that the charset will automatically be set to UTF-8. If you need to override this, add a custom HTTP header to the request with the name Content-Type and the value application/xml.

The request body cannot exceed 5 MB. However, this does not include the up to 75 MB of base64 documents that can be streamed.

Document (auto-detect)

The Document Content Type option allows you to send files to external systems. Choosing this option affects your request in three ways:

1. Appian sets the Content-Type header. The media type in parenthesis is "auto-detect" because Appian will automatically detect the correct media type based on the content of the chosen document and the document's extension.
2. Appian casts the body or part value to an Appian document whose content type will be detected. This step follows standard Appian casting rules.
3. Appian sends the content of the Appian document as the body or part of the request instead of the document ID. This allows you to upload files to external systems, such as Google Drive or Microsoft SharePoint®. The file contents are streamed from the file system to the external service, meaning the file is never fully read into memory. As a result, it is safe to send large files to external systems using this functionality.

Although there is no request body size limit imposed on this Content-Type, the best practice is not to exceed 250 MB for a single document.

Multipart Form Data (multipart/form-data)

Some services require data to be sent as multipart/form-data. This is typical for services that upload documents. Multipart HTTP requests can send multiple types of data in a single request, such as structured text and unstructured binary data. For example, sending JSON or XML data (structured text) along with files (unstructured binary data). In Appian, choosing the Multipart Form Data (multipart/form-data) for the Content Type allows you to configure this type of request. For more information on multipart requests in general, see the RFC.

The request body cannot exceed 5 MB. However, this doesn't include the documents that can be streamed.

Sending documents

Documents can be sent as form part values. See the above section for more details on sending documents.

Document parts are sent differently than non-document parts. Unlike non-document parts, document parts are never fully stored in memory, making it safe to send large files through a multipart request. Best practice is to not send more than 75 MB of documents in a single request.

Configuring form parts

If you have a static number of form parts that don't require additional logic, select Specify data for each part and use the form to specify the fields.

You can also use an expression to define the form parts by selecting Define all parts with a single expression. This can be helpful if you need conditional logic, such as sending optional files. See a!httpFormPart() for more information on setting up the expression.

Text (text/plain)

Choosing this option sets the Content-Type header text/plain, which is the generic media type for plain text. This content type is rarely used by APIs.

Note that the charset will automatically be set to UTF-8. If you need to override this, add a custom HTTP header to the request with the name Content-Type and the value text/plain.

The request body cannot exceed 5 MB.

Custom

Selecting the Custom option allows you to set content-type manually. This should be used when you cannot leverage any of the provided content-type options. Note that only text-based media types can be sent through integrations in this way, and the charset will automatically be set to UTF-8.

If you need to override the charset, add a custom HTTP header to the request with the name Content-Type and set the value to match the custom Content Type that you entered.

The request body cannot exceed 5 MB.

Feedback