# Creating & Managing Vault to Vault Integrations

With the Vault Java SDK, you can build custom Vault to Vault integrations to automate business processes across different Vaults. In the Vault UI, you can set up an _Integration_ object record to display the business goals of an integration to Business Admins, and allow them to easily manage the integration. For example, this allows Business Admins to turn an integration on or off.

This page contains information unique to integrations between two Vaults. The _Integration_ object is not supported for _Local_ or _External_ connection types.

<div class="note-border alert-info">
  <div class="alert alert-info" role="alert">
    <div><i class="far fa-info-circle"></i></div>
    <div class="alert-text">
      <p><strong>Note</strong>: This feature is highly complex. We strongly recommend working with your Veeva Representative or Veeva Services to configure this feature.</p>
    </div>
  </div>
</div>



## Accessing Integration Management

View and manage integrations from **Admin** > **Connections**. Once here, you can view _Integrations_ for each _Connection_ record with a _Vault to Vault Connection Type._ You must have a security profile that grants the _Application: Manage Connections_ permission to access connections in this tab.

To access integration-related items other than connections, such as user exception messages, integration rules, and to view Spark message processors currently deployed to your Vault, you need the _Application: Manage Integrations_ permission.

## SDK Integrations Overview

An integration between two Vaults can automate a previously manual business process. For example, a new _Change Event_ record in QMS sends a Spark message to Registrations. This message starts a set of regulatory activities in Registrations, which can also call back to QMS for any necessary information about the change event.

Before you can create an integration between two Vaults, you must set up a _Connection_ record between them. This record contains the agreement which allows two Vaults to communicate. Learn more about [setting up connections.](/en/lr/53358/)

After creating the connection between two Vaults, you can set up _Integration_ and _Integration Point_ records on the connection. These objects and the features they provide are the focus of this article.

With the Vault Java SDK, a developer builds the business logic for the integration between two Vaults. This integration code will reference the _Connection_, _Integration_, and _Integration Point_ objects. Learn more about <a class="external-link " href="https://developer.veevavault.com/sdk/#vault_Integrations" target="_blank" rel="noopener">coding SDK integrations in the Developer Portal<i class="fa fa-external-link" aria-hidden="true"></i></a>.

## About Integrations and Integration Points

At its core, the _Integration_ (`integration__sys`) object is a self-contained, independent grouping of _Integration Points_ (`integration_point__sys`) records. Integration points represent a single goal, or "point" in an integration flow. An integration can have many integration points, but a single integration point can only belong to one integration.

While _Integrations_ and _Integration Points_ are not mandatory for integrations, utilizing them has many benefits. For example, an Admin can view the integration points associated with an integration to understand its goal and flow without examining their Vault's configuration or SDK code. For example, the process to create a new change control record.

_Integration Points_ also allow you to utilize [User Exception Messages][3]. These custom exceptions are coded by a Vault Java SDK developer, and allow Vault Admins to troubleshoot common integration errors. For example, if your integration fails to create a new change control record due to a missed required field, you can display this information to a Business Admin to correct the error.

## How to Create an Integration Object

To create an integration record for a connection:

  1. From **Admin > Connections**, select the connection where you'd like to create an _Integration_ record.
  2. Click **Integrations** to expand the section, then click **Create**.
  3. Enter a **Name** for this integration. This will appear in the Admin UI.
  4. Enter an **Integration API Name**. This is how developers will reference this integration through the Java SDK or Vault API. Only lowercase, alphanumeric characters, and underscores (\_) are allowed, though the name cannot start or end with an underscore.
  5. Set a **Status** for the integration, either _Active_ or _Inactive_. While building a custom integration, developers should leverage this status to perform business logic. For example, adding logic for this status to control turning an integration on or off. By default, this setting has no effect.
  6. Optional: If you want the integration details to contain a link to the remote Vault's _Integration_ record, enter a **Remote Vault Integration Name**. This is the label for the link. Next, enter the **Remote Vault Integration Id.** This is the ID value of the remote Vault's _Integration_ record.
  7. Click **Save**.

After creating an integration record, you may wish to create [integration points][4].

## How to Create an Integration Point {#Integration_Point}

To create an integration point for an integration:

  1. From **Admin > Connections**, select the connection which contains the integration where you'd like to create an integration point.
  2. Click **Integrations** to expand the section, then select the integration where you'd like to create an integration point.
  3. Expand the section for either **Integration Points – Outbound** or **Integration Points – Inbound**.
  4. Enter a **Name** for this integration point. This will appear in the Admin UI.
  5. Enter an **Integration API Name**. This is how developers will reference this integration point through the Java SDK or Vault API. Only lowercase, alphanumeric characters, and underscores (\_) are allowed, though the name cannot start or end with an underscore.
  6. Enter a **Description** for this integration point. This should explain the business process or integration goals associated with this point in the integration.
  7. Set a **Status** for the integration, either _Active_ or _Inactive_. While building a custom integration, developers should leverage this status to perform business logic. By default, this setting has no effect.
  8. Click **Save**.

## About User Exception Messages {#User_Exception}

From **Admin > Connections > User Exception Messages**, you can view the user exception messages generated by your integrations.

Vault includes the _User Exception Message_ object and its child object, _User Exception Item_, to help Business Admins track and resolve any errors that occur with your integrations. Your Vault Java SDK developers can leverage these objects inside Spark message processors to create these custom exception messages.

For example, if either end of your integration fails to process an incoming message, your custom SDK logic creates a _User Exception Message_ record to capture the failure and display information to a Business Admin. This record can contain information for how to troubleshoot, what action is necessary, who to contact if the failure persists, and so on.

If you want specific users or groups to receive notifications whenever there is a new _User Exception Message_, you must create a custom lifecycle for the _User Exception Message_ object and configure a notification entry action.

Vault runs the _Cleanup User Exceptions_ job daily to delete any inactive _User Exception Item_ and _User Exception Message_ records. Vault Owners receive a notification if this job fails. By default, Vault also deletes _User Exception Item_ and _User Exception Message_ records that are older than 180 days.

User exception messages are tied to individual _Integration Points_. Because of this, you cannot leverage user exception messages without setting up integrations and integration points.

## About Integration Rules

Integration Rules allow developers to incorporate configurable rules for mapping object and document fields between two Vaults into a _Spark_ _Message Processor_. Learn more about [creating and managing integration rules](/en/lr/62154/).

## Spark Message Processors

**Admin > Connections > Spark Message Processors**, you can view all of the Spark message processors currently deployed to your Vault.

Spark message processors provide logic to handle Spark messages. For example, all inbound queues must include a Spark message processor to provide the operations to perform on the received messages.

  * **Name**: The name of the Spark message processor.
  * **Source**: The source of this Spark message processor. _Custom_ means this was developed with the Vault Java SDK.
  * **Operational Status**: The status of this Spark message processor, either _Active_ or _Inactive_. While you can still assign an _Inactive_ processor to an inbound queue, only _Active_ processors can process messages.

## Spark Message Delivery Event Handlers

**Admin > Connections > Spark Message Delivery Event Handlers**, you can view all of the Spark message delivery event handlers currently deployed to your Vault.

These provide a mechanism for Admins and Spark-integration developers to handle undelivered Spark messages. Once configured for an outbound queue, Vault executes the handler logic. For example, if the target Vault is unavailable, the handler may put the message back on the queue in 24 hours, notify a specific user, or take other actions.

Name
: The name of the handler.

Source
: The source of the handler. _Custom_ means the handler was developed with the Vault Java SDK.

Operational Status
: The status of the handler, either _Active_ or _Inactive_.

 [3]: #User_Exception
 [4]: #Integration_Point