Managing CDB Deployments

Clinical programmers continually update listings and views for their data managers throughout a trial’s lifetime. With CDB’s Deployments feature, an organization can track these changes through their review, approval, and deployment.

You can deploy approved custom listings and views from their UAT environment to their production environment. In the UAT environment, you can review each listing and view and mark it as Approved to identify it as ready for deployment. For each custom listing and view, there is an approval log available for download, which tracks that object’s progress through the approval workflow. Once a listing or view is approved, you can deploy it to production by adding it to a deployment package and deploy it from UAT to production.

Prerequisites

For Studies created prior to the 21R3 release (December 2021), this feature must be enabled from the UAT environment in Workbench. See details below.

For Studies created after the 21R3 release, this feature is automatically enabled.

You can determine if this feature is enabled for your Study from the Deploy Enabled column of the Study Listing for your UAT environment. If Workbench shows the Enabled icon (rocket_launch), the feature is enabled.


Users with the standard CDMS Super User study role can perform the actions described below by default. Users with the standard CDMS Lead Data Manager and CDMS Data Manager can perform the approval workflow functions described below. If your organization uses custom Study Roles, your role must grant the following permissions:

Type Permission Label Controls
Functional Permission Workbench Tab

Ability to access and use the Data Workbench application, via the Workbench tab

Functional Permission Manage Deployments

Ability to create and manage study Environments and deploy Studies from EDC Tools, as well as manage and deploy vault-level configuration from Tools > System Tools

Functional Permission View Listings

Ability to access the Listings page


Enable Deployment 21R3 & Earlier

If your Study was created prior to the 21R3 release (December 2021), then you must enable the deployment feature for your Study. If your Study was created after the 21R3 release, then this feature is automatically enabled for your Study.

Workbench includes the Deployment Enabled column in the Study listing. If the Deployment icon () displays in this column, then the feature is enabled in your Study. Note that Workbench only shows this column for UAT environments.

You enable this feature from the Workbench instance containing your study’s UAT environment.

  1. Log in to the Vault that contains your study’s UAT environment.
  2. Click the Workbench tab to open the CDB application.
  3. From the Studies page, locate your Study in the list.
  4. Hover over your Study to show the Study menu ().
  5. From the Study menu, select Deployment. This opens the Enable Deployment page.
  6. Click Continue.
  7. Select the Study Instance (environment) to use as the master set of listings and views. Workbench will create these listings and views in all of your study’s UAT environments, removing any listings or views that don’t exist in the chosen master set.
  8. Click Enable.

Accessing Deployments

You can navigate to the Deployment area from the Navigation Drawer () after you select your Study, or from the Study menu () on the Studies page.

The Deployment tab has three subtabs:

  • Approved Listings: This subtab lists all Listings in the Approved status.
  • layers Approved Views: This subtab lists all Views in the Approved status.
  • watch_later Packages: This subtab lists deployed packages.

Approval Statuses

You can only deploy listings and views that are in the Approved status. There are three approval statuses:

Status Description Badge
Draft The listing or view has not yet been approved. This is the starting state for any new listings or views.
Ready for Approval This listing or view has been reviewed and is ready for approval.
Approved This listing or view has been approved and is ready for deployment.

Returning to Draft Status: If a user saves changes to a Listing or View, Workbench returns it to the Draft status. If the Listing or View has been deployed, the only way to return it to the Draft status is to save a change.

Approval Workflow

To deploy a listing, that listing must be in the Approved status. Listings start out in the Draft status, then users can move them into the Ready for Approval and Approved statuses from the Status menu. You can move a listing to any status from any other status. There is no enforced order of statuses in the current release. The recommended workflow is to move listings or views from Draft to Ready for Approval when development is finished, then move them from Ready to Approval to Approved when review is finished and they are ready for deployment.

To move a listing or view from Draft to Ready for Approval:

  1. Navigate to the Listing or View that you move to the Ready for Approval status.
  2. From the Status menu, select Ready for Approval.
  3. Optional: Enter a Reason.
  4. Click Save.

To move a listing or view from Ready for Approval to Approved:

  1. Navigate to the Listing or View that you want to move to the Approved status.
  2. From the Status menu, select Approved.
  3. Optional: Enter a Reason.
  4. Click Save.

To move a listing or view from Approved to Draft:

  1. Navigate to the Listing or View that you want to return to the Draft status.
  2. From the Status menu, select Draft.
  3. Optional: Enter a Reason.
  4. Click Save.

Approval Logs

Workbench keeps a log of changes to a listing or view’s approval status. You can download this log as a CSV from the listing or view. The CSV file is named “Approval Log <Study> <Listing/View Title> <DateTime of Generation>.csv”.

To download the approval log:

  1. Navigate to the Listing or View for which you want to download the approval log.
  2. From the Listing menu or the View menu (), select Approval Logs.
  3. Workbench generates the CSV file. Download it and review it in a CSV viewer of your choosing.

The approval log contains the following information for each status change:

The approval log contains the following information for each status change:

Column Description
Vault ID The Vault ID for the vault containing the listing or view.
Study Name The Name of the Study.
Object ID The unique Object ID for the listing or view.
Type The Type of the object:
  • LISTING
  • VIEW
Source The Source associated with the listing or view.
Object Name The TItle property value for the listing or view.
Object Short Name The Short Title property value for the listing or view.
Category The Category property value for the listing or view.
Description The Description property value for the listing or view.
Objective The Objective property value for the listing or view.
CQL Syntax The CQL statement for the listing or view.
Created By The Name of the User who created the listing or view.
Created On The date and time the listing or view was originally created.
Last Modified By The Name of the User who last modified the listing or view.
Last Modified On The date and time that the listing or view was last modified.
Last Modified In The Name of the Study Instance (environment) in which the listing or view was last modified.
Current Status The Status that the listing or view moved in to as part of this change:
  • DRAFT
  • READY_FOR_APPROVAL
  • APPROVED
Transitioned By The Name of the User who changed the status.
Transitioned On The date and time that the status change occurred.
Transition Comment The Reason provided for the status change.

Viewing Approval Logs: The approval log contains a CQL Syntax column, which contains the CQL statement for the listing or view. Microsoft Excel™ has a column character limit of 32,767. If the CQL statement is longer than 32,767 characters, Excel™ truncates the value. Veeva recommends viewing approval log CSVs in a viewer that does not have this character limit.

How to Deploy

You deploy listings and views in separate packages. Once you have at least one listing or view in the Approved status, you can create a deployment package of listings or views and deploy it to production.

Failed Deployment: If your deployment fails, contact Veeva Services for help resolving the issue.

Listings

To deploy listings:

  1. Navigate to the Deployments tab for your Study.
  2. In the Approved Listings, subtab, select the Listings you want to deploy.
  3. Optional: Select the Select All checkbox to select all Listings on the current page (up to 25).
  4. Click Deploy rocket_launch.
  5. Optional: Enter a Reason.
  6. In the confirmation dialog, click Deploy.
  7. Workbench begins the deployment job. You can check the progress from Deployment > watch_later Packages.

Views

To deploy views:

  1. Navigate to the Deployments tab for your Study.
  2. In the layers Approved Views, subtab, select the Views you want to deploy.
  3. Optional: Select the Select All checkbox to select all Views on the current page (up to 25).
  4. Click Deploy rocket_launch.
  5. Optional: Enter a Reason.
  6. In the confirmation dialog, click Deploy.
  7. Workbench begins the deployment job. You can check the progress from Deployment > watch_later Packages.

Deployment Packages & Logs

You can review all Deployment Packages and their associated Deployment Logs from Deployment > watch_later Packages.

For each Deployment Package, Workbench shows the following information:

Column Description
Name The Name of the Deployment Package (in the current release, this is always “Deploy”) and the date and time the deployment occurred.
Initiated By The Name of the User who initiated the deployment and the date and time that they did so. You can hover over this value to show the Reason provided for the deployment if one was provided.
Current Status The Status of the deployment job and the number of listings or views contained within this deployment package.

Deployment Statuses

Deployment jobs move through the following statuses:

Status Description Display
Queued The deployment is currently in the job queue. When other jobs finish, Workbench will begin this deployment.
In Progress The deployment is currently in progress.
Deployed The deployment was successful.
Error The deployment job failed. Contact your Veeva Services representative for help.

Download the Deployment Package

To download a Deployment Package:

  1. Navigate to Deployment > watch_later Packages for your Study.
  2. Locate the Deployment Package you want to download in the list.
  3. From the package’s Package menu, select Download Package.
  4. Workbench generates a ZIP file for the package. When finished, Workbench shows a toast notification at the bottom of your screen. Click to download it.

Best Practices for Deployment

Best practices for deployment include:

  • Before enabling deployment in your Study, download the object summary logs for each of your UAT instances. This way, you have a record of those objects in case you accidentally select the incorrect UAT instance as the master.
  • Just before you deploy, download the object summary log in the production environment.
  • Changes to the CQL for a Review Listing clear all review progress. So, when deploying changes to a Review Listing, download a CSV of the listing in the production environment.