# Document Usage Metrics

The _Document Usage_ object captures more comprehensive metrics than Vault's standard document auditing allows, providing a more accurate view of document usage over time. Each time that a user performs specific actions on documents in their _Steady_ state, such as views, downloads, copies, and rendition downloads, Vault automatically creates a new (non-editable) _Document Usage_ object record. Fields on each _Document Usage_ record track key usage metrics for documents in your Vault.


Once the _Document Usage_ object contains data, Admins can create reports to see aggregated metrics, with the ability to drill into record-level details to better understand channel distribution performance. For example, Gladys, a brand manager, can use these metrics to see which documents have the most views or downloads, and to understand which documents are most utilized when determining future resource allocations.

## Captured Events

The _Document Usage_ object captures the following events for _Steady_ state documents:

### Basic Events

  * View Document
  * Download Source File
  * Download Rendition
  * Download from Distribution
  * Copy

### Brand Portal Events

  * View Document (via Brand Portal or Medical Portal)
  * Download Source File (via Brand Portal or Medical Portal)
  * Download Rendition (via Brand Portal or Medical Portal)

### Send as Link Events

  * View Document (via Send as Link)
  * Download Document (via Send as Link)
  * Download Video (via Send as Link)

### Integration Events

  * View Document (Embedded Viewer)
  * Download Document Rendition (Embedded Viewer)
  * Download Source File (Embedded Viewer)
  * View Document (Standalone Viewer)
  * Download Document Rendition (Standalone Viewer)
  * Download Source File (Standalone Viewer)

## Metric Descriptions

<table class="wbord">
  <tr>
    <td>
      <p>
        <strong>Object Field</strong>
      </p>
    </td>
    <td>
      <p>
        <strong>Description</strong>
      </p>
    </td>
    <td>
      <p>
        <strong>Example Data</strong>
      </p>
    </td>
  </tr>
  <tr>
    <td>
      <p>
        Name
      </p>
    </td>
    <td>
      <p markdown="span">
        [System Managed](/en/lr/30986/): DU-{##########}
      </p>
    </td>
    <td>
      <p>
        DU-0000000001
      </p>
    </td>
  </tr>
  <tr>
    <td>
      <p>
        Document ID
      </p>
    </td>
    <td>
      <p>
        Document ID and Version of viewed document
      </p>
    </td>
    <td>
      <p>
        (Cholecap Works (v1.0))
      </p>
    </td>
  </tr>
  <tr>
    <td>
      <p>
        Document Type
      </p>
    </td>
    <td>
      <p>
        Document Type Detail of viewed document
      </p>
    </td>
    <td>
      <p>
        Patient Education
      </p>
    </td>
  </tr>
  <tr>
    <td>
      <p>
        User
      </p>
    </td>
    <td>
      <p>
        Username of user who performed the action
      </p>
    </td>
    <td>
      <p>
        John Doe
      </p>
    </td>
  </tr>
  <tr>
    <td>
      <p>
        Activity Type
      </p>
    </td>
    <td>
      <p>
        The performed action:
      </p>

      <ul>
        <li>
          View
        </li>
        <li>
          Copy
        </li>
        <li>
          Source Download
        </li>
        <li>
          Rendition Download
        </li>
      </ul>
    </td>
    <td>
      <p>
        View
      </p>
    </td>
  </tr>
  <tr>
    <td>
      <p>
        Activity Date
      </p>
    </td>
    <td>
      <p>
        Date and time the event occurred
      </p>
    </td>
    <td>
      <p>
        9/22/2017 9:12 AM PDT
      </p>
    </td>
  </tr>
  <tr>
    <td>
      <p>
        Channel
      </p>
    </td>
    <td>
      <p>
        Application in which the action occurred:
      </p>

      <ul>
        <li>
          <em>Vault</em>, if the event was triggered from Vault
        </li>
        <li>
          <em>Brand Portal</em>, if the event was triggered from Brand Portal or Medical Portal
        </li>
        <li>
          <em>External</em>, if the event was triggered from an external site
        </li>
      </ul>
    </td>
    <td>
      <p>
        Vault
      </p>
    </td>
  </tr>
  <tr>
    <td>
      <p>
        Context
      </p>
    </td>
    <td>
      <p>
        Additional metadata to provide more context:
      </p>

      <ul>
        <li>
          <em>Vault</em>, if the channel was Vault
        </li>
        <li>
          <em>External</em>, if the channel was External
        </li>
        <li>
          <em>Portal Name</em>, if the channel was Brand Portal or Medical Portal
        </li>
      </ul>
    </td>
    <td>
      <p>
        Vault
      </p>
    </td>
  </tr>
</table>

## Object Visibility

The _Document Usage_ object is a [raw object](/en/lr/62987/) that is automatically enabled in all Vaults and tracks usage from the time of enablement forward. Before you can access _Document Usage_ data, you must [configure a report type](/en/lr/21543/) on the _Document Usage_ object, or an Admin must set up a custom tab. From a report or custom tab, you can edit columns and export data, making it easy to see the most relevant metrics in your preferred format.

## Document Usage Record Retention

The _Document Usage Cleanup_ job deletes _Document Usage_ records older than 36 months. This job also deletes records that reference deleted documents, even if they are newer than 36 months. Deleted _Document Usage_ records cannot be recovered. 

When the job runs, Vault creates a _System Audit History_ record that indicates the number of deleted records. 

## Related Permissions

You must have a security profile that grants the _Document Usage: Read_ [object permission](/en/lr/22824/#objectpermissions) to view the _Document Usage_ object in a custom tab.