Versions and Changing Forms After Go-Live

Modified on Fri, 20 Nov at 4:41 PM

 

ℹ️ This page is for Data Managers responsible for study design.

 

In OpenClinica, you change a form by saving your changes as a Form Designer draft or in a Form Template. The changes become part of the study when you add the draft to the study or upload the template, which creates or updates a form version. Data already collected stays tied to the version it was entered in. This article explains drafts and versions, when you can overwrite a version, which changes are never allowed once a version exists, how to bring back an item from an earlier version, and what to plan for when an electronic case report form (eCRF) changes mid-study, for example after a protocol amendment.

 

For how to build and save a form, see Build a Form in Form Designer or Build a Form with the Form Template.


 

Drafts, versions, and the default version

 

In OpenClinica Form Designer, a form moves from draft to version; uploading a Form Template creates a version directly. One version is the default for new data entry. Use this table to tell these terms apart.

TermWhat it means
DraftWork saved in Form Designer with Save Draft. Drafts are listed under Drafts on the form in Study Designer, with the newest labeled (latest). They are not published and not recorded in the Activity Log.
VersionA form definition that is part of the study design. Versions are listed under Versions on the form and are published with the study.
Default versionThe version used for newly added form cards in Study Runner. Select it with the button next to the version ("Selected indicates default version for data entry").
Test and ProductionThe two environments a study is published to. Test is for checking the build; Production is for live data.
ℹ️ Note: If a site's settings have ever been changed, publishing from Study Designer does not overwrite them. After you change the default version in Study Designer, also update the default version in the site settings of each of those sites. See Managing Sites.

 

How a version is created

 

In OpenClinica, you create a form version from a Form Designer draft or by uploading a Form Template.

  • Form Designer: save a draft, then choose Add to Study from the draft's menu.
  • Form Template: click Upload on the form. The uploaded spreadsheet becomes a version immediately.

 

The version identifier comes from the Version number in Form Designer's Layout & Settings, or the version column on the template's settings sheet. A new identifier creates a new version. The same identifier overwrites the existing version, if that is allowed.

 

The version identifier is required and can be up to 255 characters. Any characters are accepted, but OpenClinica builds the version's object identifier (OID) from only its first 10 letters and numbers. To keep versions easy to tell apart, use letters, numbers, and underscores, and make the start of each version different.

⚠️ Warning: Watch out for overwriting form versions that have not yet been published to Production. A new Form Designer draft can keep the version number of an existing version. If you choose Add to Study without changing the Version number in Layout & Settings, the draft replaces that version, and the version's earlier content is lost from the form. The same applies to the Form Definition file: uploading a spreadsheet whose version matches an existing version replaces it. To avoid this, change the version number before you add a draft to the study or upload a spreadsheet, and discard drafts you no longer need. Each time you publish the study, OpenClinica keeps a read-only copy of the study design, so a version that has been published can be recovered. See Publish History.

 

Can I overwrite a form version?

 

In OpenClinica, you can overwrite a form version until it is published to Production. Use this table to check a version's status.

Version statusCan you overwrite it?
Not yet publishedYes. If the form has other versions, items and groups that also appear in those versions must follow the rules in Which form changes are not allowed after go-live?
Published to Test onlyYes, with limits. Items and groups that were in this version when you published it to Test, or that appear in any other version of the form, must follow the rules in Which form changes are not allowed after go-live?
Published to ProductionNo. A lock icon marks the version. Uploading it again fails with: A form version cannot be replaced after it has been published to Production. You must upload it as a new form version.

 

Which form changes are not allowed after go-live?

 

In OpenClinica, once an item or group exists in any version of a form, these changes are not allowed in later versions of the form, or when you overwrite a version that has been published to Test:

  • Changing an item's data type, for example from text to integer, or from Select One to Select One (External List).
  • Moving an item to a different Item Group.
  • Moving an item into a repeating group, or out of one.
  • Changing a repeating group to a non-repeating group, or a non-repeating group to a repeating group.
ℹ️ Note: To make one of these changes, add a new item with a new Item Name instead. To change a group, add a new group with a new name. Data already collected stays with the original item or group. To move existing data into the new item, see Importing Data.

 

For the upload error that each change causes and how to fix it, see Common Form Definition Upload Errors.


 

Which changes are allowed in a new version?

 

In OpenClinica, you can make these changes to a form in a new version.

  • Changing question text, hints, edit check (constraint) messages, required messages, and appearance.
  • Adding, changing, or removing skip logic, edit checks, required settings, and calculations.
  • Adding new items and groups.
  • Removing items from the new version. Earlier versions keep their own items.
  • Adding response options. All option values together, and all labels together, must stay under 4,000 characters across every version of the form.

 

Bring Back an Item from an Earlier Version

 

In OpenClinica, an item removed from a form version is not deleted. Earlier versions keep it, and its data stays in extracts. To add the item back in a later version so that new data joins the existing data, add a question that matches the original exactly:

  • Item Name: the same name, with the same capitalization. ae_date and AE_Date are different items.
  • Item Group: the same Item Group.
  • Item type: the same type, such as Integer or Select One.
  • Repeating group: the same placement, inside or outside the same repeating group.
⚠️ Warning: OpenClinica does not tell you when a question you add is a new item instead of the old one. A different Item Name or Item Group creates a new item, so the same question is stored under several items across form versions and is hard to report on. Check the Item Name and Item Group of the earlier version before you add the item back.

 

Common Mistakes When Changing a Form Mid-Study

⚠️ Warning: These mistakes can split one question's data across several items or remove collected data. Check for them before you add a new form version in OpenClinica.
  • Item Names are case-sensitive. Renaming item1 to Item1 does not rename the item. It creates a new item, and data stays under the old name.
  • Keep response values stable. If the value 1 means Yes in one version, do not reuse 1 for a different answer in another version.
  • Repeat counts. If a repeating group's repeat count goes down, the last repeats are removed.
  • External lists and media. CSV (comma-separated values) and image files belong to the version they were uploaded with. To change them after the form is in Production, upload them with a new version.
  • Events lock too. After a study is published to Production, an event's type cannot be changed, and a repeating event cannot be made non-repeating.
ℹ️ Note: One event change is still allowed after the study is published to Production: you can change a non-repeating event to a repeating event.

 

Archive and Restore

 

In OpenClinica Study Designer, archive a form version to retire it so that it no longer appears as an available option in Study Runner, or archive a form to remove it from an event.

  • To retire a version, open its menu and choose Archive.
  • To remove a form from an event, open Form Actions and choose Archive.
  • Archived versions and forms can be restored from the Archived Items menu.
ℹ️ Note: You cannot archive the default form version. To archive it, first select a different version as the default, then archive it.

 

✅ Tip: Publishing publishes the whole study design. To publish and test other parts of the design while a form version, form, or event is still in progress, archive it first. Restore it from the Archived Items menu when it is ready.

 

✅ Best practice: Before you archive a form version, move its data to the latest version of the form.

 

For more information on archival best practices, refer to Archive Form Versions and Forms: Best Practices.


 

Key Terms

 

These are the main OpenClinica terms used in this article.

 

Form version: a form definition that is part of the study design. Data is always tied to the version it was entered in.

 

Draft: work saved in Form Designer that the study does not use until you add it to the study.

 

Default version: the form version used for new data entry.

 

Item Name: the variable name stored in data extracts. It is case-sensitive.

 

Item Group: the dataset or domain an item is stored in.

 

Archive: retire a form version or form without deleting its data.


 

Frequently Asked Questions

 

How do I add back an item that was deleted from an earlier form version in OpenClinica?

 

In OpenClinica, add a new question with exactly the same Item Name, including capitalization, the same Item Group, the same item type, and the same repeating-group placement as the original. OpenClinica then treats it as the same item, so new data joins the data collected in earlier versions. A different name or Item Group creates a new item.


Can I change an eCRF after the study goes live in OpenClinica?

 

Yes. In OpenClinica, add a new form version with the change. You can change question text, logic, and response options, and add or remove items. You cannot change an item's data type, Item Group, or repeating-group placement. A version published to Production cannot be overwritten, so change the version number before you upload or add to study.


What happens to data when I archive a form version in OpenClinica?

 

In OpenClinica, data on an archived form version stays in reporting and data extracts, as long as the whole form is not archived. The data can be viewed but not changed until you restore the version and publish the study. The best practice is to move the data to the latest version before you archive.

 

How do I keep a form version I am still working on out of a publish in OpenClinica?

 

In OpenClinica, publishing publishes the whole study design. Form Designer drafts are never published, but every form version that is added to the study is. To leave out a version you are still working on, archive it in Study Designer before you publish, then restore it from the Archived Items menu when it is ready. You can do the same with forms and events.


 

Related Articles

 

These OpenClinica articles cover building and changing forms.


Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article