> ## Documentation Index
> Fetch the complete documentation index at: https://docs.carelane.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pathway Versioning

> Manage participant pathways through a Draft, Testing, Approved, and Retired lifecycle

Pathway versioning lets you evolve a study's participant pathway — questionnaires, schedule of activities, study arms — through a formal lifecycle without disrupting participants already enrolled on a prior version. You can iterate in a draft, validate on designated test sites, approve for production, and retire old versions when they are no longer in use.

## What Gets Versioned

A **CRF version** bundles everything that defines the participant pathway for a study:

* All questionnaires (CRFs)
* The schedule of activities (pathway structure)
* Study arms
* Citations

Each version has a human-readable label (for example, "Version 1.0") and a short identifier. A draft can be created from scratch or "based on" an existing version — the latter copies all forms and settings so you only need to change what differs.

## Lifecycle

| Status       | Colour | Meaning                                                                         |
| ------------ | ------ | ------------------------------------------------------------------------------- |
| **Draft**    | Orange | Editable working copy. Safe to rename, restructure, or delete.                  |
| **Testing**  | Blue   | Locked for validation. Test sites can enrol participants against it.            |
| **Approved** | Green  | Production version. New participants enrol on this version.                     |
| **Retired**  | Grey   | Previous production version. Retains all historical data but no new enrolments. |

```
Draft → Testing → Approved → Retired
```

Transitions are one-way. To iterate on a Testing or Approved version, use **Copy as new draft** to create a fresh Draft that is "based on" the locked version.

## Where to Find It

Pathway versioning lives on the **Participant Pathway** page under Study Design. The dashboard groups versions by status (Approved, Testing, Draft, Retired) and shows the "based on" lineage between versions.

## Creating and Editing a Draft

<Steps>
  <Step title="Create Draft">
    On the Participant Pathway dashboard, click **Create Draft**. Choose to start from scratch or base the draft on an existing version.
  </Step>

  <Step title="Edit Content">
    Edit questionnaires, the schedule of activities, and study arms as you normally would. All edits are saved against the draft without affecting any other version.
  </Step>

  <Step title="Name and Describe">
    Set the version label (e.g. "Version 2.0") and an optional description. Both can be updated until the draft leaves Draft status.
  </Step>
</Steps>

<Note>
  Study arms can only be modified in Draft status. After a version is submitted for Testing, its arms are locked.
</Note>

## Submitting for Testing

When a draft is ready to validate:

<Steps>
  <Step title="Submit for Testing">
    Open the draft and click **Submit for Testing**. The version transitions to **Testing** and becomes immutable.
  </Step>

  <Step title="Validate on Test Sites">
    On any site that is designated as a test site, enrol participants against the Testing version using the version selector.
  </Step>

  <Step title="Iterate If Needed">
    If validation finds issues, create a new draft with **Copy as new draft** and start again. Testing versions cannot be edited directly.
  </Step>
</Steps>

<Tip>
  A site becomes a **test site** through its organisation type (set by an organisation admin). Test sites can enrol participants even when the study is not yet active, and they see a version selector when both Approved and Testing versions exist.
</Tip>

## Approving for Production

<Steps>
  <Step title="Approve the Testing Version">
    Open the Testing version and click **Approve**. The version transitions to **Approved** and the previous Approved version (if any) is automatically retired.
  </Step>

  <Step title="New Enrolments Use the New Version">
    All participants enrolled from this point forward are bound to the new Approved version.
  </Step>
</Steps>

<Warning>
  If the Approved version has more than one study arm, the public participant self-registration portal is automatically disabled. Manual enrolment through sites is unaffected.
</Warning>

## Participants Already Enrolled

Participants are bound to the version that was Approved when they were enrolled. When a new version is approved, **in-flight participants stay on their original version** — they do not migrate. The previous Approved version moves to Retired, which preserves all its historical data for ongoing data collection.

This means:

* Existing participants continue to complete the pathway they were enrolled on.
* New participants enrol on the newly Approved version.
* Retired versions remain visible on the Participant Pathway dashboard so you can see which pathway any given participant is on.

## Audit Trail

Every version event is recorded in the study audit trail:

| Event                          | What is Captured                                                                 |
| ------------------------------ | -------------------------------------------------------------------------------- |
| **Created / Copied / Deleted** | Who, when, source version (for copies)                                           |
| **Status Change**              | Old status, new status, display text (e.g. "CRF 'Version 1.0': status changed.") |
| **Study Arms Updated**         | Before / after snapshot of the arms list                                         |

## Permissions

Version lifecycle transitions (Submit for Testing, Approve, Retire) require the **Study Manage** permission and are typically held by Chief Coordinating Investigator, Deputy Coordinating Investigator, and Study Administrator roles.

## Best Practices

<AccordionGroup>
  <Accordion title="Always Test Before Approving">
    Use Testing + a test site to dry-run every non-trivial change. Approved is final — to fix a mistake, you have to create a new draft.
  </Accordion>

  <Accordion title="Base Drafts on the Current Approved Version">
    Unless you are starting a fundamentally different pathway, use **Copy as new draft** from the Approved version so that participants already on it stay comparable.
  </Accordion>

  <Accordion title="Keep Version Labels Meaningful">
    Treat the version label like a software release tag. "Version 2.0 — add safety follow-up at week 12" is more useful to future you than "v2".
  </Accordion>

  <Accordion title="Don't Use Testing as a Staging Pathway">
    Testing is for validation, not long-term parallel production. Approve it, or discard it and start a new draft.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Participant Pathways" icon="route" href="/participants/participant-pathways">
    The participant-facing view of the pathway.
  </Card>

  <Card title="Study Arms" icon="code-branch" href="/study-design/study-arms">
    Arms are versioned along with the pathway.
  </Card>
</CardGroup>