Technical specifications

Usage

When Rodano is started it deserializes the JSON configuration file into a graph of objects. The configuration object graph is static and global.

Configuration entities

Description

Scope is the main data container object of the application. A scope’s configuration is defined by its scope model. Through the use of a scope model, a scope can represent any study entity: patient, centre, country, study, sub-study, etc. Data that is directly related to the scope entity can be represented using the one or more datasets attached directly to the scope (e.g. patient record, medical history, family history, etc.). Events can also be attached to scope to represent specific events through time (e.g.medical visit, termination event, etc.).

Scopes are arranged in a tree-like hierarchy with the scope representing the study usually acting as the root node of the tree, this scope is referred to as the root scope. All the scopes must have at least one parent relation except for the root scope.

Virtual scope

A virtual scope is used to represent non-physical assembly of other scopes. For example, it can be used to assemble a group of scopes that adhere to certain criteria. Note that virtual scopes can only be created by providing a scope model that is marked as virtual.

Scope relations

Scope relations are the entities that define the edges between the scopes in the scope hierarchy tree. They define the relations between individual scopes. All scope relations are created with a start date and can feature an optional end date. The relation end date thus defines the end of the relation between the two referenced scopes. A scope’s model can define the maximum number of allowed child scopes.

User rights on scopes

When a user is granted the rights to manage a scope, he can see all current descendant scopes of this scope. This means that he has rights to see descendant scopes that have been added in the scope before he has been given the right on the scope. The user will also have right to see any future descendant scopes that could be added afterwards.

However, if a descendant scope is transferred to another scope, the user will be able to see only data of events that happened before the transfer. All future collected data will be hidden from the user. This means that they won’t be able to view next events nor the eventual data modifications. Analogously, if a descendant scope is transferred to his scope he will see all pre-existing data in read only mode and won’t be able to add events before the transfer date.

Note that in the case of a virtual scope, the user that has rights on the virtual scope can see all the past data of the descendant scopes. To illustrate this concept, suppose that a user has rights on centre x which has a patient that just got transferred from centre y to centre x. At this point the user can only see the data that happened after the transfer. But if the user is also granted rights on a virtual scope of which the patient scope is a descendant of, then the user will be able to see all the patient’s data before the transfer. In this way the virtual scope "overrides" the usual rights on scopes.

Creation

A scope can be created at any time providing the following parameters:

1. Scope model.
2. Parent scope.

Deletion

When a scope is deleted by a user, its deleted flag is set to true and all the scope deletion rules are executed on the scope. The deleted scope can be restored by a user with the appropriate rights. Note that if a parent scope is deleted, it and its descendants will only be visible to authorized users, even though the descendant scopes are not deleted.

Restoration

Any deleted scope can be restored by an authorized user. When a scope is restored by a user:

1. The scope’s deleted flag is set to false.
2. All the fields found in the scope’s datasets, the datasets of its events and recursively in all its descendant scopes are validated.
3. All the scope restoration rules are executed.

Description

An event is a representation of something (i.e. a patient visit, an intervention, a sample collection, etc.) that has already happened or will happen in the future. An event is always attached to a scope and can contain one or more datasets. Event’s model is defined by an event model in the configuration. An event has an expected date, a start date and an optional end date.

Creation

If the event’s event model is mandatory, it is created automatically when it’s associated scope is created. Otherwise, the event can be created manually by a user, if the configuration allows it. An event can be created if all the following statements are true:

1. The associated scope is not locked.
2. The event’s model is linked to the scope’s model in the configuration.
3. No blocking event is present on the scope.
4. The maximum number of allowed events has not been reached, if a maximum is defined in the configuration.
5. There is no rule that forbids the addition of the event.

Description

Dataset is a container for one or more fields. A dataset represents a collection of one or more fields and can thus serve to regroup fields with the same theme (e.g. all the fields relating to the patient information could be regrouped in a single "patient information" dataset). A dataset can be attached directly to a scope or to a event. A dataset can be either of single or multiple type. Dataset’s model is defined by a dataset model in the configuration.

Creation

Datasets of type single are created whenever a scope or an event is created and has dataset models attached to it in the configuration. Dataset of type multiple can be created manually by an authorized user. In order to create a dataset, its dataset model has to be present in the scope’s or event’s model. When a dataset is created, all the fields associated with it are created.

Deletion

Only a dataset of type multiple can be manually deleted by an authorized user. When a dataset is deleted, all the dataset removal rules are executed.

Restoration

A deleted dataset can be restored by an authorized user. When a dataset is restored, all the dataset’s fields are validated and the dataset restoration rules are executed.

Description

A form object serves as a metaphor for a paper medical form in a clinical study. A form can contain zero or more fields from one or more datasets. Note that a form does not need to contain all the fields of a particular dataset, it is a visual grouping of fields. For example, we can have a form that contains the address of the patient and a form that regroups fields that define other information pertinent to the patient while all these fields belong to one single dataset that regroups patient information. The form’s model, including its visual layout, is defined by the form model in the configuration. A form can have zero or more workflow statuses attached to it. A form can be attached to an event or directly to a scope.

Creation

All forms associated with a scope or an event in the configuration are automatically created upon their creation. All the workflows attached to the form in the configuration are initialized upon form creation.

Deletion

1. The form’s deleted value is set to true.
2. The mandatory workflows of the form and its fields are reset.
3. The non-mandatory workflows of the form and its fields are deleted.
4. Datasets of type multiple that are not directly attached to a scope or an event are deleted.
5. Fields that are not on scope are reset.

Restoration

A form can be restored through a form restore action. Note that this action only restores the form itself and it does not affect any fields or datasets associated with the form.

Description

A field represents a singular value in a dataset. They are used for value transmission (for example, when a user sends new data to the system), field validation and value storage. A field contains a unique identifier, a reference to its dataset, the ID of the field model and a value. A field can not be deleted nor restored. Field’s model is defined by a field model in the configuration.

Field value

A field’s value represents the value that is actually stored in the database for a given field. A field can have three possible values associated with it:

1. A null value.
2. A blank value, which is either an empty string or whitespace.
3. A string value, which is stored as a string of characters in the database.

Interpreted value

The value that is actually returned to the user through the API is the interpreted value of the field. The interpreted value calculation abides by the following pattern:

1. If the user that requests the field’s value no longer has rights to the scope to which the field belongs, the value returned is the last value to which the user had rights before rights removal.
2. If the field value is null, the field model is not a plugin and the model has a formula defined on it, then the value is calculated using the provided formula.
3. Otherwise, the actual field value is returned.

It should be noted that the interpreted value is calculated on the fly and does not necessarily reflect the field value actually stored in the database.

File field

Fields with the model of type FILE are a special case among the fields. In order to identify possible file changes and to integrate it with the string only value of the field, the field value in this case consists of the file name concatenated with the checksum of the actual file that has been uploaded. More information on the file field processing can be found in section 16.3.1.

Creation

Whenever a new dataset is created, a field is automatically created for every field model that is associated with the dataset’s model in the configuration.

Reset

A field can be reset. This means that its value is set to null and the value update rules are executed. When a field is reset, all the mandatory workflow statuses associated with it are reset to their initial state and all the non-mandatory workflow statuses are deleted.

Description

A workflow status defines the status of a workflow on an object. The model of the workflow status is defined by the workflow in the configuration. A workflow status can be attached to any workflowable object:

• Scope
• Event
• Form
• Field

Creation

When a workflow status is created, it is initialized with a reference to an object, an ID of a workflow in the configuration and an initial status as defined in the workflow configuration. Workflow status can be created in several ways:

1. When a workflowable object is created, and it has workflows associated with its creation in the configuration.
2. Through a manual user operation.
3. Through the field validation mechanism.

Status modification

Whenever the status of an existing workflow status is modified, the status ID is changed and the change is audit trailed. Whenever a status is modified, the status modification rules are executed. Workflow status can be modified through:

1. A manual user call using a workflow action.
2. The field validation mechanism.

Note that the status can not be modified if the associated workflowable object is locked.

Deletion

Audit action

An audit action is a construct that allows grouping of multiple audit trails under a single action triggered by a user or a robot. For example, suppose some user updates a field in a dataset which in turn triggers a rule that updates the value of another field. All the audit trails resulting from the user action (even changes that are executed by the system) will be associated with a single audit action. We can thus see which user interaction triggered specific changes in the database.

Note that the audit actions are created and recorded in the database even when no modification is made by the user on the database entities. This is a current limitation that will be addressed in a future version.

Content and creation

An audit action is created whenever a data-modifying API action (identified by HTTP methods PUT, POST and DELETE) is performed by a user or whenever the system starts a pre-programmed action (i.e. a CRON task). An audit action contains the following properties:

• Date of the action.
• PK of the user or the robot performing the action. Empty if it is the system that starts the action.
• Context for the action, which is the endpoint of the API method activated by the user.

Creation

• Name of the user.
• Unique email.
• Whether the user is externally manged or not.
• At least one user role.

When a user is created, an email with a unique link is sent to the user’s email inviting them to enable the role to which they were invited. When the user lands on the activation page, they need to accept the displayed privacy policies, if any are attached to the role, and select a password for their account. As soon as a valid password is chosen, the user’s account is activated and the user’s roles status change from PENDING to ENABLED. And thus the user account creation is finalized.

Identification

A user is identified by a unique email which serves as the user’s ID and a secret password (as described in 11.10 (d) of 21 CFR Part 11 and tested in USER_ID).

Authentication

A user can log into the system by using their verified email and their secret password. All successful and unsuccessful login attempts are audit trailed (as described in 11.10 (d) of 21 CFR Part 11 and tested in USER_LOGIN_TRAIL).

Email verification

Anytime a user changes their email it needs to be verified in order for the user to be able to access the system with the new email. Whenever a user changes his email, the following happens:

1. An email with a verification link is sent to the newly entered email address.
2. The user has 7 days to activate his new email by using the verification link.
3. If the user uses the link, the new email becomes the user’s current email.
4. If the user does not use the link in the allotted time, the link expires and the user’s email does not change.

When a user is created, the email is implicitly verified upon the first role activation. The following diagrams describes all the flows of the email verification.

Password management

Possible states

1. PENDING: the role has been created, but has not yet been accepted by the user.
2. ENABLED: the role is enabled after the user has accepted the role and its privacy policies.
3. DISABLED: the role has been disabled by an authorized user.

Creating a role

A role can be created on any existing user. When a role is created, the role creation rules are triggered and the role’s status is set to PENDING. Only two things are needed for role creation:

1. A scope reference, to which the role will be attached.
2. A profile, which defines the role’s features.

Enabling a role

If a user has pending roles associated with them, they can enable the role themselves directly, if no privacy policies are attached to the role’s profile. If privacy policies are present, the user first needs to accept them in order to enabled the role. If the user rejects the privacy policies, the role will become DISABLED. Furthermore any authorized user can enbale a pending role on another user, as long as no privacy policies are attached to the role’s profile.

Disabling a role

Any enabled role can be disabled by a user with sufficient rights. Note that if a user has only one role enabled, it can not be disabled. If a user possessing a single enabled role must be removed from the system, it is preferable to delete the user.

Re-enabling a role

Field processing

When the system receives the newly submitted fields, it needs to identify which fields need to be processed and which can be reset or discarded. To do this, the following criteria are used:

• Is the field visible on the page? Some fields are displayed only if some other field holds a particular value or certain conditions are met. If the field is not visible, it is reset.
• Is the field is dynamic? If the field is dynamic then its value will be set by the system and not by the user, however, its value might need to be processed for validation, or to trigger a rule.
• Is the field read-only? Some fields are not editable by users and might be computed by other fields. However, such fields need to be processed, so the validation can occur and rules can be triggered.
• Does the field have an edit check? If an edit check is attached to a field, the system must validate the field if some conditions are met.

The field filtering flow is described in the following diagram.

Validation

After the fields are submitted and filtered, the field validation phase starts. The field validation applies to all fields whose models have validators attached to them. The field validation can be broken down into three phases:

1. Phase I: Blocking validators are applied.
2. Phase II: Required field validators are applied.
3. Phase III: All other validators are applied.

The whole field validation procedure is described in detail in the following diagram.

Blocking validators

Some fields have blocking validators attached to them. If at least one the blocking validator’s criteria are not met, the system aborts the whole field update process and sends the failed blocking validators’ descriptions to the user. The following diagram describes the process.

Required field validation

Some field models can be marked as “required“ in the study configuration. The fields that are associated with those models are validated in the required field phase of the field validation. For each field that has a required validator, the following occurs:

1. If the field is valid (i.e. not empty), the validation proceeds on to the next field and:
   1. If the field has workflow attached to it, then the workflow is set to an invalid state.
2. If the is not valid (i.e. empty), the validation proceeds on to the next field and:
   1. If the field has no workflow attached to it, then initialize the workflow specified in the configuration and set it to the invalid state.
   2. If the field already has a workflow attached to it, then leave the workflow as-is.

This validation phase is described in the following diagram.

Field validation

Any field model can have one or more validators attached to it in the study configuration. The fields associated with those models are validated in this phase of the field validation.

For each validator attached to the field:

1. If the value of the field is valid:
   1. If it is in a valid state, then leave the workflow as-is.
   2. If it is in an invalid state, then set the workflow to the valid state.
2. If the value of the field is not valid:
   1. If the field value or its dependencies have changed, set the workflow to valid state and initialize a new required workflow in an invalid state.
   2. Otherwise, if the required workflow that is already present should be set to an invalid state.

The whole process is described in the following diagram.

Updating values

The value update process works as follows:

1. The submitted field value is compared to the same field value present in the database
   1. If the value is the same, the field value is not updated.
   2. If the value is different, then the field value is updated to the newly submitted value.
2. All updated fields are saved and audit trailed in a single transaction in the database.

Dispatch queue

The system implements a dispatch queue for emails. When an email is created, it is added to the dispatch queue. The dispatch queue sends batches of emails periodically (batch size and the dispatch period is adjustable in the configuration) and sends the emails in FIFO order. If an email is cancelled before it could be sent, it is removed from the dispatch queue.

Lifecycle

These are the possible states of an email:

1. Pending: The email has been created and added to the email queue.
2. Sent: The email has been sent.
3. Simulated: This status is used for email testing and does not actually send out the email.
4. Cancelled: email dispatch has been manually cancelled.
5. Failed: email dispatch has failed.

When an email is created, it is added to the email dispatch queue. The following diagram shows the lifecycle of an email.

Workflow summaries

A workflow summary is a tabular report that aggregates the data of one workflow by scope and state. It shows the number (absolute and percentage of the total) of workflows that are in each state of the workflow, for all scopes of the study.

Export

It is possible to export the workflows statuses that have been used to build the report. The export is a CSV file that lists all workflow statuses. It contains the following columns:

The first 2 columns are repeated as many times as the depth of the scope tree. For example, in studies where the scope model tree consists of Study, Country, Center and Patient, the columns will be: Study ID, Study, Country ID, Country, Center ID, Center, Patient ID, Patient.

Deleted workflow statuses and workflow statuses attached to deleted entities are included only for users having the feature MANAGE_DELETED_DATA.

Audit trail export

For workflow summaries that display non aggregating workflows, it is also possible to download the history of the workflow statuses that have been used to build the report. The export is a CSV file that contains the same workflow statuses as the regular export, and, for each of the workflow status, alls states it went through. It contains the same columns as the regular export (except columns "Current workflow status" and "Current workflow status date") and contain the following additional columns:

Description

A resource is an object containing information that can be displayed to the users. A resource can contain text (useful for spreading news to users) and it can contain attachments (useful for sharing documents to other users). A resource must be attached to a scope in order to define who can access it.

Creation

A resource can be created by an authorized user and requires the following parameters:

1. Title
2. Category ID
3. Scope ID
4. Is the resource public or not

Deletion

Any resource can be deleted anytime by an authorized user.

Restoration

Any deleted resource can be restored by an authorized user.

File attachment

Description

A widget is a pre-configured component that displays information relevant to the study. They provide overviews of information relevant to the ongoing study. The available widgets are:

• Welcome text - displays the welcome text defined in the configuration.
• General information - displays general information relevant to the study. This widget uses custom study code in order to extract the relevant data.
• Resources - displays the resources available to the user. Uses the configured resource category to filter the displayed resources.
• Chart - displays the pre-configured chart based on the study data.
• Workflow - displays the workflow-related information.