OpenClinica User Manual/CRFandOIDissues

Avoiding problems with rule OIDs

The XML that defines rules refers to OIDs, the system's internal codes for CRFs, Events and Item Names. Problems arise if your study set up causes these OIDs to be generated randomly at the time of CRF upload (https://docs.openclinica.com/3.1/rules/oid-overview). If the OIDs on your live server differ from your test server you will need a different rule XML for each. You can simplify the creation of rules in your study by following procedures and naming conventions that ensure that OIDs in the study are predictable.

Problems when uploading CRFs

If you overwrite existing CRF versions in the database

Don't upload a new version '0.3' over '0.3', as random OIDs are generated for overwritten items. Either:

• change the version number of the new CRF in the CRF tab before uploading or
• delete the currently uploaded version before uploading (see 'Working around problems during development and test' below if the CRF is referenced by an event or has been used for data entry).

The new CRF's OIDs should match those of the currently uploaded version. Note that in a rule you don’t need to specify a specific version of a CRF, you can miss off ‘_V3’ from the target CRF end, references to F_LIRAGLUTIDE_V3 can be changed to F_LIRAGLUTIDE.

If you reorder items

If a new CRF version reorders existing items, then the items may be given random OIDs.

To avoid this problem, ideally you would simply delete the current version in the database, but sometimes that version can't be deleted, as it is referenced by an event or has data entry. See 'Working around problems during development and test' below.

Working around problems during development and test

During development there are sometimes issues when uploading a CRF to the database, either:

• If items are reordered (which causes problems with OIDs) or
• If items change significantly and OpenClinica displays a warning message during upload, such as:

The item: xyz in your spreadsheet already exists in the DB with different response options/text. You cannot code an existing response option with a different text, or code an existing response text with a different option. Please check it and upload your spreadsheet again

In these cases you can either:

• Delete the CRF version currently in the database (sometimes this isn't possible because it is referenced by an event or data entry has started using it)
• Change the item names for significantly changed items (so OpenClinica sees the items as new)
• Upload new versions of the CRF to the database removing all conflicting items. Point any events to the new version. Delete all old versions containing the conflicting items. Then upload a version with updated items.

If the preferred option is to delete the items from all versions of the CRF, this can be done by:

1. Create and upload a version without the items with a temporary version number, e.g. 0.3a. This version can be very stripped-down to allow the maximum number of changes, e.g. a single items with a temporary unique item name
2. Alter any events referencing old versions to use the temporary version (e.g. 0.3a)
3. Delete all data entry for old versions of the CRF. When you attempt to delete an old version OpenClinica displays the ids where data entry has started with the version of the CRF. Use this id to find the scheduled event where the CRF that needs to be deleted is. The data entry using the CRF version should be listed in the CRFs within the event ready for deletion. The 'Delete' button will appear for the CRF if at least one page of the CRF is complete (if not, complete at least one page with dummy data such that the 'Delete' button appears).
4. Delete old CRF versions (e.g. 0.1 and 0.2)
5. Upload the replacement version (e.g. 0.3)
6. Alter any events to use the replacement version (e.g. 0.3)
7. Delete the temporary version (e.g. 0.3a)

Issues when deleting CRFs (OpenClinica 3.1 and later)

Note: This issue only applies in OpenClinica 3.1.2 and later (3.0.3 does not have this issue).

There should be no issues deleting CRFs when there are no rules in the database. However, be aware when deleting CRFs that are referenced by existing rules, that these rules may be left orphaned (https://issuetracker.openclinica.com/view.php?id=16336). You may need to give your rules new OIDs and re-upload them (technical explanation: This occurs because within the database, the rule_set table's item_id column doesn't enforce referential integrity when referencing the item table).

Here's an SQL query to identify affected rules:

select distinct rule.id,rule.oc_oid,rule.rule_expression_id from rule_set,rule_set_rule,rule where 
rule_set_rule.rule_id = rule.id and
rule_set_rule.rule_set_id = rule_set.id and
not exists (select 1 from item where item.item_id=rule_set.item_id) order by rule.id;

Naming conventions to avoid problems

Conventions for CRFs where the server hosts multiple trials

1. Define a short (2 character), unique trial code for each study on the server, e.g. 'AA'
2. The first 2 characters of a CRF name should be the short trial code as CRFs from multiple trials are grouped together when viewing CRFs (it also helps avoid overlaps with CRF names from other trials).
3. The first 2 characters of a rule OID should be the short trial code as rule OIDs need to be unique within a server (e.g. AALXORLTICK includes the prefix 'AA'). This avoids rule OIDs in similar events such as Adverse Events from overlapping.
4. Event names need to be unique within a server (e.g. 'AA Concomitant Medications', otherwise OIDs will be given random suffixes. Events should be given prefixes that match the prefixes of CRFs. This avoids overlaps for common events such as Adverse Events.

Conventions for Events, CRFs and Items

1. The first 5 characters (ignoring spaces) of CRFs should be unique within the server. These characters are used to create the group name for items in the CRF that are ungrouped, as well as composite ItemNames for items. If you have a series of CRFs named 'Visit 1', 'Visit 2' etc. you may want to name them by placing the number before the string, e.g. '1 Visit' and '2 Visit' etc..
2. If the trial is to be hosted on a server hosting multiple trials, a CRF named 'Visit 1' in a study with the short trial code of 'AA' could be named 'AA 1 Visit' (see 'Naming conventions for CRFs where the server hosts multiple trials', above).
3. The first 20 characters of Item names should be unique. In practice this means the first 13 characters of item names need to be unique (12 in 3.0.4 and above), as the first 7 characters of item names are based on the CRF name, e.g. the item name starts “I_XXXX_”, where XXXX is the first four characters of the CRF name (five characters in 3.0.4 and above).
4. When exporting to XML, the SASFormatName contains the itemname truncated to 8 characters in length (as of OpenClinica 3.0). So, if you plan to import the data into SAS, you may wish to restrict your itemnames to 8 characters.
5. When naming an Item name used in a calculation, you may want to consider using a user-friendly name as the Item name is displayed to the user when the field is empty.