# Configuring CTMS Activity Tracking

CTMS Activity Tracking allows you to record _Clinical Activities_ in your CTMS Vault. Before you can begin tracking Clinical Activities in your CTMS Vault, you must configure the _Activity_ (`crm_activity__v`) object.

## Clinical Activity Setup

Before you can begin using CTMS Activity Tracking, you must update several page layouts to include the _Clinical Activity_ object.

### Update Page Layouts

Configure the following [object page layout](/en/lr/26387/) updates:

* Add an _Activity_ related object section to the _Investigator_, _Study_, _Study Country_, _Study Site_, and _Study Person_ object page layouts.

## Automated Clinical Activities (Optional) {#automation}

Enabling Automated Clinical Activities enhances CTMS Activity Tracking by introducing a job that automatically creates _Clinical Activities_ when _Monitoring Event_ or _Study Communication_ records are created and updated. The automation eliminates the need for study teams to manually create corresponding _Clinical Activities_ after logging _Monitoring Events_ and _Study Communications_.

To enable:

1. [Add the following fields](/en/lr/32857/#assign) to the _Clinical Activity_ object type:
 * _Monitoring Event_
 * _Study Communication_
2. [Add the following fields](/en/lr/26387/#show-hide-move) to the _Study Details_ section:
 * _Monitoring Event_
 * _Study Communication_
3. For each _Monitoring Event_ object type you wish to automate, add the following [Object Type Fields](/en/lr/32857/#assign):
 * _Activity Update Required_
 * _Monitoring Visit Method_
4. [Edit the Page Layout](/en/lr/26387/#show-hide-move) on the _Monitoring Event_ object as follows:
 * Remove the _Activity Update Required_ field
 * Move the _Monitoring Visit Method_ field to the _Monitoring Event Details_ section
5. For each _Study Communication Log_ object type you wish to automate, [add](/en/lr/32857/#assign) the _Activity Update Required_ Object Type Field.
6. [Remove](/en/lr/26387/#show-hide-move) the _Activity Update Required_ field from the _Study Communication Log_ page layout.
7. In **Admin > Operations > Job Definitions**, [edit](/en/lr/22897/#how-to-edit-job-definitions) the _Generate Clinical Activities_ job to activate it.

## Configuring the Clinical Operations to Medical CRM Connection

Using the Veeva Clinical Operations to Medical CRM connection, organizations with both a Clinical Operations CTMS Vault and Medical CRM can exchange data related to Clinical and Medical activities. To use the Clinical Operations to Medical CRM Connection, you must configure the _Activity_ object, configure the remaining relevant components, and configure and activate the connection.

### Medical Activity Setup

To correctly view the Medical Activities from Medical CRM, you must complete the following configuration steps:

* Update Investigator Page Layout
* Activate Medical Activity Object Type

#### Update Investigator Page Layout

Add an _Activity_ related object section to the _Investigator_ object page layout.

#### Activate Medical Activity Object Type

To activate the _Medical Activity_ Object Type, navigate to **Admin > Configuration > Objects > Activity > Object Types** and select the _Medical Activity_ Object Type. Edit the _Medical Activity_ object type and change its **Status** to **Active**.

## Connection

The Clinical Operations to Medical CRM Connection is available in your Clinical Operations CTMS Vault in **Admin > Connections**. You must establish the connection before you can use it. Once you have configured one connection, you can easily copy it to create a new connection. You can create up to 10 different instances of the Clinical Operations to Medical CRM connection so that your Clinical Operations CTMS Vault can be connected to your different Medical CRM organizations.

### Connection Setup: Configuration

Before you begin using the Clinical Operations to Medical CRM connection, you must configure the connection from your Clinical Operations CTMS Vault.

#### Configure the Enter Connected App Details action

You must configure the **Enter Connected App Details** action before using the Clinical Operations to Medical CRM connection.

1. Navigate to **Admin > Configuration > Objects > Connection Authorization**.
2. Click the **Object Types** tab.
3. Click **Actions**.
4. Click the **Actions Menu** and then select **Edit Object Type Actions**.
5. For the _Enter Connected App Details_ action, select the **Basic Auth** (`basic_auth__sys`) object type.
6. Click **Save**.

### Connection Setup: Enablement

You must enable the Clinical Operations to Medical CRM connection in your Clinical Operations CTMS Vault before it is ready to use. This includes:

* Enable and authorize the connection
* Activate CRM/Clinical Operations Transfer job
* Enable Multiple Connections (optional)
* Update User Exception Page Layout
* Create User Exception Report
* Schedule User Exception Report

#### Before You Begin

Vault uses the Connection Authorization to store login credentials and other information it needs to retrieve data from Medical CRM. Before you begin, you must <a class="external-link " href="https://crmhelp.veeva.com/doc/Content/CRM_topics/Medical/ViewMedActVaultClinical.htm#ConfiguringtheClinicalOperationstoMedicalCRMConnection" target="_blank" rel="noopener">find or create a connected app<i class="fa fa-external-link" aria-hidden="true"></i></a> and gather the following information from Medical CRM:

* The _Consumer Key_ and _Consumer Secret_ from **Setup > App Setup > Create > Apps > Remote API Access**
* The Medical CRM _Username_ and _Password_ for your dedicated integration user

#### Enable and Authorize the Clinical Operations to Medical CRM Connection {#enable-and-authorize-the-clinical-operations-to-CRM-connection}

The _Connection Authorization_ and _Authorized Connection User_ options are recommended when configuring an external connection that retrieves data from Vault.

The _Connection Authorization_ is intended to store the user name and password of the external system and can be passed in the message header for authentication on the external system. There must be processing on the external system to handle the user name and password and authenticate on the external system.

The _Authorized Connection User_ can be used to generate a `SessionID` that can be passed to the external system and used for subsequent API callbacks to retrieve data from Vault.

1. Navigate to **Admin > Configuration > Connections**.
2. Click the **Clinical CRM Connection**.
3. Click **Edit**.
4. Update the **Name** field with the name of the CRM organization to which you are connecting.
5. 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.
6. Optional: Select an **Authorization** record for this external connection. If the external connection needs to access data in this Vault, they will do so through this _Connection Authorization_ record. If none exist, you can create one.
7. Optional: Enter a **Description** for this connection.
8. Click **Save**. The connection record is created in an _Active_ state and is available for use immediately.

Next, authorize the connection.

1. Click the **Authorization** field and select **Create Connection Authorization**.
2. Enter the name of the Medical CRM user you are authorizing in the **Name** field.
3. Enter the username of the Medical CRM user you are authorizing in the **Username** field.
4. Click **Save**.
5. From the **Actions Menu**, select **Set Password**.
6. Enter the Medical CRM password for the user you are authorizing the **Password** field. Confirm the password in the **Confirm Password** field.
7. Click **Save**.
8. From the **Actions Menu**, select **Enter Connected App Details**.
9. In the **Connected App Consumer Key** field, enter the key from Medical CRM.
10. In the **Connected App Consumer Secre**t field, enter the secret from Medical CRM.
11. Click **Save**.

You can get the _Consumer Key_ and _Consumer Secret_ from Medical CRM in **Setup > App Setup > Create > Apps > Remote API Access**.

#### Clinical Operations to Medical CRM Connection Settings

Update the Clinical Operations to Medical CRM Connection settings.

1. Navigate to **Admin > Settings > Application Settings**.
2. Click **Edit**.
3. Select the **Enable Global CRM Connection Identifier Mapping** checkbox.
4. Enter the unique identifiers for both your CTMS Vault and Medical CRM in the appropriate fields. For example, in the **Clinical Person Identifier** field, enter the field API name from the _Person_ object. In the **CRM Account Identifier** field, enter the field API name from the _Account_ object.

For the Clinical Operations to Medical CRM connection to work properly, you must establish a link between the Clinical Person and the CRM Account Identifier. The _Clinical Person_ and _CRM Account Identifier_ fields are case sensitive. They must also be unique.

If you are setting up multiple Clinical Operations to Medical CRM connections, you can specify the CRM Account Identifier using the corresponding _CRM Connection Identifier Mapping_ record to map to different identifiers in different Medical CRM instances.

When running the connection, Vault first checks for a mapping on the _CRM Connection Identifier Mapping_ record. If one isn't specified here, it will use the global _CRM Account Identifier_ from Settings. If this is also not specified, the connection fails with a user exception error.

#### Activate the Clinical Operations to Medical CRM Transfer job

The CRM/Clinical Operations Transfer job runs the Clinical Operations to Medical CRM connection. This job runs once per hour once you have activated it.

1. Navigate to **Admin > Configuration > Operations > Job Definitions**.
2. Click the **CRM/Clinical Operations Transfer** job.
3. Click **Edit**.
4. Change the _Status_ to **Active**.
5. Click **Save**.

#### Enable Multiple Connections

If desired, you can establish up to 10 separate Clinical Operations to Medical CRM connections to use with different CRM organizations. Once you have successfully configured the first Clinical Operations to Medical CRM connection, you can easily connect another by copying the existing connection.

1. Navigate to **Admin > Configuration > Connections**.
2. Click the **Actions Menu** of your existing connection.
3. Select **Copy to New**.
4. Update the following connection fields with the appropriate information:
* **Name**: the name of the CRM organization to which you are connecting
* **URL**: the URL of the CRM organization, including https:// and .com
* **Description** (optional): a description with details about the CRM organization to which you are connection
* **Authorization**: update the authorization following the instructions [here][1]
5. Click **Save**.

#### Standard Field Rules

The Clinical Operations to Medical CRM Connection contains standard Field Rules for Inbound and Outbound Integration Rules. If you make a copy of the Clinical Operations to Medical CRM Connection using the **Make a Copy** action, Vault also copies the Field Rules. You can prevent the transfer of a non-required field by inactivating the Field Rule.

#### Restrict Data from Transfer

To prevent the transfer of a specific field, you can inactivate that Field Rule. For example, if you want to prevent the transfer of the From field on the Inbound Integration Rule (Medical CRM to Clinical Operations), you can inactivate the From Field Rule. If you inactivate a Field Rule for a field that is required, however, it results in an error and the transfer fails.

In order to prevent fields from transferring to the opposing system, complete the following steps:

From Transfer from Medical CRM to Veeva Clinical Operations:

1. Navigate to **Connections > Integration Rules** and select the Field Rule you wish to inactivate.
2. Inactivate the Field Rule.

From Transfer from Veeva CTMS to Medical CRM:

1. Navigate to **Connections > Integration Rules** and select the Field Rule you wish to inactivate.
2. Inactivate the Field Rule.

#### Update the User Exception Page Layout

Make the following changes to the User Exception object Page Layout:

1. Navigate to **Admin > Configuration > Objects > User Exception Message**.
2. Update the _User Exception_ page layout to include a related object section for _User Exception Item_. Select the radio button for **Prevent record creation**.
3. Ensure that the columns in the _User Exception Items_ section are in the following order:
* _Exception Item Name_
* _Error Type_
* _Error Message_
* _Item_
* _Item Data_

Vault creates a User Exception Message for each Integration job run when a failure occurs. The User Exception Message consolidates all failed items as _User Exception Items_ and stores them to re-process on the next job run. On the next run, the job processes failed items stored in the most recent User Exception Message and items with a more recent Last Modified Date than Last Successful Run Time on the Integration.

#### Create User Exception Report

We suggest creating a [flash report](/en/lr/51842/) to track and resolve any issues that occur with the connection. First, create a new _[Report Type](/en/lr/21543/)_:

1. Navigate to **Admin > Configuration > Report Types** and click **Create**.
2. Populate required fields.
3. Select **User Exception Messages** as the _Primary Reporting Object_.
4. Click **Add Related Object**, select **User Exception Items (Child)** as the _Related Object_.
5. Click **Save**.

Next, create the report:

1. Navigate to the **Reports** tab and click **Create**.
2. Select the **User Exception Message with User Exception Item** _Report Type_ and click **Continue**.
3. Add the following **User Exception Message** [filters](/en/lr/8591/):
* _Status equals Active_
* _Created Date is in the last 1 day_
* In the CTMS Vault: _Integration in CRM Call Inbound Integration and CRM Call Outbound Integration_
4. Click **Edit Columns** and add the _Error Type_, _Error Message_, _Item_, and _Item Date_ columns.
5. **Save** the report.
6. [Schedule the report](/en/lr/51842/) to run daily and select the **Only send when at least one record is returned** option from the _Email and Vault notification preferences_ drop-down.
7. Update the **[Sharing Settings](/en/lr/3622/#how-to-share-reports)** for the report to ensure it is sent to the necessary users. We recommend sharing with one or more users on your IT team.

## Related Permissions

To perform the tasks described in this article, you must have a security profile that includes the following permissions:

|Permission Type|Permission|Effect|
|--- |--- |--- |
|Security Profile|Admin: Application: Manage Connections|Ability to access the **Connections** tab in **Admin** and activate the _Connections_|
|Security Profile|Object: User Exception Item, User Exception Message: Read|Ability to see _User Exception Item_ and _User Exception Message_ records if a connection failure occurs|

[1]: #enable-and-authorize-the-clinical-operations-to-CRM-connection