> For the complete documentation index, see [llms.txt](https://docs.sharelogic.com/unifi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sharelogic.com/unifi/configure/integrations.md).

# Integrations

The Integration is where most configuration and settings are stored.

## Definition

An Integration defines the connection between a **Process** and the **single system it’s connecting with**. It is a record that contains all of the properties and configurations for that **unique connection**.

Multiple Integrations can exist for one Process and each unique Integration will define the way in which the Process connects with that particular system. (Unifi defines an integration as **the connection of two systems to transfer or exchange data for one process**. This is represented by one integration record in Unifi.)

### Example

Incident Process - JIRA = *one* Integration

Incident Process - ATOS = *one* integration

Incident Process - SAP = *one* integration

**Incident Process total = *****three*** integrations

## Automated Creation of Trigger Business Rule <a href="#integration-fields" id="integration-fields"></a>

{% hint style="info" %}
Unifi will automatically create a Trigger (Business Rule) for the Process being integrated *(if one doesn't already exist)* when you run '**Build**' either on the Integration or Message once your Create Message is configured.
{% endhint %}

For step-by-step instructions on how to configure Integrations *(and other Integration components)* see the **Integration Guides** section of the documentation.

What follows is an explanation of the properties and configurations available on the Integration, grouped by section as they appear in Unifi Integration Designer.

## Integration <a href="#integration-fields" id="integration-fields"></a>

Here is where you will configure the high level Details and Message Identification method.&#x20;

### Details

Configure the high level, general details for the integration:

<details>

<summary>Details</summary>

<table><thead><tr><th width="220">Field</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>String. The name of the integration.</td></tr><tr><td>Description</td><td>String. A description of what this Integration is for and what it does.</td></tr><tr><td>Is template</td><td>Boolean. Mark this integration as a template that can be used to create new integrations.</td></tr><tr><td>Debug</td><td>Boolean. Turns on debugging for this integration. Currently breaks out detailed message trace logs into a separate activity log file.</td></tr><tr><td>State</td><td>String. The current state of the integration. It can be Active, Off, or Paused.</td></tr><tr><td>Status</td><td>String. The current status of the integration. It can be Up or Down.</td></tr><tr><td>Service type</td><td>String. The type of web service this integration is using <em>(SOAP/REST)</em>.</td></tr><tr><td>Message format</td><td>String. Automatically pre-process incoming messages for simpler message scripting.  The choice selected here will determine the object that's available to the 'Identify message script' <em>(choices: XML, JSON, Advanced)</em>.</td></tr><tr><td>Application</td><td>Reference. Application containing this record.</td></tr><tr><td>Process</td><td>Reference. The process this integration belongs to.</td></tr><tr><td>Company</td><td>Reference. The company this integration belongs to.  This is usually the name of the service provider being connected to, <em>as opposed to</em> the name of the manufacturer of the software.</td></tr></tbody></table>

</details>

### Message Identification

Messages are central to the functionality of Unifi. Upon receipt of an inbound request, Unifi will be able to identify the Message, know how to process it and subsequently what actions to perform based on the Message configurations.&#x20;

{% hint style="warning" %}
It is very important that **each Message within an integration be unique** *(more on that in the* [*Messages*](/unifi/configure/messages.md) *section)*.
{% endhint %}

The **Identify message script** field is used to extract the unique message identifier from the incoming payload and determine which Message is used to process the inbound request:

#### Identify message script (examples)

Unifi automatically looks for a header called `X-SND-EB-Message-Name` to use as the message name. **If the header is found then the Identify message script is not executed**.

Both the `payload` and `headers` are passed into the script. The following example will parse the XML payload and identify the message name from the first child element of the body node:

```javascript
function identify(xmlDoc) {
  var message_name = '';

  message_name = '' + x_snd_eb.utils.identifyFirstChild(
    xmlDoc,
    '/soapenv:Envelope/soapenv:Body'
  );

  return message_name.split(':').pop();
}
```

The following is an example which returns the message name from a JSON payload:

```javascript
function identify(payload) {
  return (payload.$message_name || '') + '';
}
```

## Settings <a href="#attachment-configuration-fields" id="attachment-configuration-fields"></a>

Here is where you will configure settings that relate to Attachments, Bond, Heartbeat and Feedback.&#x20;

### Attachments

Configure how attachments are handled for this integration. Unifi handles **streamed** or **embedded** attachments. We have a [How to Handle Attachments](/unifi/configure/how-to-guides/how-to-handle-attachments.md) guide which shows how to configure a dedicated Message in Unifi to handle streamed inbound attachments (**we strongly recommend streaming inbound**). You may also find it helpful to view our dedicated pages that provide specific information about [Extracting Attachments](/unifi/configure/attachments/extracting-attachments.md), [Fetching Attachments](/unifi/configure/attachments/fetching-attachments.md), [Sending Attachments](/unifi/configure/attachments/sending-attachments.md), [Sending Journal Embedded Attachments](/unifi/configure/attachments/sending-journal-embedded-attachments.md), [Sending Multipart Attachments](/unifi/configure/attachments/sending-multipart-attachments.md) and [Deleting Attachments](/unifi/configure/attachments/deleting-attachments.md).

See below for more details on the available Attachment settings fields:

<details>

<summary>Attachment settings</summary>

<table><thead><tr><th width="220">Field</th><th>Description</th></tr></thead><tbody><tr><td>Send existing attachments</td><td>Boolean. Set to true to send attachments which were added to the record before it was bonded.</td></tr><tr><td>Allowed content types</td><td>String. Comma separated list of attachment content types that are allowed to be sent to this integration. OOTB you can send any content type (i.e. this field is empty). You may wish to limit the content type by ‘whitelisting’ (explicitly specifying the file type that is allowed) (e.g. TXT, PNG).</td></tr><tr><td>Max attachments per bond</td><td>Integer. The maximum number of attachments allowed to be sent per bond.</td></tr><tr><td>Max attachments size per message</td><td>Decimal. The maximum size of all the attachments in a single message in MB.</td></tr><tr><td>Max attachments size per bond</td><td>Decimal. The maximum size of all the attachments in a single bond in MB.</td></tr></tbody></table>

{% hint style="info" %}
**Max attachments**

Setting any attachment value to -1 means there is no limit.
{% endhint %}

</details>

### Bond

The Bond does more than just store correlation data; it is a container for all transactions and attachments exchanged between integrated (bonded) records and stores a whole wealth of data useful for debugging the health and status of the integration. For more information see the [Bonds](/unifi/operate/bonding/bonds.md) page. This transactional data is kept for as long as the Bond it belongs to is open.&#x20;

The **Bond cleanup** field allows you to configure how long in days to keep that data after the Bond is closed. NOTE: Although the associated transaction and attachment records' data are deleted, Bond history will still be available. Setting the `Bond cleanup` value to 0 means the cleanup is never performed.

### Heartbeat

Heartbeat messages can be used to help identify if the integration is up or down.  You can configure settings specific to the integration heartbeat message, if it exists. More information on setting up a heartbeat message can be found in our [How to Setup Heartbeat Messages](/unifi/configure/how-to-guides/how-to-setup-heartbeat-messages.md) guide.

The **Heartbeat frequency** field is where you would set the amount of time to wait in seconds between trying an outbound heartbeat request.

### Feedback

Configure whether or how the user is to receive feedback about the Integration:

<details>

<summary>Feedback settings</summary>

<table><thead><tr><th width="220">Field</th><th>Description</th></tr></thead><tbody><tr><td>Enable UI messages</td><td>Boolean. Allow information and error messages to be shown to the user as UI Notifications. Only applies to certain notifications.</td></tr><tr><td>Note bond history</td><td>Boolean. Use the ‘Note bond history’ to process bond history updates.</td></tr><tr><td>Note attachment history</td><td>Boolean. Use the ‘Note attachment history’ to process attachment updates.</td></tr><tr><td>Add note script</td><td>Script plain. Script for adding integration updates to the target record. <strong>There is no need to call update() on the target</strong>.</td></tr></tbody></table>

{% hint style="info" %}
**Note bond history/Note attachment history**

When the Note bond history/Note attachment history checkbox is checked, the history will be promoted to the work notes fields of the record being integrated for the user to view.
{% endhint %}

</details>

## Error Handling <a href="#message-configuration-fields" id="message-configuration-fields"></a>

Here is where you will configure how you want the integration to handle errors.

### Error Messages

The Error Messages you want the integration to send when an inbound message cannot be processed:

<details>

<summary>Error messages</summary>

<table><thead><tr><th width="220">Field</th><th>Description</th></tr></thead><tbody><tr><td>Sync error message</td><td>Reference. The message to use when an inbound message cannot be processed synchronously.</td></tr><tr><td>Async error message</td><td>Reference. The message to use when an inbound message cannot be processed asynchronously.</td></tr></tbody></table>

{% hint style="info" %}
**Sync error message/Async error message**

In the case of a catastrophic failure (e.g. the inability to identify, access, or read an inbound request, or the inability to process the request asynchronously), this will be the message that is sent in response (which can be standard or customised to suit).
{% endhint %}

</details>

### Timeouts

Whether or not to process timed out receipts and the amount of time to wait for responses:

<details>

<summary>Timeouts</summary>

<table><thead><tr><th width="220">Field</th><th>Description</th></tr></thead><tbody><tr><td>Sync timeout</td><td>Integer. The amount of time in seconds to wait for a request to be accepted by the external system.</td></tr><tr><td>Async timeout</td><td>Integer. The amount of time in seconds to wait for an asynchronous receipt.</td></tr><tr><td>Process timed out transactions</td><td>Boolean. Process an inbound asynchronous receipt even if the transaction is timed out. This will allow the integration to run with less errors. Turn off to enforce strict processing of receipts within the specified timeout period.</td></tr><tr><td>MID server timeout</td><td>Integer. The amount of time in seconds to wait for the MID server to respond (only applies to connections using MID servers).</td></tr></tbody></table>

{% hint style="info" %}
**Sync/Async/Mid server timeout**

If there is no response/receipt within the time stipulated, then the request is errored. These errored requests can be rolled up to the record for them to deal with/escalate accordingly. Such insight allows the sender to remain informed of the condition of the request.
{% endhint %}

</details>

### Retry

Configure the Retry limits for the Integration:

<details>

<summary>Retry</summary>

<table><thead><tr><th width="220">Field</th><th>Description</th></tr></thead><tbody><tr><td>Retry delay</td><td>Integer. The amount of time in seconds to wait before retrying a failed outbound request.</td></tr><tr><td>Retry limit</td><td>Integer. The number of times sending an outbound request is attempted.</td></tr></tbody></table>

</details>

## Enabling and Disabling the Integration

{% hint style="info" %}
**Active**

This field is not selectable and is controlled by the *Connections*. **There can only be one active Connection at any time**. If there is an active Connection, the Integration will be active. If there is no active Connection, the Integration will be inactive.
{% endhint %}