ℹ️ 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.
| Term | What it means |
|---|---|
| Draft | Work 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. |
| Version | A form definition that is part of the study design. Versions are listed under Versions on the form and are published with the study. |
| Default version | The 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 Production | The two environments a study is published to. Test is for checking the build; Production is for live data. |
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.
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 status | Can you overwrite it? |
|---|---|
| Not yet published | Yes. 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 only | Yes, 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 Production | No. 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.
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.
Common Mistakes When Changing a Form Mid-Study
- 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.
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.
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.
- Building Forms in OpenClinica: Start Here: where forms fit in a study and which tool to use.
- Build a Form in Form Designer: a reference for every Form Designer setting, including drafts.
- Build a Form with the Form Template: a reference for every Form Template column, including the version setting.
- Publishing Your Study: publish the study to Test and Production.
- Managing Sites: site settings, including each site's default form version.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article