Overview¶

There are two basic modes in which RDRF is intended to be used: Design mode (for creating new registries) and User Mode (for adding/editing and viewing patient data in a registry that has been created).

Only administrators can add new registries, forms, sections or data elements.

Important Point: Once data elements and sections are created they can be used by more than one registry. But altering a data element or section that is in use will immediately affect any registries which use it.

Additionally, a public interface is provided when a registry form is nominated to be a questionnaire. See questionnaires.

Roles¶

Each workflow in RDRF is intended to be performed by a user with a distinct role.

Admin¶

• Can do anything
• Create and modify registry definitions
• Import and Export registries
• Manage user permissions

Curators¶

Manage membership of patients in working groups within a registry

Clinicians¶

Enter and view data on patients in a working group within a registry

Design Mode Workflow¶

Modelling¶

1. Do this first on pen and paper!
2. Gather requirements of the data fields ( “DEs” ) required
3. For each data field required, decide its datatype. If a field is logically a range, work out the allowed permitted values. Depending on the datatype, decide any validation rules for a numeric or float data type (max and/or min), and for a string data type, the maximum length or pattern. Decide if any Derived Data Elements (calculated data type) are required.
4. Split them into logical groups (sections). Decide whether a section might be multiple
5. Portion related sections into forms
6. If a questionnaire is required for the registry, nominate a single form as a questionnaire

Creating a Registry¶

Assuming all Data Elements (DEs) have already been created

1. Admin logs in and navigates to “Registries” from “Settings”
2. Admin clicks on green “Add” button
3. Admin fills in Name, code and description of registry (code must be unique and not contain spaces)
4. Admin pastes a html splash screen into the Splash screen field (this will be linked to on the main page)
5. Admin navigates to “Registry Forms” from “Settings” and for each desired form in the registry, clicks the green “Add” button.
6. Admin Selects the registry just created from the drop down list
7. Admin enters a name into the name field (this name will appear on the form, eg “Physical Info”)
8. Admin enters a comma-separated list of form section codes (E.g. “FHPhysicalSection,FHPersonalitySection,FHAmbulatorySection” (Note: The codes should be unique and have no spaces - no quotes! - prefixing with registry code is conventional but advised). If the form is intended to be a public questionnaire form, check the questionnaire checkbox
9. Save the form definition
10. For each section referred to in the comma separated list, add a section object by navigating to “Sections” from “Settings”
11. Click the green “Add” button and enter the section code (used in the form definition)
12. Enter a display name for the section (this will appear on the form above the fields defined for the section)
13. Enter the DE codes of any fields required in the elements list (as a comma-separated list) E.g. “CDEName,CDEAge,CDEHeight” (Note- The system will check whether any entered DE codes exist when the section object is saved - if any DE code cannot be found in the system, the section object will not be created)

User Mode Workflows¶

Adding a user (curator or clinician, or genetic staff)¶

1. Admin logs in
2. Clicks on “Users” from the “Menu” button
3. Clicks Add User button on right
4. Enters Username and password
5. Clicks Next
6. Enters personal information
7. Checks “Staff Status”
8. Control-Clicks Working Group Curators for curator (or Clinical Staff for clinician, or Genetic Staff for genetic staff)
9. Control-clicks the required working groups and registries (if more than one)
10. Clicks save

Adding a Patient to a Registry¶

1. Curator or clinician logs in
2. Click “Add Patient” (or click on the Patients name to edit patient)
3. Control-click on each registry that is listed that you would like the patient to be a member of (NB. If a clinician or curator has access to only one registry, it will already be assigned)

Entering (and viewing existing) Demographic Data for a Patient¶

1. Login as a clinician
2. Click the Patient’s name in the Patient column of the Patient List
3. Edit contact details for the patient
4. Click Save button

Changing Working Group for a Patient¶

1. Login as curator
2. Click the Patient’s name in the Patient column of the Patient List
3. Select required working group (NB. workings group in the dropdown will only be those for which the curator has access)

Entering / editing existing Clinical Data for a Patient¶

1. Login in as a clinician
2. If clinician has access to more than one registry a drop down of registries is shown in the search area, otherwise no registry dropdown will appear and all operations will occur in the one registry
3. Click the “Show Modules” button in the patients list for the required patient - a pop up of available forms will appear (except if there is only one defined clinical data form)
4. Click the desired clinical data entry form
5. The screen will show the required form
6. Edit and click Save

Approving/Rejecting a Questionnaire response¶

1. Curator or clinician logs in.

2. Click “Questionnaire Responses” under “Menu”

3. Click “Review” under “Process Questionnaire” to approve/reject a questionanaire

4. User reviews information in the submitted form and clicks approve (or reject)

   • If approve is clicked, a new patient will be created in the registry and working group indicated in the form
   • If reject is clicked, no patient record will be created

Adding a new working group¶

1. Admin logs in
2. Click on “Working Groups” under the “Menu” button
3. Click the green “Add” button
4. Enter name and save

Changing the Working Groups of a Curator¶

1. As an admin, click on “Users” under the “Menu” button
2. Click on the username of the curator required
3. Control-click (command-click for Mac) on each working group in the combo box required for that user (a curator in 2 working groups will see patients in both groups)
4. Click the Save button

Assigning a curator (or clinician) to a registry¶

1. As an admin, login and then click on “Users” under the “Menu” button
2. Click on the username of the user required
3. Control-click (command-click for Mac) on each registry the user is meant to have access to
4. Click the Save button

Adding Genes¶

1. Admin logs in
2. Click on “Genes” under the “Menu” button
3. Click on “Add” and add details
4. Click Save

Adding Laboratory¶

1. Admin logs in
2. Click on “Laboratories” under “Menu”
3. Click on “Add” and add details
4. Click Save

Admin Page¶

The Admin Page consists of:

Patient List¶

Add or edit patient information (contact details)

Doctors¶

Add or edit Doctors

Reports¶

Access Reports that have been defined with the Explorer tool

Users¶

Add or edit users

Genes¶

Add or edit genes

Laboratories¶

Add or edit laboratories

Registries¶

Add or edit registries

Registry Form¶

Add or edit forms (created forms are accessed under ‘Modules’ in the Patient List)

Sections¶

Add or edit sections (Sctions are compiled into Forms)

Data Elements¶

Add or edit CDEs (CDEs are compiled into sections)

Permissible Value Groups¶

Add or edit PVGs

Permissible Values¶

Add or edit PVs (assigned to a pemritted value group)

Groups¶

Administer available permissions for user groups (working group curators, clinicians, etc)

Importer¶

Import a registry definition (yaml file)

Demographics Fields¶

Configure Demographics fields to be hidden or readonly by registry and group

Working Groups¶

Add or edit working groups (e.g. States, Hospitals, Clinics)

Questionnaire Responses¶

Questionnaire responses are stored here when submitted by a patient, awaiting validation or rejection by an admin or curator

Registry¶

In RDRF, a “registry” is just a named collection of forms. A Registry is created by an admin user by selecting “Registries” from “Settings” and clicking “Add”.

A Registry must have a non-blank name and a code (which should not contain spaces).

Forms¶

A form is a single “screen” of information in RDRF and consists of a group of named Sections. To create a form, select “Registry Form” from “Settings” and clicking “Add”.

Form names should not include spaces (e.g. ClinicalData), however the form name will appear as Clinical Data if captial letters are used for separate words.

A form is defined by the following features:

Registry¶

A link to the Registry that owns the form. A form can only exist in one registry at a time.

Name¶

The display name to use (this will appear in the “Patient Listing” under “Modules”.

Sections¶

The section codes that comprise this form, listed in a comma-separated list.

Is Questionnaire¶

A checkbox to indicate whether this form is exposed as a public questionnaire.

Questionnaire forms are not loaded from the dashboard but access via an autogenerated URL

/<regcode>/questionnaire

An autogenerated approval form (for curators) is created also.

Sections¶

A section is a named group of fields that can be inserted into a Form.

Sections consist of:

Code¶

A section must have a non-blank code (no spaces) which is just a text value. Section codes must be unique. The code of a section is used to refer to it, when used in a Form.

Example: “FHSECTION34” or “SEC001”

Display Name¶

A string which will be displayed on the form to mark the start of the section.

Example: “Physical Characteristics” , “Contact Information”

Elements¶

The DEs codes of any fields comprising that section.

This must be a comma-demlited list of DE codes.

Example: “CDEName, CDEAge”

(This would mean that the section would consist of two data input fields - one defined by the Data Element with code “CDEName” and one defined by the Common Data Element with code “CDEAge”)

NB. Spaces between codes is not significant.

Allow multiple¶

A boolean flag indicating whether multiple entries of this section can added ( or removed ) on the form.

Extra¶

If allow multiple is checked, this causes extra (blank) copies of the initial section to be displayed.

Code¶

A DE must have a globally unique code (e.g. CDEAge, CDEInsulinLevel) which must not contain a space.

A meaningful code prefixed with CDE or the Registry Code is recommended.

Name¶

A non blank “name” must also be entered, which will be used as the label of the component when it appears on the form.

Desc¶

Origin of the field if externally loaded.

Datatype¶

Each cde must have a data type specified by a text descriptor. Currently this descriptor is specified as free text although this may change.

The allowed Datatypes are as follows (NB. These are the literal words to type into the datatype field, except for ComplexField)

• string
• integer
• alphanumeric
• boolean
• float
• range
• calculated
• file
• date
• ComplexField

Pv group¶

IF a range, select the desired permitted value group here.

Allow multiple¶

IF a range, checking this box will allow multple selections to be chosen from the range.

Max length¶

IF a string value, the maximum number of characters allowed.

Max value¶

IF an integer or a float value, the maximum magnitude allowed.

Min value¶

IF an integer or a float value, the minimum magnitude allowed.

Is required¶

A check box indicating whether this field is mandatory (any datatype)

Pattern¶

IF a string value, a regular expression used to indicate admissible values (note these are always case sensitive in the current version).

Widget name¶

The name of a custom widget to visually present the data, or an an alternative widget from the default. IMPORTANT! The custom widget must already be provided in the codebase otherwise an error will occur. If this field is left blank ( the default ), the default widget for the specified datatype will be used, which should be good enough in 99% per cent of cases.

Derived Data Element (DDE)¶

IF a calculated field, a fragment of javascript outlined in Derived Data Elements. Leave blank if not a calculated field.

String Datatype¶

Integer Dataype¶

A whole number. Integer DEs can have a max or min value entered.

Float Datatype¶

Alphanumeric Datatype¶

Boolean Datatype¶

Range Datatype¶

For more sophisticated DEs, a DE can incorporate Permitted Value Groups (PVG).

Calculated (Derived Data Element)¶

var height = parseFloat(context.CDEHeight);
var mass = parseFloat(context.CDEMass);
context.result = mass / ( height * height );

File Datatype¶

Date Datatype¶

ComplexField Datatype¶

Permissible Values¶

A permissible value (PV) is just a single allowed value that comprises part of a value range.

Examples¶

If the associated value range was intended to be a size range then examples might be

• small
• medium
• large

In the GUI, individual permissible values will appear as selectable options in a drop down list.

Permitted Value Group¶

A permitted value group (PVG) is a set of permissible values. A PVG must be defined first, with PVs then defined and assigned to a PVG. PVGS are defined by navigating to “Permissible Value Groups” under “Settings”.

Click “Add” to create a new PVG.

A value group has a code which must be a unique non blank string value.

Once a permitted value group has been created, add permissible values to it.

Examples¶

The decoupling of permitted value groups from cdes that make use of them allows different attributes

(e.g. shoe size , hat size) to share the same value ranges (E.g. small, medium, large) as is done in NINDS http://www.commondataelements.ninds.nih.gov )

Modelling¶

1. Do this first on pen and paper!
2. Gather requirements of the data fields ( “DEs” ) required
3. For each data field required, decide its datatype. If a field is logically a range, work out the allowed permitted values. Depending on the datatype, decide any validation rules for a numeric or float data type (max and/or min), and for a string data type, the maximum length or pattern. Decide if any Derived Data Elements (calculated data type) are required.
4. Split them into logical groups (sections). Decide whether a section might be multiple
5. Portion related sections into forms
6. If a questionnaire is required for the registry, nominate a single form as a questionnaire

Creation¶

1. Login as an admin and navigate to “Registries” via the “Settings” button
2. Create a registry object and give it a name and code
3. Create any permitted value groups required ( adding

any permitted values to the range.

4. Create DEs (one per data field ) - OR note an existing DE that does the job (IMPORTANT deleting a DE

may affect other registries which use this cde - in the current version there are no safeguards to prevent a used DE from being deleted. Proceed with caution!)

5. Create the section objects and enter the cde codes required into the elements field

NB. This MUST be a comma-delimited list (E,g “CDEName, CDEAge” - no quotes)

6. Create forms and link them to the registry
7. Add section codes to the sections field

That’s it as far as registry definition goes. The RDRF database now contains the definition of the registry. It is already usable by end users without any re-start - the defined forms are created entirely dynamically.

Registry Use¶

• To begin using the registry, login as a curator and assign patients to the registry.
• Patients can be added by navigating to the “Patient List” from the “Menu” button. Forms are then accessed for each Patient by clicking on “Modules”.

Demo Site¶

• A demo site is up and running at: https://rdrf.ccgapps.com.au/demo/

• Logins Provided (username/password):

  • admin/admin (for definition of new registries)
  • curator/curator (for data entry)
  • clinical/clinical (for data entry on clinical forms)
  • genetic/genetic (for data entry on genetic forms)

• A Demo Contact Registry and Demo Clinical Registry for Myotonic Dystrophy are provided.

Importing¶

Importing a registry definition saved a yaml file. Login as an admin and navigate to “Importer” under “Settings”, and select a previously exported registry yaml file from your file system.

Export¶

Exporting of a defined registry to a yaml file. Login as an admin and navigate to the registry required (“Registries” under “Settings”). Select the export custom action and run it.

Updating CDE Data¶

Using curl: Posting a file:

curl -i -F value=@LPK.filvar.vcf <rdrf url>/<regcode>/patients/<patientid>/<formname>/<sectioncode>/<cdecode>

NB. The CDE with code <cdecode> must have datatype ‘file’

Updating a non-file value

curl -i -H “Accept: application/json” -X POST -d <value> <rdrf url>/<regcode>/patients/<patientid>/<formname>/<sectioncode>/<cdecode>

NB. This only works at the CDE level at the moment.

Examples¶

curl –request GET <rdrf url>/fh/patients/1/fh/fhBMI/CDEHeight

retrieves json of height ( only)

curl –request GET <rdrf url>/fh/patients/1/fh/fhBMI

retrieves json of fhBMI section dictionary( code ==> value mapping )

curl –request GET <rdrf url>/fh/patients/1/fh

retrieves json of fh form ( JSON dictionary of section dictionaries )

curl –request GET <rdrf url>/fh/patients/1

retrieves JSON of all forms in fh registry for patient 1.

Setting up your development environment¶

After downloading the source and decompressing:

1. first install docker ( https://www.docker.com/ ) and python tools pip and virtualenv.
2. cd in to the source directory
3. issue the command: ./develop.sh start ( this will install a tool which creates the application containers and wires them up.)
4. open a web browser at localhost:8000 and login with the (dev only!) admin account (password admin)
5. look at How to create a registry

usage¶

Usage ./develop.sh (pythonlint|jslint|start|rpmbuild|rpm_publish|unit_tests|selenium|lettuce|ci_staging)

start¶

./develop.sh start

This brings up the dev container - login at localhost:8000

Changes to the code are automatically picked up. Data and logs in ./data/dev

unit tests¶

./develop.sh unit_tests

selenium tests¶

./develop.sh selenium

Starting the development container¶

fig up

Running unit tests¶

fig -f fig-test.yml up

Running selenium tests¶

fig -f fig-selenium.yml up