# Configuring the eCOA-Clinical Operations Connection

The eCOA-Clinical Operations Connection transfers _Study_, _Study Country_, and _Study Site_ records from your Clinical Operations Vault to your eCOA Vault in near-real time. Streamlining object records reduces duplicate data entry and allows your organization to have a single source of truth for this data.

## Configuration Overview

You must complete the following steps in your Clinical Operations and eCOA Vaults to configure the standard connection:

1. Clinical Operations Vault
    1. [Update object layout][1].
    2. [Verify _Country Code_ field is populated][2].
    3. [Recommended: Update object field requiredness][3].
2. eCOA Vault
3. Establish the Vault to Vault connection between your eCOA Vault and your Clinical Operations Vault. See [Creating & Managing Connections](/en/lr/53358/#how-to-establish-a-vault-to-vault-connection) for detailed instructions.

You must complete these steps in both Vaults in order for the connection to work.

## eCOA-Clinical Operations Connection Components

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

### Connections

<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>: Only one Clinical Operations Vault can be connected to an eCOA Vault. You cannot create additional connections with multiple Clinical Operations Vaults.</p>
    </div>
  </div>
</div>



The following _Connection_ records are delivered as standard in **Admin > Connections**:

* _Clinical Operations-eCOA Connection_ (`epro_clinops_connection__v`) is available in your eCOA Vault.
* _Clinical Operations-eCOA Connection_ (`epro_clinops_connection__v`) is available in your Clinical Operations Vault.

You must [establish the Vault to Vault connection](/en/lr/53358/#how-to-establish-a-vault-to-vault-connection) before you can use it.

### Integrations & 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 Vault to another. These records are read-only and are used by Vault to manage the connection and track any connection errors.

The connection record in both the eCOA and Clinical Operations Vaults include the following default _Integration_ records with standard _Integration Point_ records:

|Integration Name|Integration Point Name(s)|Sent From|Sent To|Included Data|
|--- |--- |--- |--- |--- |
|Study Data|Study Transfer|Clinical Operations|eCOA|Study|
|Study Data|Study Country Transfer|Clinical Operations|eCOA|Study Country|
|Study Data|Study Site Transfer|Clinical Operations|eCOA|Study Site|
|eCOA End-of-Study Media|eCOA Participant Files|eCOA|Clinical Operations|Documents|
|eCOA Study Design Specification|eCOA Study Design Specification|eCOA|Clinical Operations|Documents|

### Configuring End-of-Study Media Integration

When enabled, the _eCOA End-of-Study Media_ integration for the eCOA - Clinical Operations connection automates the creation of eCOA end-of-study participant reports as CrossLinks in the Clinical Operations Vault. CrossLinks are created with the classification and lifecycle configured in Clinical Operations Vault.

Before you enable the _eCOA End-of-Study Media_ integration, your Vault must have _Study, Study Country, and Study Sites_ records linked between eCOA and Clinical Operations Vaults. 


#### Enabling the End-of-Study Media Integration

The _eCOA End-of-Study Media_ integration is _Inactive_ by default. An Admin must enable the **eCOA End-of-Study Media** integration in the Clinical Operations Vaults. 

To enable the eCOA End-of-Study Media integration for eCOA Vaults:

1. Navigate to **Admin > Connections > Clinical Operations-eCOA Connection**.
2. In the _Integrations_ section, locate the _eCOA End-of-Study_ integration and click **Edit**.
3. Update the Status field to Active. 
4. Click **Save**.

To enable the _eCOA End-of-Study Media_ integration for Clinical Operations Vaults:

1. Navigate to **Admin > Connections > Clinical Operations-eCOA Connection**.
2. In the _Integrations_ section, locate the _eCOA End-of-Study Media_ integration.
3. From the **Actions** menu for the _eCOA End-of-Study Media_ integration, select **Activate**.

When you enable the _eCOA End-of-Study Media_ integration in your Vaults, end-of-study media transfer is enabled for all connected _Studies_. 


#### Configuring the Document Type for End-of-Study Media

Once you enable the integration, an Admin must configure the **Document Type for eCOA End-of-Study Media** setting in the Clinical Operations Vault.

To configure the _Document Type for eCOA End-of-Study Media_ setting:

1. Navigate to **Admin > Settings > Application Settings** and click **Edit**. 
2. In the _eTMF Features_ section, select the **Document Type for eCOA End-of-Study Media** checkbox. 
3. Select a **Document Type** from the drop-down. The _Document Type_ must be a document _Classification_.
4. Select a **Lifecycle** from the drop-down. The lifecycle you select must have a steady state defined. 
5. Click **Save**. 


#### Triggering End-of-Study Media Integration

The generation and re-generation of eCOA end-of-study media triggers the creation and updates of CrossLinks in Clinical Operations. When the eCOA Vault regenerates the end-of-study media packages, the eCOA-Clinical Operations connection updates the target _End-of-Study Media_ documents in the Clinical Operations Vault. The connection creates the target _End-of-Study Media_ documents in the selected classification and lifecycle's steady state.   

_End-of-Study Media_ documents in the Clinical Operations vault labels _Restricted_ end-of-study media packages from eCOA Vaults as _Unblinded_. The connection also populates the _Name_, _Study_, _Study Country_, and _Study Site_ fields with the data from the source document. If the connection cannot populate any of these fields, Vault creates a User Exception and does not create the target document.

When an error occurs while processing an end-of-study media record, the connection creates a _User Exception_ and retries the file on the next connection run.
### Configuring the Study Design Specification Integration

eCOA Vaults generate _Study Design Specification_ (_SDS_) documents when study collections are approved as a comprehensive representation of the study build. When enabled, the _eCOA Study Design Specification_ integration enables the eCOA - Clinical Operations connection to automate the creation of eCOA SDS documents as CrossLinks in Clinical Operations Vaults. Before you enable the _eCOA Study Design Specification_ integration, your Vault must have _Study_ records linked between eCOA and Clinical Operations Vaults.

#### Enabling the Study Design Specification Integration

The _eCOA Study Design Specification_ integration is _Inactive_ by default. An Admin must enable the integration in the Clinical Operations Vaults. To enable the eCOA End-of-Study Media integration for eCOA Vaults:
1. Navigate to **Admin > Connections > Clinical Operations-eCOA Connection**.
2. In the _Integrations_ section, locate the _eCOA Study Design Specification_ integration and click **Edit**.
3. Update the Status field to Active. 
4. Click **Save**.

To enable the integration:
1. Navigate to **Admin > Connections > Clinical Operations-eCOA Connection**.
2. In the _Integrations_ section, locate the _eCOA Study Design Specification_ integration.
3. From the **Actions** menu for the _eCOA Study Design Specification_ integration, select **Activate**.

You must enable the integration on both Vaults. When you enable the _eCOA Study Design Specification_ integration in your Vault, eCOA SDS document transfer is enabled for all connected _Studies_. 

#### Configuring the Document Type for Study Design Specification

Once you enable the integration, an Admin must configure the **Document Type for eCOA Study Design Specification** setting in the Clinical Operations Vault.To configure the _Document Type for eCOA Study Design Specification_ setting:

1. Navigate to **Admin > Settings > Application Settings** and click **Edit**. 
2. In the _eTMF Features_ section, select the **Document Type for eCOA Study Design Specification** checkbox. 
3. Select a **Document Type** from the drop-down. The _Document Type_ must be a document _Classification_.
4. Select a **Lifecycle** from the drop-down. The lifecycle you select must have a steady state defined. 
5. Click **Save**. 

#### Triggering Study Design Specification Integration

When users approve a study collection in the eCOA Vault, the connection triggers the transfer of the new or up-versioned _Study Design Specification_ (SDS) documents to the Clinical Operations Vault. When the connection runs for the _eCOA Study Design Specification_ integration, the Clinical Operations queries eCOA for all new and updated _Study Design Specification_ documents for connected _Studies_ that have been updated since the last connection run. The connection creates the target _Study Design Specification_ documents in the selected lifecycle's steady state. When an error occurs while processing an SDS record, the connection creates a [_User Exception_][5] and retries the file on the next connection run.

### User Exception Objects {#user-exception-object}

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 eCOA-Clinical Operations Connection. If either end of your integration can't process an incoming message, Vault creates a _User Exception Message_ record to capture the failure. Vault also creates individual _User Exception Item_ records for each item that failed on the related _Integration Point_ record in the outbound Vault.

System Admins can view and manage these messages from **Admin > Connections > User Exception Messages**. 

A _User Exception Message_ typically means that you need to update your source data in Clinical Operations due to missing fields or incorrect data setup. 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 to run the connection and resolve errors.

### Last Successful Run Field

On every inbound _Integration_ record, the _Last Successful Run_ 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_ field in the following ways:

* If you don't want Vault to transfer existing object records, set this field to the date and time you will activate the connection. Only records created or updated after that date and time will be transferred.
* If you need to rerun every _Integration Point_ within the _Integration_ record, you can clear the _Last Successful Run_ 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.

## Updating Object Layouts {#updating-object-layouts}

For the eCOA-Clinical Operations Connection to work properly, you must add the following fields to the following object layouts in your Clinical Operations Vault:

* Add the _Connect to Vault eCOA_ field to the _Study_ (`study__v`) object layout.
* Recommended: add the _Site Timezone_ field to the _Study Site_ (`study_site__v`) object layout and [make required][3].

## Verifying the Country Code in Clinical Operations {#verifying-country-code}

To transfer a _Study Country_ from Clinical Operations to eCOA, the connection requires that the _Code_ field be populated for _Country_ records in Clinical Operations. Older Vaults may not have this populated. 

You need to verify that _Country_ records in Clinical Operations all have a value in the _Code_ column. You can access Country records by navigating to **Business Admin > Objects > Countries**.

If _Country_ Code values are missing, contact Veeva Services for help.

## Updating Field Requiredness {#updating-field-requiredness}

Clinical Operations should be the source of truth for _Studies_, _Study Countries_, and _Study Sites_. We recommend making the _Site Timezone_ (`site_timezone__v`) field required on _Study Site_ in Clinical Operations to ensure that Clinical Operations is the source of truth. Use the [Required Setting](/en/lr/15057/#required-setting) on the field to make it required.

## Connecting Existing Records

When you configure the eCOA-Clinical Operations Connection, you may have study and other records that were manually created in both Vaults. If you want to connect the existing records across Clinical Operations and eCOA, Vault does not automatically match them. You can, however, link the two records manually using the steps below before setting _Connect to Vault eCOA_ to **Yes** on the _Study_ in Clinical Operations. If you fail to do so, running the connection may result in errors or duplicate records.

1. From your Clinical Operations Vault, copy the **Global ID** and note the **Study Number** of the first _Study_ you wish to link.
2. From your eCOA Vault, locate the _Study_ you want to link based on the _Study Number_ from Clinical Operations.
3. Enter the **Global ID** from your Clinical Operations Vault in the **Link** field of the study in your eCOA Vault.

Repeat these steps for any _Study Country_ and _Study Site_ records that were manually created for that study in both Vaults. Then you can set the records to be transferred moving forward using the _Connect to Vault eCOA_ field on the _Study_ in Clinical Operations.

[1]: #updating-object-layouts
[2]: #verifying-country-code
[3]: #updating-field-requiredness
[4]: #configuring-reference-lookups
[5]: #user-exception-object