Version Control and Change Analysis for LIMS

Veeva LIMS contains version control functionality for Spec Data, Test Definitions, and Sample Plans.

Version Control for Design Records

Veeva LIMS ensures full traceability between the Lab Tests that are executed and the Spec Data those records were generated from. This is made possible through a versioning mechanism, through a versioning mechanism that locks records in the Effective state type from being edited, and a special Create New Version action must be used before you can make changes. This applies to records related to Test Definitions, Sample Plans and Spec Data.

Versioning your Spec Data does not require you to update (and therefore, version) your Test Definitions, but you may determine that some Spec Data updates need Test Definitions to be added or modified. Conversely, versioning a Test Definition requires you to version any Spec Data (or other Test Definitions) that are referencing it. Versioning a Sample Plan also necessitates versioning any Spec Data that are referencing it.

Prevented Changes in Effective State Type

When a version-controlled record is in the Effective lifecycle state type, Vault prohibits the following actions:

  • Editing fields
  • Adding, removing, or updating related records
  • Deleting records

For example, if a Test Definition record is effective, you cannot add, remove, or amend any Test Definition Result records associated with this effective Test Definition.

Creating New Versions of Design Records

To make changes to Effective design records, users must first execute the Create New Version action in the record’s Actions menu. This action is available to users who have Edit permissions in the lifecycle state associated with the Effective lifecycle state type and access to this action in their permission sets. It creates a new set of records in the Draft lifecycle state type, creates a new Change Analysis record associated with the design record in question, and allows the user to make the necessary field or related record changes without affecting prior versions.

Vault copies the following data forward to the new version:

  • Spec Data
    • Spec Data Sample Action
    • Spec Data Criteria
    • Spec Data Criteria Sets
  • Test Definition
    • Test Definition Step
    • Test Definition Input
    • Test Definition Result
      • Test Definition Result Variable
  • Sample Plan
    • Sample Definition

By making new records using this versioning mechanism, LIMS ensures that the changes will not affect any in-flight or historical data.

Due to the hierarchy of these records, to make changes to a lower level record, such as a Test Definition Result that resides in a Test Definition version, you must create a new version of the top level record first and then create new, draft copies of all the underlying related records.

When a design data record enters the Effective lifecycle state type, Vault automatically moves the prior effective version to the Superseded state type.

About New Effective Sample Plan Versions

Spec Data reference a specific Sample Plan version. If you create a new Sample Plan version and make it Effective, Change Analysis moves the prior Sample Plan version to Superseded and updates any Spec Data referencing the superseded Sample Plan version.

About New Effective Test Definition Versions

Spec Data Criteria reference specific Test Definition versions. If you create a new Test Definition version and make it Effective, Change Analysis moves the prior Test Definition version to Superseded and updates any Spec Data Criteria referencing the superseded Test Definition version.

If your Test Definition contains Test Definition Results with cross-method variables, you will need to ensure the Protocol Variable Targets on your new protocol version are pointing to the correct Sample Definitions and Test Definition Results.

These changes to your protocol require you to make changes to your Lab Specification and its Lab Specification Criteria.

Change Analysis for Design Records

LIMS Change Analysis facilitates the accurate upversioning of underlying LIMS data. When a new version is created, the Change Analysis process identifies all dependent records, allowing users to manage updates to these records all in one place, set a common new effective start date, and approve all the items together. When a new record is created, a related Change Analysis record is also created.

When a new version of a design record is created via the Create New Version action, Change Analysis performs the following actions:

  • Find Change Analysis Items: Ensures that effective records do not reference draft records. Traverses records and surfaces any Effective Spec Data, Test Definition, or Sample Plan records that reference the design record from which the Change Analysis was generated. After all relevant Change Analysis Items have been surfaced, change instructions are added to each record. If a lab user creates an initial record version, the system sets the corresponding Change Analysis Items’ Change Instruction values to New Record. If a lab user creates a new version of a record, the system sets the corresponding Change Analysis Items’ Change Instruction values to New Version.
  • Create Versions for Change Analysis Items: Creates new versions for all Change Analysis Items with a New Version Change Instruction. If new versions already exist for some items, the system does not create additional new versions for those items. Once new versions are created, Change Analysis Item records are updated to include new effective record references to the new version of the originating record. LIMS updates the following references:
Record Category Source Record Reference to Change Update Reference
Spec Data Spec Sample Action (Test Sample) Test Definition Create New Version for Change Analysis Items
Spec Data Spec Sample Action (Collect Sample) Sample Definition Create New Version for Change Analysis Items
Spec Data Spec Data Criteria Test Definition Result Create New Version for Change Analysis Items
Test Definition Test Definition Result Variable Test Definition Result Create New Version for Change Analysis Items
  • Change Analysis Version Check: Ensures that the change can proceed. It consists of two parts:
    • Change Analysis Check: Validates whether a Change Analysis and its subsequent records can be made effective by checking whether all Items and logical blockers have been resolved, as well as confirming that no additional dependencies have surfaced.
    • Version Check: Validates that each impacted record can be made into an effective version.
  • Change Analysis Completion: Completes the Change Analysis and takes the actions in the Change Analysis Items’ Change Instruction field.

Re-merging & Viewing Change Analysis Dependencies

In many cases, when reviewing a Change Analysis, it may not be readily apparent what records it impacts due to multiple versioned items impacting the same Spec Data record or a versioned item having multiple layers of dependencies. To alleviate this, LIMS allows you to re-merge records that are already part of in-progress workflows as well as view all of a Change Analysis record’s dependencies while merging it for approval. To re-merge:

  1. Navigate to the Change Analysis record and select Actions > Merge (Dependencies) Change Analysis.
  2. In the resulting dialog, all Change Analysis records that are part of the current approval workflow are automatically selected. You can use the checkboxes to add or remove Change Analysis records to be included in the envelope for approval.
    1. You cannot select records that are in the Canceled or Approved lifecycle states or part of a different in-progress workflow.
  3. To view the records’ dependencies, select the Identify Dependencies tab. This tab shows all dependencies for the selected Change Analysis records and which records they block.
    1. Dependencies that are in the Approved or Cancelled lifecycle state do not appear in this list.
  4. Use the checkboxes to add or remove dependencies to the envelope for approval. Any dependencies that are eligible to be merged are automatically selected.
  5. Select Merge. If the originating Change Analysis record was already part of an in-progress workflow, you will be prompted to cancel that workflow before starting a new one. This is a necessary step to ensure that the newly added records also progress through the entire workflow.
  6. Select the Workflow to start.
  7. Click Continue.
  8. Enter an Approver and QA Approver if required.
  9. Click Start.

Bulk Updating References

Admins can configure a workflow action in a Change Analysis lifecycle to Bulk Update References to Latest Version. This action queries all outbound references to Design Data that are versioned in the same workflow to determine if there is a more recent version available and, if so, updates the references accordingly. The following fields are included in this query:

  • Spec Data
    • Sample Plan
    • Spec Data Sample Action
      • Sample Plan
      • Sample Definition
      • Target Sample Definition
      • Test Definition
      • Test Definition Variation
    • Spec Data Criteria
      • Test Definition
      • Result to Evaluate
      • Test Definition Variation
      • Variation Result to Evaluate
  • Test Definition
    • Test Definition Result
      • Test Definition Result Variable
        • Target Test Definition
        • Target Test Definition Result

Canceling a Change Analysis

You can run the Cancel Change Analysis action to stop any future actions in the Change Analysis at any time as long as the effective date of the items in question has not passed.

About Calculation Constant Versioning

Veeva LIMS tracks versions of Lab Calculation Constants in a different manner. Every time you edit a Lab Calculation Constant Value record, the system creates a Lab Calculation Constant Value Version record.

When Lab Calculation Constants are referenced by Lab Result Variables, LIMS targets the specific, current version of the Lab Calculation Constant Value record to ensure full traceability if the constant value is ever updated for any reason.

Lab Location History

Every time the Current Location field on a Lab Location is updated, Veeva LIMS automatically creates a related Lab Location History record denoting where it moved from and to, by whom, and the Date/Time. LIMS also creates these records if the Parent Location record is moved to a new location.

The following permissions affect a user’s ability to create new versions and view Veeva LIMS version histories:

  • Object Action Permissions: LIMS: Create New Version: View, Execute for the following objects:
    • Test Definition
    • Sample Plan
    • Spec Data
  • Object Control Permissions: View History for the following objects:
    • Test Definition
    • Sample Plan
    • Spec Data