Working with Casebook Versions in Studio
When you need to make changes to your study, for example, due to a study amendment or issue, you can use Vault EDC’s casebook versioning feature to manage changes. Vault EDC uses the most recent, published casebook version when you create a new subject casebook.
For information about how casebook versioning works throughout different areas of Vault EDC, see Casebook Versioning in Vault EDC.
Each casebook version is represented by a Casebook Definition object record. The Casebook Definition houses all of the relationships between your study definition object records and data validation rules. Each time you version your Casebook Definition, Vault updates the relationships referencing any updated objects. This helps prevent you from creating duplicate or unintentional copies of object records. Once you complete your initial study design, you can publish your casebook version and use it to create new Casebooks. When a casebook version is Published, all definition objects, except for Rules, become read-only on that version.
The following actions are available to users with the Vault Owner or Design security profiles.
Selecting a Casebook Version
By default, Studio opens the most recent casebook version. You can view and export previous casebook versions within Studio by selecting a version from the Actions menu. For example, you may want to check the Properties of an Item Group Definition that was removed in the most recent version. You can select a previous version that still contains that Item Group Definition and view its configuration in the Properties panel.
You can hover over the current version number to view details about that version.
Exporting & Importing Casebook Definitions
You can export and import your Casebook Definition as an ODM XML document. If you are using manual deployments and a development or UAT vault to test your study design before deploying it to a production vault, you can export the definition from one vault and import it to another.
To export a Casebook Definition:
- In Studio, navigate to the Study for which you want to export the Casebook Definition.
- From the Actions menu, click to expand Casebook Versions and choose which version to export.
- Optional: Enter a file name. By default, Vault names the file with the Study Name and export date.
- Optional: Select the Publish Version checkbox to publish your Casebook Definition upon export.
- Click Export. When the export is complete, Vault sends an email notification, which includes a link to download the ODM XML and a summary CSV file indicating any Item Definitions that Vault skipped exporting due to errors.
To import a Casebook Definition:
- In Studio, navigate to the Study for which you want to import a Casebook Definition.
From the Actions menu, select Import.
- Optional: Select the Ignore import casebook version and add as current version checkbox to import the Casebook Definition into the current version and publish status. This is only available for the first casebook version for a Study.
- Optional: Click Preview. Vault imports a preview version of the Casebook Definition. Note that you will need to perform steps 1 through 3 a second time to fully import the Casebook Definition.
- Click Import. When the import is complete, Vault sends you an email notification.
What’s Included in the XML File
Vault includes the following in the ODM XML file, depending on your configuration and your selections when exporting.
- All design definition records, including any configuration performed in the Properties panel
- Study schedule and layout relationships between design definitions
- Coder Study Settings, including the assigned dictionary release, Synonym List, Stop List, and Therapeutic Area for the study (if selected)
- Rules (if selected)
- Views (if selected and this feature is enabled in your vault)
Validating a Casebook Version
Before you can publish any version of a Casebook Definition, you must validate your study design. Vault EDC reviews your study design and configuration, and sends you a CSV with any errors that must be resolved prior to publishing.
To validate your Casebook Definition:
- In Studio, navigate to the Study that you want to validate.
- From the Actions menu, click to expand Casebook Versions.
- In the confirmation dialog, click Validate.
- Vault begins an asynchronous job to validate your casebook. When complete, Vault sends you an email notification with a link to download a CSV file listing any errors and warnings.
Validation Errors & Warnings
For details about the various errors and warnings you may receive during validation, see Casebook Validation Errors & Warnings.
Vault adds an Error to the CSV log when there is a significant issue with your study design that will interfere with or disallow the creation of new Casebooks. You must resolve these errors before publishing the casebook version. For example, Vault adds an error when there is an Event Group Definition in your design that does not have any Event Definitions associated with it.
Vault adds a Warning to the CSV log when there is an issue with your study design that is less severe. Users in your Study would still be able to create new Casebooks based off of that version, but the design may cause problems during study execution. For example, Vault adds a warning when there is no Signature Definition associated with your Study. This does not prevent Casebook creation, but investigators will be unable to sign Forms without a Signature Definition.
Vault downgrades rule-related errors to warnings when a Rule Definition is Inactive.
Publishing a Casebook Version
Once you complete your updates and resolve any validation errors, you can publish your casebook version.
Note that the Publish Version action does not display until you validate the casebook version.
To publish a casebook version:
- In Studio, navigate to the Study for which you want to publish a casebook version.
- From the Actions menu, click to expand Casebook Versions.
- Select Publish Version.
- Vault publishes your casebook version. Vault EDC makes all definition objects for that version , except for rules, read-only.
You can easily determine whether or not your current version is published from Browse view. When your most recent casebook version is published, Vault displays a Lock icon next to the Studio Actions menu. Once you create a newer version, Vault displays an Unlocked icon.
Creating a New Casebook Version
When you first begin designing your study, Vault automatically creates a Casebook Definition record for your first version. After you have published this initial version, you’ll need to create new versions before making additional changes to your study design.
To create a new casebook version:
- In Studio, navigate to the Study you want to version.
- From the Actions menu, select Create New Version.
- Optional: Enter a Name for the version. This displays in the Studio Actions menu and in Tools > EDC Tools > Casebook Versions. If you do not enter a Name, Vault names your version with the Version Number.
- Select a Change Reason.
- Vault creates a new casebook version. This new version displays in Studio. Changes to this version will not affect existing subject casebooks.
You can see the current version number below the breadcrumb menu in Browse view.
Editing a Casebook Version’s Properties
You can edit the Name and Description properties of a Casebook Definition at any time from Studio.
To edit Casebook Definition properties:
- Click to expand Casebook Versions in the Actions menu.
Select Edit Version Properties.
- In the Edit Casebook Version dialog, edit the Name and Description.
- Click Save.
Vault updates the Name and Description for that version. The new values now display in Studio and in Tools > EDC Tools > Casebook Versions.
Comparing Casebook Versions
You can run a report to show the differences between two Casebook Definitions or two Casebook Definition Versions. This illustrates added, removed, and changed design components. You can also compare two different versions across two different vaults. By comparing versions, you can more easily identify changes and required actions across versions. For example, you may want to compare the current version in your production vault to a newer version in your development vault. You can use the comparison report to identify all the changes and share that information with a study administrator.
See Comparing Casebook Versions to learn how to compare versions.
Which permissions control your access depends on when your vault was created. If your vault uses the Role by Study feature, see the first section, Role by Study Permissions. If your vault does not use the CDMS Role by Study feature, see the second section, Profile Permissions.
Role by Study Permissions
Users with the standard Vault Owner or Design security profiles can perform the actions described above by default. If your vault uses custom security profiles, you must have the permissions described in the Profile Permissions table.
Users with the Vault Owner security profile are automatically able to perform the actions described above.
If your vault uses custom security profiles, you must have the following permissions:
|Security Profile||Tabs: Studio||Ability to access the Studio tab in Vault EDC|
Learn more about permissions sets.