# Version Control and Change Analysis for LIMS

Veeva LIMS contains version control functionality for <a href="/en/gr/51412705/">Spec Data</a>, <a href="/en/gr/51412703/">Test Definitions</a>, and <a href="/en/gr/51412704/">Sample Plans</a>.

## **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 <a href="/en/gr/51412706/">cross-method variables</a>, 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 {#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. 
    2. 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 <a href="/en/gr/51412706/">referenced by Lab Result Variables</a>, 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.

## **Related Permissions**

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*