# Configuring the Safety-Clinical Operations Connection

Using the <a href="/en/lr/526178/">Safety-Clinical Operations Connection</a>, organizations with both a Clinical Operations Vault and a Safety Vault can exchange data in near-real time. To use the Safety-Clinical Operations Connection, you must configure the relevant components, connect any existing data, and activate the connection. This setup requires configuration steps in both Vaults.

## Configuration Overview

You must complete the following steps in both your Safety Vault and Clinical Operations Vault to configure the standard connection:

1. <a href="/en/lr/53358/">Establish the Vault to Vault connection</a>. 
2. Review the [connection components][6] and adjust as needed to fit your organization's business processes.
3. [Migrate Clinical Operations _Study_ data][1] from custom fields to standard fields and inactivate the custom fields.
4. [Update object layouts][2].
5. [Configure reference lookups][3] for controlled fields within the integration scope and load these to each Vault.
6. [Update any required fields][4] that are not defined in the connection to either have a default value or to make values not required.
7. [Update object lifecycles][5] to assign initial objects' states.
8. [Link existing _Studies_][7] in your Safety and Clinical Operations Vaults.
9. Optional: Configure both Vaults to [transfer Safety Letters][8] from your Safety Vault to your Clinical Operations Vault. 
10. We recommend creating a <a href="/en/lr/51842/">flash report</a> to run when there are active _User Exception Message_ records in your Safety Vault.
11. Establish the Vault to Vault connection between your Safety Vault and your Clinical Operations Vault. See <a href="/en/lr/53358/">Creating & Managing Connections</a> for detailed instructions.

## Safety-Clinical Operations Connection Components

The components in the following sections support the standard Safety-Clinical Operations Connection.

### Connections

The following _Connections_ are available from **Admin > Connections**:

* _Safety to Clinical Connection_ (`safety_to_clinical_connection__v`) in your Safety Vault
* _Safety to Clinical Connection_ (`safety_to_clinical_connection__v`) in your Clinical Operations Vault

In your Safety Vault, you can update the _Connections_ <a href="/en/lr/26387/">object layout</a> to include the following fields in the <a href="/en/lr/53358/#stats">_Connection Stats_ section</a>:

* _ClinOps: Safety Letters sent to eTMF_
* _ClinOps: Studies Created_
* _ClinOps: Studies Registrations Created_
* _ClinOps: Safety Letters Sent to Site_

### Integration & Integration Points

The _Integration_ and _Integration Point_ objects enable Vault to manage the message queues and define what documents and data the connection maps from one (1) Vault to another. These records are read-only and are used by Vault to manage the connection and track any connection errors.

#### Safety Vaults

The Safety-Clinical Operations Connection includes the following default _Integrations_ with standard _Integration Points_ in your Safety Vault:

<table>
  <thead>
    <tr>
      <th>Integration</th>
      <th>Integration Point</th>
      <th>Sent From</th>
      <th>Sent To</th>
      <th>Included Data</th>
    </tr>
  </thead>
  <tr>
    <td>
        Clinical Study Integration
    </td>
    <td>
        Study Integration Point
    </td>
    <td>
        Clinical Operations
    </td>
    <td>
        Safety
    </td>
    <td>
        Study (including the associated <em>Organization</em>)
    </td>
  </tr>
 <tr>
    <td>
        Safety Distributions Integration
    </td>
    <td>
        Safety Distribution Outbound Integration Point
    </td>
    <td>
        Safety
    </td>
    <td>
        Clinical Operations
    </td>
    <td>
        Distribution (with CrossLinks)
    </td>
  </tr>
<tr>
    <td>
        Safety Distributions Integration
    </td>
    <td>
        Safety Distribution Created Inbound Integration Point
    </td>
    <td>
        Clinical Operations
    </td>
    <td>
        Safety
    </td>
    <td>
        Distribution
    </td>
  </tr>
<tr>
    <td>
        Safety Distributions Integration
    </td>
    <td>
        Safety Distribution Distributed Inbound Integration Point
    </td>
    <td>
        Clinical Operations
    </td>
    <td>
        Safety
    </td>
    <td>
        Distribution
    </td>
  </tr>
</table>

#### Clinical Operations Vaults

The Safety-Clinical Operations Connection includes the following default _Integrations_ with standard _Integration Points_ in your Clinical Operations Vault:

<table>
  <thead>
    <tr>
      <th>Integration</th>
      <th>Integration Point</th>
      <th>Sent From</th>
      <th>Sent To</th>
      <th>Included Data</th>
    </tr>
  </thead>
  <tr>
    <td>
        Clinical Study Integration
    </td>
    <td>
        Study Integration Point
    </td>
    <td>
        Clinical Operations
    </td>
    <td>
        Safety
    </td>
    <td>
        Study
    </td>
  </tr>
  <tr>
    <td>
        Clinical Study Integration
    </td>
    <td>
        Study Country Integration Point
    </td>
    <td>
        Clinical Operations
    </td>
    <td>
        Safety
    </td>
    <td>
        Study Country
    </td>
  </tr>
<tr>
    <td>
        Safety Letter Integration
    </td>
    <td>
        Vault Safety Inbound Document Creation
    </td>
    <td>
        Safety
    </td>
    <td>
        Clinical Operations
    </td>
    <td>
        Safety Distribution (with CrossLinks)
    </td>
  </tr>
<tr>
    <td>
        Safety Distribution Integration
    </td>
    <td>
        Safety Distribution Created
    </td>
    <td>
        Clinical Operations
    </td>
    <td>
        Safety
    </td>
    <td>
        Safety Distribution
    </td>
  </tr>
</table>

### Integration Rules {#integration-rules}

To support the Safety-Clinical Operations Connection, it may be necessary to transform data from the source Vault's data model to fit within the target Vault's data model. You can use <a href="/en/lr/62154/">Integration Rules</a> to incorporate configurable rules for mapping object and document fields between two (2) Vaults.

#### CRO Support {#cro-support}

By default, the Safety-Clinical Operations Vault Connection associates a single _Organization_ with each _Study_ generated in your Safety Vault. To support multiple sponsor _Organizations_ for a _Study_, we recommend activating the `safety_study_cro_organization__v` field rule for the _Study Integration Rule_ instead of using a custom integration rule. If you do this, you must also inactivate the `safety_study_organization__v` field rule.

### Queues

The Safety-Clinical Operations Vault Connection includes the following <a href="/en/lr/53147/">message processing queues</a>:

* Safety Vault:
  * _Safety to Clinical Inbound Queue_ (`safety_clinical_inbound_queue__v`)
  * _Safety to Clinical Inbound Queue Distribution_ (`safety_clin_inbound_dist_queue__v`)
* Clinical Operations Vault:
  * _Safety to Clinical Outbound Queue_ (`safety_clinical_outbound_queue__v`)
  * _Safety to Clinical Outbound Queue Distribution_ (`safety_clin_outbound_dist_queue__v`)

You can access and manage these queues from **Admin > Connections > Spark Queues**.

### User Exception Objects

Vault includes the _User Exception Message_ object and its child object, _User Exception Item_, to help you track and resolve any errors that occur with your Safety-Clinical Operations Vault Connection. If either Vault is unable to process incoming data, Vault creates a _User Exception Message_ to capture the failure and individual _User Exception Items_ for each item that failed on the related _Integration Point_ in the outbound Vault. The connection retries failed items from previous connection runs during the next run. Vault reprocesses integration points when the _User Exception Item_ has a _Last Run Time_ more recent than the _Last Successful Run Time_.

You can view and manage these messages from **Admin > Connections > User Exception Messages**. If you want specific users or groups to receive notifications when Vault creates _User Exception Messages_, you must create a custom lifecycle for the _User Exception Message_ object and configure a <a href="/en/lr/59885/">notification entry action</a>.

#### Resolving User Exception Messages

A _User Exception Message_ means that you need to update your configuration. After you update the configuration, Vault attempts to resolve any errors the next time the connection runs. You can also select the **Reprocess Request** action on a _User Exception_ to run the connection and resolve errors.

### Last Run Time (LRT) Field

On every inbound _Integration_, the _Last Run Time_ field captures the date and time that the integration last ran. Vault uses this date with the _Last Successful Run Time_ field to determine which integration points to retry during the next connection run.

### Last Successful Run Time (LSRT) Field

On every inbound _Integration_, the _Last Successful Run Time_ field captures the date and time that the integration last ran with no errors. Vault uses this date to query changes since the integration's last successful run.

You can use the _Last Successful Run Time_ field in the following ways:

* If you don't want Vault to transfer existing object records, populate this field with the date and time you plan to activate the connection.
* If you need to rerun every _Integration Point_ within the _Integration_, you can clear the _Last Successful Run Time_ field. The next time an action in either Vault triggers the connection, Vault re-processes all documents or object records within the scope of that integration point.

When activating a Safety-Clinical Operations Connection, populate the _Last Successful Run Time_ field on each active _Integration_ to the date and time you want transfers to start. If you do not populate this field, Vault will transfer all relevant records and documents.

## Clinical Operations Data Migration {#clinical_operations_data_migration}

In order to use the Safety-Clinical Operations Connection, you must ensure that the _Studies_ in your Clinical Operations Vault include the _Masking_, _Study Name_, and _Study Start Date_ standard (`__v`) fields rather than custom (`__c`) fields. You must [migrate][11] the data for any _Studies_ using the custom fields and then [inactivate][12] the custom fields. 

You should only need to perform the data migration and field inactivation procedures once when you first set up the Safety-Clinical Operations Connection.

### Migrating Data {#migrate}

We recommend using Vault Loader to migrate data in your Clinical Operations Vault:

1. Use Vault Loader to <a href="/en/lr/31536/#how-to-extract">extract the _Study_ object metadata</a>.
2. Open the resulting CSV file in an editor.
3. Locate the three (3) custom fields in the file (`masking__c`, `study_name__c`, and `study_start_date__c`).
4. Copy the data from these columns into the columns for the standard fields (`masking__v`, `study_name__v`, and `study_start_date__v`).
5. Save the CSV file.
6. Use Vault Loader to <a href="/en/lr/76401/#loading-object-records">update the _Studies_</a>. 
  * Ensure that you select **Study Number** (`name__v`) from the **Key Field** drop-down.

<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>:  When copying the data from the custom fields into the standard fields, ensure the date is in the following format: <code class="language-plaintext highlighter-rouge">YYY-MM-DD</code>. Some editors may change the date format.</p>
    </div>
  </div>
</div>



### Inactivating Fields {#inactivate}

Once you have migrated the data to the standard fields, you must inactivate the custom fields:

1. Navigate to **Admin > Configuration > Objects > Study > Fields**.
2. Click the custom field you want to mark as _Inactive_.
3. Click **Edit**.
4. From the **Status** drop-down, select **Inactive**.
5. Repeat these steps for each of the following fields:
  * `masking__c`
  * `study_name__c`
  * `study_start_date__c`

## Updating Object Layouts

In order for the Safety-Clinical Operations Connection to work properly, you must add the following fields to the following <a href="/en/lr/26387/">object layouts</a>.

In your Safety Vault:
* Add the _ClinOps State_ and _Protocol Title_ fields to the _Study_ object layout
* Add the _ClinOps State_ field to the _Study Registration_ object layout

In your Clinical Operations Vault:
* Remove the [inactive][12] _Masking_, _Study Name_, and _Study Start Date_ custom (`__c`) fields from the _Study_ object layout
* Add the standard _Masking_, _Study Name_, and _Study Start Date_ (`__v`) fields to the _Study_ object layout

##  Configuring Reference Lookups {#configuring_reference_lookups}

Reference lookups are a configuration component referenced by <a href="/en/lr/62154/">integration rules</a> that allow you to map the value of a field on a target object indirectly from a value in the source Vault. As a part of the connection offering, the `country__v` and `masking__v` reference lookups are already configured. It is critical for the implementation to review these mappings to ensure that they are correct. You can view the reference lookups by navigating to **Admin > Connections > Safety to Clinical Connection > Reference Lookups** in your Safety Vault.

You must add reference lookups for controlled fields within the integration scope. We recommend creating CSV mapping files and using <a href="/en/lr/76401/">Vault Loader</a> to upload these to your Vault to create reference lookups. For example, in order for Vault to transfer studies from one (1) Vault to the other, you must create _Study Type_ reference lookups to map the source study types to the target study types. See <a href="/en/lr/58198/">Creating & Managing SDK Reference Lookups</a> for detailed instructions.

You must create reference lookups in your Safety Vault for the following:

* _Study Type_
* _Development Phase_

To support [Safety Letters][8], you must also create reference lookups in your Clinical Operations Vault to map document 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>: In Safety Vaults, the United Kingdom is represented by two (2) separate values: United Kingdom (Great Britain) and United Kingdom (Northern Ireland). In Clinical Operations Vaults, there is only one (1) value: United Kingdom. Because of this, the United Kingdom (Northern Ireland) value is not mapped directly. You can change this if required.</p>
    </div>
  </div>
</div>



### Study Type Support {#study-type}

To receive _Study Type_ values from the Safety-Clinical Operations Vault Connection:
1. Ensure you've added a reference lookup for the following picklist fields and ensure they are active in each Vault:
  * **Clinical Operations Vault**: _Study Design Type_ field on the _Study_ object
  * **Safety Vault**: _Study Type_ field on the _Study_ object
2. Activate the `safety_clinical_study_design_type__v` field rule for the [_Study Integration Rule_][9].
3. Inactivate the `safety_clinical_study_type__v` and `safety_study_type__v` field rules.

### Loading Mappings

Once you have created CSV mapping files for _Studies_, you can use <a href="/en/lr/76401/">Vault Loader</a> to load reference lookups to your Vault. Once you load the reference lookups, confirm that they loaded successfully. Then, navigate to **Admin > Connections** in your Safety and Clinical Operations Vaults and review the reference lookups to ensure they appear as expected.

##  Updating Fields & Rules {#updating_fields_and_rules}

In order for the connection to run successfully, you need to update any required object fields that are not defined in the connection to either have a default value or to make values not required. For example, in your Safety Vault, review and make any update necessary for the default value for the following fields:

* _Organization_ (`safety_study_organization__v`)
* _Masking_ (`safety_study_masking__v`)
* _Study Phase_ (`safety_study_phase__v`)
* _Study Type_ (`safety_study_type__v`)

### Required Fields

The _Study Name_ field is not required in Clinical Operations Vaults, but is required in Safety Vaults. If the connection attempts to send a record from the Clinical Operations Vault to the Safety Vault without this required field, Vault generates a _User Exception Message_ and the transfer fails. To avoid this, we recommend <a href="/en/lr/46866/#how-to-create-validation-rules">creating a Validation Rule</a> that tells Vault to require the _Study Name_ field in the Clinical Operations Vault.

### Validation Rules

Safety Vaults have a custom validation rule for configuring the _Blinded_ value if the _Masking_ value is _Double-Blind_. Because the _Blinded_ field does not exist in Clinical Operations Vaults, the Safety-Clinical Operations Vault Connection does not populate this field. Before running the connection, ensure this validation rule is inactive in your Safety Vault. Once the _Study_ transfers through the connection, you can then populate the _Blinded_ field in your Safety Vault.

### User Exception Message Configuration

In your Safety Vault, configure the _User Exception Message_ object as follows:

* Navigate to **Admin > Configuration > Object > User Exception Message > Actions > Reprocess Request**.
  * Ensure the **Status** is **Active**.
* Update the _User Exception Message_ <a href="/en/lr/26387/">object layout</a> to include a related object section for _User Exception Items_. 
  * For _Creation Option_, select **Prevent record creation**.

##  Object Lifecycles {#lifecycles}

In your Safety Vault, update <a href="/en/lr/30683/#how-to-define-states">object lifecycles</a> as follows:

* Update the _Study_ object lifecycle to set _New_ as the initial state
* Update the _Study Registration_ object lifecycle to set _New_ as the initial state

## Linking Existing Studies

When you start the Safety-Clinical Operations Connection, you will likely have studies populated in both Vaults. Vault does not automatically match an existing Clinical Operations _Study_ to an existing Safety Vault _Study_. You can, however, link the two (2) _Studies_ manually. If you do not link existing _Studies_, the connection may cause errors or create duplicate _Studies_.

To manually link existing _Studies_:

1. In your Clinical Operations Vault, identify the _Global ID_ and _Study Number_ of the _Study_ you want to link.
2. In your Safety Vault, open the _Study_ you want to link.
    * In the **Link** field, enter the **Global ID** from your Clinical Operations Vault.
3. Repeat these steps to link all applicable _Studies_.

## Configuring Safety Letters

You can configure your Vaults to transfer Safety Letters from your Safety Vault to your Clinical Operations Vault. This includes <a href="/en/lr/23143/">CrossLink</a> documents, such as CIOMS and FDA 3500 forms, and optional cover letters. In Clinical Operations Vaults with Veeva Site Connect, users can distribute these directly to clinical research sites. 

To configure your Vaults to distribute Safety Letters:

* In your Safety Vault:
  * <a href="/en/lr/23139/#enable-crosslinks">Enable and configure CrossLinks</a>.
  * Review <a href="/en/lr/62154/#about-field-rules">field rules</a> for the applicable [integration rules][9] and if applicable, <a href="/en/lr/62154/#how-to-create-field-rules">create new rules</a> to support your business processes.
  * Configure the _Send to Vault Clinical_ user action. Users can only execute this action on _Distribution_ types of _Transmissions_ and the action fails if it runs it on a _Distribution_ related to a _Study_ you have not [linked][7] to a _Study_ in your Clinical Operations Vault.
      1. <a href="/en/lr/43127/#assign-actions">Assign</a> the action to the _Transmission_ object.
      2. Add the action to the appropriate lifecycle states in either of the following ways:
          * When assigning the action, select the **Available in All Lifecycle State** checkbox to apply <a href="/en/lr/47850/#configuring-atomic-security-on-user--system-actions">atomic action security</a> defaults. 
          * Add the action as a <a href="/en/lr/59885/">user action</a> to the applicable states of the _Transmission Lifecycle_.
  * Create a <a class="external-link " href="https://safety.veevavault.help/en/lr/01252" target="_blank" rel="noopener">_Safety Rule Set_<i class="fa fa-external-link" aria-hidden="true"></i></a> for the _Vault Clinical_ <a class="external-link " href="https://safety.veevavault.help/en/lr/01202" target="_blank" rel="noopener">_Transmission Profile_<i class="fa fa-external-link" aria-hidden="true"></i></a>.
* In your Clinical Operations Vault:
  *  <a href="/en/lr/23139/">Enable and configure CrossLinks</a>.
  * Create a [reference lookup][3] to map the document types between your Vaults.
  * [Map Vault Clinical Docs artifacts][10] so that Vault knows how to classify target CrossLinks.
  * Optional: To distribute Safety Letters directly to clinical research sites using SiteVault, configure <a class="external-link " href="https://clinical.veevavault.help/en/lr/64233" target="_blank" rel="noopener">Veeva Site Connect<i class="fa fa-external-link" aria-hidden="true"></i></a> and <a class="external-link " href="https://clinical.veevavault.help/en/lr/65185" target="_blank" rel="noopener">Safety Distributions<i class="fa fa-external-link" aria-hidden="true"></i></a>.

### Mapping Vault Clinical Docs Artifacts {#mapping}

You must map document types and classifications in your Safety Vault to the applicable document types in your Clinical Operations Vault so that Vault classifies transferred Safety Letters correctly in your Clinical Operations Vault. To do this, assign the _Expedited Safety Report_ and _Safety Report Supporting Documents_ <a class="external-link " href="https://clinical.veevavault.help/en/lr/30260" target="_blank" rel="noopener">artifacts<i class="fa fa-external-link" aria-hidden="true"></i></a> to the appropriate document types, subtypes, or classifications in your Clinical Operations Vault. 

<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>: Do not associate either artifact with more than one (1) classification in your Clinical Operations Vault.</p>
    </div>
  </div>
</div>



<table>
  <thead>
    <tr>
      <th>Safety Letter</th>
      <th>Safety Document Type & Subtype</th>
      <th>Safety Document Classification</th>
      <th>Vault Clinical Docs Artifact</th>
    </tr>
  </thead>
  <tr>
    <td>
        Safety Document
    </td>
    <td>
        Case > Individual Case Safety Reports (ICSR)
    </td>
    <td>
      <ul>
          <li>E2B Plus</li>
          <li>CIOMS I</li>
          <li>E2B(R2)</li>
          <li>E2B(R3)</li>
          <li>EMA E2B (R3)</li>
          <li>FDA 3500A</li>
          <li>FDA E2B(R2)</li>
          <li>FDA VAERS E2B (R3)</li>
          <li>PMDA E2B (R2)</li>
          <li>HC E2B (E2)</li>
      </ul>
    </td>
    <td>
        Expedited Safety Report
    </td>
  </tr>
  <tr>
    <td>
        Cover Letter
    </td>
    <td>
        Case > Individual Case Safety Reports (ICSR)
    </td>
    <td>
        SUSAR Cover Letter 
    </td>
    <td>
        Safety Report Supporting Documents
    </td>
  </tr>
</table>

### Populating Products on Documents {#populating-products}

You can configure your Vaults so CrossLink documents transferred to your Clinical Operations Vault have accurate _Product_ values. If you do not configure your Vaults to populate the _Product_ field, CrossLinks reference all _Studies_ related to the _Distribution_, which Vault populates based on the _Products_ specified in the related _Case_. When configured, Vault populates the following CrossLink document fields:

* **Product**: Based on the document's associated _Case_ by identifying the <a class="external-link " href="https://safety.veevavault.help/en/lr/01215" target="_blank" rel="noopener">_Product Family_<i class="fa fa-external-link" aria-hidden="true"></i></a> of the primary <a class="external-link " href="https://safety.veevavault.help/en/lr/01287#products-section" target="_blank" rel="noopener">_Case Product_<i class="fa fa-external-link" aria-hidden="true"></i></a>. The connection populates the _Product_ field regardless of if the related _Product_ is inactive in either Vault.
* **Study**: Based on the <a class="external-link " href="https://clinical.veevavault.help/en/lr/59930#components" target="_blank" rel="noopener">_Product Profile_<i class="fa fa-external-link" aria-hidden="true"></i></a> of the <a href="/en/lr/618/">_Document Type Group_</a> in your Clinical Operations Vault for [mapped artifacts][13].

To configure _Product_ mapping for Safety Letters:

* In your Clinical Operations Vault, activate the `product__v` field rule for the [_Crosslink Inbound Integration Rule_][14].
* In your Safety Vault, ensure [mapped document types and subtypes][13] include the standard _Product_ <a href="/en/lr/4884/">shared document field</a>.

If your organization also utilizes <a href="/en/lr/01220/">Safety-RIM Connection</a> to transfer product data to your Safety Vault, Vault matches _Products_ between all Vaults based on the matching _Link_ (`link_sys`) values of _Products_ in Safety and RIM Vaults and _Product Families_ in Clinical Operations. Otherwise, ensure you have configured the appropriate [integration rules][14] to map the _Product_ and _Product Family_ objects.

### Matching Countries {#countries}

Vault determines the <a href="/en/lr/526178/#safety-letters">_Country of Origin_</a> by identifying the _Country_ in your Clinical Operations Vault that matches the _Event Country_ of the <a class="external-link " href="https://safety.veevavault.help/en/lr/01287#events-section" target="_blank" rel="noopener">_Case Adverse Event_<i class="fa fa-external-link" aria-hidden="true"></i></a> in your Safety Vault in the following priority order:

1. _Country Name_ (`name__v`)
2. _Country_ (`country_cda__v`)
3. _Code_ (`code__sys`)

The connection populates the _Country of Origin_ field regardless of if the related _Country_ is inactive in either Vault.

[1]: #clinical_operations_data_migration
[2]: #updating-object-layouts
[3]: #configuring_reference_lookups
[4]: #updating_fields_and_rules
[5]: #lifecycles
[6]: #safety-clinical-operations-vault-connection-components
[7]: #linking-existing-studies
[8]: #configuring-safety-letters
[9]: #integration-rules
[10]: #mapping-vault-clinical-docs-artifacts
[11]: #migrate
[12]: #inactivate
[13]: #mapping
[14]: #integration-rules