The library has been designed to facilitate the reuse of common data elements and to provide a community resource for the storing, browsing and extraction of these elements.
This will help researchers standardise studies, by allowing them to use predefined documents or create documents containing predefined elements during study design. This provides flexibility in designing studies while also allowing consistency across studies and improving quality through validation of elements (see element approval).
The library stores a collection of reuseable elements. An element can be an document, a part of an document, such as a question or description (collectively known as entries), or a validation rule, which is used to restrict the answers to questions.
Document: An document held by the library is a reusable electronic clinical research form (or questionnaire) and contains other elements (such as entries and validation rules).
Entry: An entry is an element within an document. For example, a description (narrative), a question or collection of questions. The elements can be of different types, such as 'text entry', 'numeric entry' or 'date entry'. These types are the same types that you can add to an document within the openCDMS Create.
Some entries are known as 'compound elements' as they depend on other entries. An example of a compound element is a derived entry, which references other entries used to complete the calculation specified within that entry's definition. As a result, importing a derived entry (or any other compound entry) also imports the elements upon which it depends.
Derived entries can have one or more tests associated with them in order to verify that the calculation performed by the entry is correct. A derived entry with tests can only be approved when all the tests are run successfully.
An entry can be held by the library on its own or as part of an document, in both cases the entry can be reused within another document inside or outside of the library.
The library is populated with generic elements that are likely to be reused across multiple forms, such as sex, gender, age, ethnicity, etc.
Validation Rule: A validation rule is used to restrict the potential answers to entries and so is typically associated with one or more entries. A validation rule associated with an entry is automatically added to the library when the entry is submitted, although it can also be submitted independently if required.
To verify the validation rule works as expected it can have one or more tests associated with it. A validation rule with tests can only be approved when all the tests are run successfully.
An element can be added to the library in two ways.
1. By using the library view to create a new element.
2. By adding an existing element from a study. It is possible to add documents to the library by right-clicking on the document in the study tree and selecting 'save to library'. Note: it is only possible to add new elements in this way, existing library elements must be edited using the library view.
In order to use or edit an element from the library it first needs to be imported into the revelant local study. Elements can only be edited by importing them into the library view.
There are two ways to launch the search facility within the openCDMS Create, from the left hand side tree view, or from the main menu when in the library view.
To search for documents, using the tree view right-click on a study or the library view icon and select the option from the menu. To search for entries right-click on an document and select the option from the menu.
Alternatively, when the library view is open, from the main menu select the relevent search option from the 'Library' menu.
The 'Search' dialog will then launch. You can search for elements in the library by name using the 'search text' field, or by leaving the field blank to find all elements of the selected type. As shown in Figure 5.10, “Library search dialog”, the dialog allows you to select the 'Search Type'. This specifies how your search should match the element names in the database. Your choices are 'begins with', 'ends with', 'contains', or 'exactly matches'. For example, if you wanted to see all the elements whose name begins with 'A', you would type 'A' as your search text, and specify 'begins with' as your 'Search Type'.
If you know you are after a particular kind of element (e.g. date entry), you can restrict your search so that only date elements will be returned. You do this by specifying the 'Element Type'. The search you have specified is summarised in plain English at the top of the dialog in the 'Current Search' field.
The 'advanced' tab allows you to further restrict the search by a particular document, element status (i.e to select only pending or approved elements) and/or by current revision. The current revision refers to the most recent version of an element as stored by the library.
Once you have specified your search, press the 'Search' button.
The 'Search Results' panel (see Figure 5.10, “Library search dialog”) shows you the elements that matched your search criteria. The 'Results' field indicates how many matches there were. If there were numerous matches, only a limited number will be specified initially. You can use the 'More' button to retrieve more of the search results.
The top table shows you the results summary, listing the element name, current revision level, and also the element type (e.g. document, text entry or date entry, etc). By clicking on one of the result rows, it is possible to see even more information about that particular element in the 'Revision History' table below it.
The Revision History table shows the complete history of the highlighted element, by displaying the past revisions. It displays who modified it, when it was modified and a description of the reason for revision.
The preview feature is to help you decide whether you would like to import the element. To preview an element, select the desired revision level from within the 'Revision History' table (or if none is selected the most recent revision is shown by default) and then press the 'View' button at the bottom of the dialog. For an document the document itself will be displayed in a new window. For other elements a dialog window will display the element's properties, allowing you to inspect the element details.
Manipulation of elements in the library is done inside the library view within the openCDMS Create. Elements can only be created or edited within the library view.
The library view is opened by selecting 'File' -> 'Open Library View'
To create a new document right click on the Library view icon within the left-hand tree and select 'New document'. You will then be prompted to enter a name for the document and it will then appear in the left-hand tree. The document can then be opened and entries added in the normal way. Entries cannot currently be created outside of a document.
In the library view derived entries can have tests to verify their correct functioning. Tests can be viewed or added by right-clicking on a derived entry, selecting 'Edit' and then choosing the 'Test Cases' tab. Click on the 'Add' button to create a new test.
To create a new validation rule select 'Library' -> 'Manage Validation Rules' and create a rule in the normal way. In the library view validation rules can have tests added to verify the correct function of the rule. To create a test simply select a validation rule within the 'Manage Validation Rule' dialog and click on the 'Create Tests' button.
Once documents or validation rules have been created within the library view they can be submitted to the library. They can be submitted at any time and once submitted they will be marked as 'pending'. Any element marked as pending cannot be added to another element (for example a validation rule cannot be attached to an entry) and cannot be used within a study until it has been approved.
To submit an element, either go to the menu and select 'Library' -> 'Save documents(or Validation Rules) to Library' or in the left-hand tree right click on the Library and select 'Save documents to Library'. A submission dialog will then appear (see Figure 5.12, “Element Submission Dialog”).
The submission dialog shows you the elements that are currently eligible for submission to the library. All of those that are new (not yet entered into the library) are marked with a 'Submission Type' of 'New Submission' and all edited elements are marked with a 'Submission Type' of 'Revision'.
First, you need to enter some comments that summarise the purpose of the element or the edits that have been made. Then select the element from the list and press the 'Submit' button. While it is possible to submit more than one element at once, it may be best to make multiple submissions and submit only elements that the comment relates to each time.
It is worth noting that, if you have added a compound element that has subordinate entries, such as a derived entry or an entry with a validation rule, that the parent entry and all of its subordinates will be submitted to the element library.
To make a change to one of the elements in the library, first import the element and then change the element using the normal 'edit' dialogs.
You can then submit the revision in the same manner as you would submit a new element. A subsequent library search will reveal that the element's revision number has been incremented. Note that all previous revisions of the element have been preserved.
Elements can have many revisions and only the latest revision can be edited. If you have imported an older revision, or if a revision has become out of date, simply delete the element and import the latest version. The library search dialog will only show the latest revision of an element by default, so this should not normally be an issue (see 'Updating Elements' for more detailed information).
You will notice that editing an entry will also mark a parent entry and/or document as being edited. Note that this is not the case with validation rules, when they are edited any entries using that rule will not automatically be updated instead they will continue to use the previous revision of the validation rule. To update the entry you will need to add the new validation rule once it has been approved.
Every time an element is saved to the library a new revision is created. Each revision records the state of the element at a particular point in time. All revisions to an element are stored. This means that elements you have imported locally may become out of date as they are edited by other people and new revisions are created. To keep you informed of any changes, each time you login or use the 'Check for Updates' function in the library or study menu, the library is checked for any updates to your locally held elements.
If any updates are found, a dialog window will appear asking if you would like to replace your elements with the latest revision from the library. Pressing 'Update' will update those elements you select. Selecting 'Ignore' will make no changes to the elements, but be aware that you will no longer be able to submit changes to those elements to the library. If you opt to ignore any changes, you will not be prompted about updates for those elements again in future.
When elements are first submitted to the library, or if they are saved back after being edited at any point, they have a status of 'pending'. This means that they cannot be added to another element, for example a pending entry cannot be added to a new document and a pending validation rule cannot be added to an entry. Pending elements also cannot be added to a study. Elements must be approved by a data curator first.
Approving elements is done in a similar way to the submission of elements. documents can be approved by right-clicking on the document or the library view icon and selecting the approve menu option. Documents can then be selected and approved. Entries cannot be approved individually.
Approval of validation rules can be done by selecting 'Library' -> 'View/Approve Validation Rules'. In the dialog window that appears, highlight a validation rule and click the 'Test & Approve' button. A validation rule can only be approved once all tests have been run successfully.
The icons in the left-hand tree used in the library view look slightly different to the icons used when creating studies. This is a quick explanation of those icons.
New
elements: The element has been newly created and is
eligible for inclusion in the library.
Library
element: The element has been imported from the library
and has no local edits.
Edited library
element: The element has been imported from the library
and has been edited locally.
The element properties dialog for each element from the library has an extra 'Library Info' section. This displays some additional information held by the library about the element. Each field in this section is explained in detail below.
Every element is uniquely identified by an identifier. Each new version of an element will have a slightly different identifier.
The identifier reflects the authority the element belongs to, the element type and its revision number.
The date the element was last modified within the library. This can be the date of creation, the date of approval, or date of the last edit submitted to the library.
The authority specifies the 'owner' of this resource. The owner will be one of a few organisations. For example, the prepopulated library comprises elements with the 'org.openCDMS' authority. As additional organisations begin to add elements to the library, other authority identifiers will be added for use.
This is added by openCDMS Create to display the local status or to indicate whether any local changes have been made to the element.
The different messages that may appear, along with a short explanation, are as follows:
"This element has been edited": The element has been checked out from the library and has local changes.
"This element can be added to the library": The element is not from the library but is eligible for submission.
"You do not have permission to edit this element": The element has been checked out of the library but cannot be edited because the current user has insufficient security privileges.
"This element is out of date and cannot be edited": The element has been checked out of the library but cannot be edited because it is not the most recent version of the element. Only the newest version of an element can be edited.
"This element has been marked as not editable": The element has been checked out of the library but cannot be edited. This is normally because the current user is has insufficient security privileges to be able to edit elements or because the element has been checked out already.