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.

Note: This feature is highly complex. We strongly recommend working with your Customer Success Manager or Veeva Services to configure this feature.

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 Vault QMS sends a Spark message to Vault Registrations. This message starts a set of regulatory activities in Vault Registrations, which can also call back to Vault 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.

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 coding SDK integrations in the Developer Portal.

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. 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:

From Admin > Connections, select the connection where you’d like to create an Integration record.
Click Integrations to expand the section, then click Create.
Enter a Name for this integration. This will appear in the Admin UI.
Enter an Integration API Name. This is how developers will reference this integration through the Java SDK or API. Only lowercase, alphanumeric characters, and underscores (_) are allowed, though the name cannot start or end with an underscore.
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.
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.
Click Save.

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

How to Create an Integration Point

To create an integration point for an integration:

From Admin > Connections, select the connection which contains the integration where you’d like to create an integration point.
Click Integrations to expand the section, then select the integration where you’d like to create an integration point.
Expand the section for either Integration Points – Outbound or Integration Points – Inbound.
Enter a Name for this integration point. This will appear in the Admin UI.
Enter an Integration API Name. This is how developers will reference this integration point through the Java SDK or API. Only lowercase, alphanumeric characters, and underscores (_) are allowed, though the name cannot start or end with an underscore.
Enter a Description for this integration point. This should explain the business process or integration goals associated with this point in the integration.
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.
Click Save.

About User Exception Messages

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.

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.