# Creating & Managing Connections The _Connection_ object allows you to create integrations locally, between Vaults, or with an external application. If you want to send Spark messages, you must also attach this connection to a queue.
## Accessing Connection Administration View and manage connections from **Admin > Connections**. You must have a security profile that grants the _Application: Manage Connections_ permission to access this tab. ## How to Create Connection Objects {#Create_Connections} To create a new connection: 1. From the **Connections** page, click **Create**. 2. Select a **Connection Type**. 3. Enter a **Name** for this connection. 4. Enter an **API Name** for this connection. Only lowercase, alphanumeric characters and underscores (\_) between characters are allowed. Remaining fields vary depending on the selected **Connection Type**: * [Vault to Vault][4] * [External][5] * [Local][6] * [LLM][7]
### Vault to Vault Connections {#vault-to-vault} The only required fields are **Name** and **API Name**. All remaining fields for this connection type are optional. 1. Enter a **Remote Vault ID**. This is the ID of the Vault you want to exchange messages with. If this field has a value, only this Vault ID can upload the connection file and there is no _Approval Workflow_. If this field is omitted, the _Approval Workflow_ begins when this connection is uploaded. 2. Enter a **Description** for this connection. 3. Select an **Authorized Connection User**. If the remote Vault needs to access information in this Vault, they will do so through this user. 4. Under **Remote Vault Details**, you can enter information about the remote Vault. Similar to the _Description_ field, these fields are for your personal reference only. After establishing a connection, these fields are automatically populated with relevant information. 5. Click **Save**. The connection record is now in a _Pending_ state. To make this connection active, you need to [establish the connection][1]. ### External Connections {#external} Options for external connections include: 1. Optional: Enter a **URL** for this external connection. This URL must be in a valid HTTPS format including `https://`. Only the standard HTTPS port is allowed, for example, `https://veeva.com:8443` is not allowed. If your Vault is configured with Vault Tokens or Custom Tokens, you can use them in the URL. 2. Recommended: Select an **Authorization** record for this external connection. If this connection needs to access data in the external application, Vault will do so through this [_Connection Authorization_](#Connection_Authorization_Types) record. The external system must be configured to accept this header. 3. Optional: Enter a **Description** for this connection. 4. Recommended: Add an **Authorized Connection User** for this connection. If the external application needs to access information in this Vault, they will do so through this user. If this user is not set, the external application cannot create session tokens (`SessionID`) for your Vault. If Client ID Filtering is on, this user must match the user in the inbound API request. 5. Click **Save**. The connection record is created in an _Active_ state and is available for use immediately. 6. Recommended: After creating your _Client Credential_ connection record, we recommend configuring a Client ID and using Client ID Filtering. ### Local Connections {#local} The only required fields are **Name** and **API Name**. The remaining fields for this connection type are optional. 1. Enter a **Description** for this connection. 2. Add an **Authorized Connection User** for this connection. If your Vault needs to access information requiring user credentials, it will do so through this user. If this user is not set, you cannot access information requiring user credentials such as API calls. 3. Click **Save**. ### LLM Connections {#llm} In addition to the required **Name** and **API Name**, options for LLM connections include **Provider**, **URL**, **Model Name**, and **Region**. Select an **Authorization** when the connection needs to access data in the external application via a [_Connection Authorization_][3] record. ### Connection Authorization Types {#Connection_Authorization_Types} [External][5] and [LLM][7] connections require you to choose the _Connection Authorization_ type corresponding to the type of authentication credentials that integration developers will pass in the message header for authentication on the external system. * **API Key** (`api_key__sys`): The _API Key_ (`api_key__sys`) of the external system. * **Basic Auth** (`basic_auth__sys`): The _User Name_ (`username__sys`) and _Password_ (`password__sys`) of the external system * **Client Credential** (`client_credentials__sys`): The _Client ID_ (`client_id__sys`) and _Client Secret_ (`client_secret__sys`) of the external system ## How to Establish a Vault to Vault Connection {#Establish_Vault_to_Vault} To establish a connection between two Vaults: 1. In the source Vault, navigate to **Admin > Connections** and locate the source Vault _Connection_ record. This may be a custom one you've [created][2], or a standard, Veeva-provided _Connection_ record, for example _QMS RIM Connection_ (`qms_rim_connection__v`). 2. From the **Actions** menu, select **Download Connection File**. 3. After reading the **Download Connection File** dialog, click **Download**. 4. In the target Vault, navigate to **Admin > Connections**. From the page's **Actions** menu, select **Upload Connection File**. 5. Click **Choose** and select the connection file you wish to upload. 6. Click **Continue**. When the connection file includes a *Remote Vault ID*, Vault establishes the connection and sets both *Connection* records' *Lifecycle State* to Active. When the connection file does not include a *Remove Vault ID*, Vault initiates an approval workflow which defaults to the Application Owner *User*. To complete the process in both the source and target Vaults, locate the approval workflow on the *Connection* record, reassign the workflow task to yourself, then complete the task. Vault transitions the *Connection* record to the *Approved* state. Once *Connection* records are *Approved* in both Vaults, Vault establishes the connection and sets the records to the *Active* state. ## Managing Existing Connections Depending on the _Connection Type_, there are various management options and related sections available for existing _Connection_ records. ### Details The _Details_ and _Remote Vault Details_ sections contain information about this connection. Most of these fields are editable. However, changing the **API Name** may break existing integrations with this connection. ### Workflow Timeline _Connection_ object records must go through an approval workflow before the connection can enter the _Approved_ lifecycle state. Once approved, this section holds read-only information about the approval, such as the time and user who completed the approval task. For _External_ and _Local_ connections, this section is blank as approval is not required. ### Integrations _Connection_ records can have multiple _Integrations_ associated with them. You can turn an integration on or off by setting the **Status** to _Active_ or _Inactive_, respectively. From this section, you can also create custom integrations. Learn more about integrations for Connections. ### Reference Lookups _Reference Lookups_ allow you to set the value of a field in the remote Vault indirectly from a VQL query to the source Vault, using a lookup. For example, you can indicate that the `country__v` value "U.S." in the source Vault is equivalent to "United States" in the remote Vault. Learn more about creating Reference Lookups for Connections. ### Connection Client The _Connection Client_ section allows you to create and update approved Client IDs for this connection. By default, each connection has a client ID in the format `veeva-vault-{connection api_name__sys}`, but you can update this value, inactivate it, or add new values. We recommend using client IDs with inbound _External Connections_ in conjunction with Client ID Filtering. ### Connection Stats {#stats} The _Connection Stats_ section displays daily performance metrics for this connection, including the number of Spark messages sent or received and the number of failures, retries, timeouts, and fatal errors. For some Vault to Vault Connections, this section also includes details about the records generated and updated by the connection. ## Managing Signing Certificates {#managing_signing_certificates} Vault uses signing certificates to sign all outbound Spark messages. All Vaults use the same signing certificate which is renewed periodically. Once the new certificate is released, Vault automatically updates all connections to use the new certificate and notifies customers ahead of time about the upcoming certificate rollover. The previous certificate is still available for a period of time known as the rollover period. During this time, you can switch between new and previous certificates if needed. Once the rollover period passes, the new certificate becomes the only active certificate on the connection. Vault immediately uses the selected signing certificate on the connection to sign all outbound Spark messages sent through the connection. To manage Spark messaging signing certificates: 1. [Create][2] or navigate to a _Connection_ record. 2. From the **Actions** menu, select **Manage Signing Certificate**. 3. From the _Manage Signing Certificate_ dialog, select the checkbox next to the applicable certificate. If the current certificate is the only one available, the certificate is read-only and you can either download the certificate or cancel the action. If two certificates are available, you are in the rollover period. Use the new certificate if possible. See Vault SSL Certificates for more information. 4. Optional: To download, click the download icon next to the applicable certificate. 5. Click **Save** to make the selected certificate active to use for Spark messaging. ## How to Delete a Connection To delete a connection, select **Delete** from the **Actions** menu. Note that you cannot delete a connection referenced by a [queue][1]. You also cannot delete standard, system-managed connections, but you can reconnect them to a different Vault. If you delete an established Vault to Vault connection, the _Connection_ record in the remote Vault moves to the _Disconnected_ state, and Vault deletes all associated _Connection Stats_. ## Standard Connections {#connections} Veeva provides various standard connections to support and automate business processes between separate Vaults. For example, organizations using both a Veeva QMS and a Veeva Safety Vault can use the Quality-Safety Connection for product quality complaint and adverse event intake. In many cases, a standard Veeva Connection provides a sufficient starting point for an organization's data transfer needs, enabling quicker configuration and use. See About Veeva Connections for an inventory of standard Veeva Connections and the processes they support. Learn more about standard connections at the Veeva Connections Resource Hub, or in a specific connection's Veeva Connect community. ### Standard Connection Limitations {#limitations} When you configure any of the standard connections, errors may occur in the following situations: * If a user deletes a record that either side of the connection was using, Vault ceases to update connected records with no notification. * If a user manually updates one of the ID fields on a record used by either side of the connection, Vault may fail to process Spark messages and update connected records. * If configuration change on either side of the connection may impact the integration, such as changes to fields or picklists, Vault may fail to process Spark messages and update connected records. ## Connections & Sandbox Vaults {#connection-sandboxes} When you create or refresh a sandbox Vault, all _Active_ external connections except those with tokens in the _URL_ are set to _Inactive_, and all _Active_ Vault to Vault connections are set to _Pending_. Local connections remain as _Active_. External connections with tokens in the _URL_ retain the _URL_ value and _Active_ or _Inactive_ state of the parent Vault in newly created or refreshed sandboxes. To make external connections active again, you must re-enter the connection URL. To make Vault to Vault connections active again, you must re-establish the connection as described below. ### Re-Establishing a Vault to Vault Connection {#reestablish} During sandbox creation or refresh, all _Active_ Vault to Vault connections are set to _Pending_. The corresponding connection in the remote Vault remains in an _Active_ state. To re-establish a Vault to Vault connection, you must re-download the connection file in the source Vault, re-upload the connection file in the target Vault, and approve the connection. To re-establish this connection: 1. Navigate to **Admin** > **Connections** in the source Vault. The source Vault is the Vault which initiates the connection request. 2. Find the _Vault to Vault_ connection you wish to re-establish. 3. If the connection record is in an _Active_ state, open the **Actions** menu and select **Reset Connection**. 4. After reading the **Reset Connection** dialog, select **Continue**. 5. Optional: If you know the ID of the target Vault, enter it in the **Remote Vault ID** field. The target Vault is the Vault your source Vault will connect to. If you leave this field blank, establishing the connection will require an approval workflow. 6. From the **Actions** menu, select **Download Connection File**. 7. After reading the **Download Connection File** dialog, click **Download**. 8. In the target Vault, navigate to **Admin > Connections**. The target Vault is the Vault which accepts the connection request. 9. Find the _Vault to Vault_ connection you wish to re-establish. 10. From the **Actions** menu, select **Connect from File**. 11. Click **Choose** and select the connection file downloaded from the source Vault. 12. Click **Continue**. 13. If the connection file included a _Remote Vault ID_, the connection is now re-established. Both connection records are now in an _Active_ state. 14. If the connection file does not include a _Remote Vault ID_, an _Approval Workflow_ will begin in both Vaults. In both the source and target Vault, navigate to the connection record details page and click **Complete**. In the dialog that appears, choose to **Approve** the connection. The connection record is now in the _Approved_ State. Once both Vaults approve the connection, both records move to the _Active_ state and the connection is re-established. ### Connection Approval Workflow When starting the _Approval_ workflow, custom connections assign the approval task to the user who created the _Connection_ record on both the source and remote Vault. Standard connections assign the approval task to the user who uploaded the signing certificate file. This behavior can occur when creating or refreshing a sandbox, as Vault sets the user creating the _Connection_ record to _System_. See the table below for details on both scenarios: |Connection Type|Approval Workflow Assignee: Source Vault|Approval Workflow Assignee: Remote Vault| |--- |--- |--- | |Standard Connection|_Connection Approval_ workflow task assigned to user who uploaded certificate file|_Connection Approval_ workflow task assigned to _Application Owner_ user| |Custom Connection|_Connection Approval_ workflow task assigned to user who created the _Connection_ record|_Connection Approval_ workflow task assigned to user who created the _Connection_ record|
## Related Admin Permissions Uploading a Vault to Vault connection file without a _Remote Vault ID_ starts an _Approval Workflow_, so this user must have the _Workflow: Start_ permission. [1]: #Establish_Vault_to_Vault [2]: #Create_Connections [3]: #Connection_Authorization_Types [4]: #vault-to-vault [5]: #external [6]: #local [7]: #llm