Overview

ClinSpark supports customer-provided dynamic logic to perform calculations and validations at the time of data collection. Methods support setting itemData values dynamically based on arbitrary logic and subject data. Edit Checks support dynamic validation of individual itemData values.

The functionality is extremely powerful. It also requires a certain degree of technical skill in Javascript, and an understanding of the context within ClinSpark that this logic executes.

CDISC Standard Background

Much of the CDISC ODM defines a schema for structuring data, and this is of course the foundation for ClinSpark’s data and object model. In addition to this static data structure guidance, the 1.3.0 CDISC ODM specification also defines a number of optional elements which support specifying dynamic behaviors for the model. This addition supports powerful use cases beyond what is possible with purely static data structure definitions. The ODM specification and it identifies 3 types that may be supported:

The ODM specification does not define how to implement these behaviors. It defines data fields called Formal Expressions to hold computer code and specifies inputs and outputs. But it does not require or even suggest an implementation model. It is up to the implementation to define how this Formal Expression instruction gets executed to perform the desired operation.

In light of this, ClinSpark has implemented the MethodDef and RangeCheck to leverage Formal Expressions written in Javascript. This Javascript code has access at execution time to the ItemData and its FormData context in the form of a JSON object. And this execution occurs on the server prior to persisting the data.

Methods vs Edit Checks

Methods are top-level CRF Design elements which can be attached to zero to many items, and the value returned by a Method is set as the value of the attached ItemData. Edit Checks are essentially validation scripts, and the return value can determine whether an ItemData can be Complete or nonconformant. Both Methods and Edit Checks execute once each time data is collected.

Formal Expressions are Javascript

ClinSpark supports “Formal Expressions” through Javascript. This is the Javascript code which gets executed to accomplish the task. It is the contents of a method, which makes some calculation, performs whatever logic is required to implement either the MethodDef or the RangeCheck.

Here’s an example of a method in ClinSpark which calculates BMI. It is designed to be associated with a Item who has other Items named Height and Weight. It retrieves these values from JSON passed to the method, performs the calculation, then returns a JSON response which includes the units.

Note that the Context value in the ClinSpark implementation is used for reference only, it does not impact the execution of the expression in any way.

The return requirements for a Method are a value if the function does not need units, or a JSON object as shown above if units must be specified.

Formal Expression Dev Tooling in ClinSpark

To support self-serve formal expression development and testing by customers, an embedded editor and test execution harness exists within ClinSpark. Here is where it can be accessed:

Here is an overview of the editor and testing harness:

Obtaining ItemData IDs for testing execution

Expressions are run against actual itemData. The test harness requires as an input the database ID of a specific itemData of the user’s choice.

The first step in testing a method is to ensure that there is some collected itemData to test against. Once this is done, follow this walkthrough to see how to obtain the desired ID.

Implicit Methods

As part of ClinSpark’s configuration, commonly useful utility methods are available to your code at runtime. These will be visible to your code at execution time and you can call them directly as needed. These methods assist in finding a certain item from a form for instance, ClinSpark-specific date utilities, etc. #5 from above will open a page showing all available methods.

Note that a useful technique when troubleshooting these methods is to copy a required function into your editor and add logger statements to help understand what is happening. For instance, you could see which itemGroups are inspected by adding the below logger statement to the standard method, assuming you have copied it into your editor.

function findFirstItemByName(formJson, itemName, sasFieldName, itemGroupRepeatKey) {
    var itemGroups = formJson.form.itemGroups;
    if (itemGroups && itemGroups.length) {
        for (var i = 0; i < itemGroups.length; i++) {
            var itemGroup = itemGroups[i];
            logger('inspecting itemGroup.name'+itemGroup.name);

Implicit Data

Two JSON objects are available to each expression execution, itemJson and formJson. The itemJson contains all of the data and metadata pertaining to the itemData which the expression is attached to. The formData is the complete formData graph, including all contained itemGroupData and itemData as wll as context info such as data about the subject/volunteer, cohort, study event etc.

You can use the logger to see the contents of these objects like this:

The execution window output now displays the JSON object.

From there you can format it using the tool of your choice to see the output you’re looking for. A Google search for “prettify JSON” will help locate free online tools; the Foundry Health team uses VS Code to do this.

{
    "item": {
        "name": "VS_Significance",
        "dataType": "string",
        "dataCollectionStatus": "Unsaved",
        "sasFieldName": "VSCLSIG",
        "codeListItems": [
            {
                "codedValue": "CS",
                "decode": "Clinically Significant"
            },
            {
                "codedValue": "NCS",
                "decode": "Not Clinically Significant"
            }
        ],
        "measurementUnits": [],
        "measurementUnit": null,
        "value": null,
        "outOfRange": false,
        "nonconformantMessage": null,
        "length": null,
        "significantDigits": null,
        "canceled": false
    }
}

formJson

The formJson object contains the complete formData along with all contained itemGroupData and their child itemData.

In addition, quite a bit of context metadata can be found within the formJson object:

"form": {
    "name": "Demographics",
    "studyEventName": "Day -28 to Day -2",
    "cohort": {
        "id": 88,
        "name": "12Nov2020",
        "epoch": {
            "id": 80,
            "name": "Screening"
        }
    },
    "timepoint": null,
    "canceled": false,
    "dataCollectionStatus": "Complete"

Here you will also find metadata about the subject/volunteer

"subject": {
    "id": 165,
    "locked": false,
    "screeningNumber": "S440113001",
    "leadInNumber": "L0001",
    "randomizationNumber": "1302",
    "subjectStudyStatus": "Active",
    "subjectEligibilityType": "Unspecified",
    "volunteer": {
        "id": 135,
        "initials": "M-M",
        "age": 30,
        "sexMale": true,
        "dateOfBirth": "1990-XX-05"
    }
}

All of this data can be directly accessed from the expression.

findFormData - looking up previous formData

Sometimes you will need to lookup up other collected data for a subject. For instance this might allow a comparison of a value to a baseline, or retrieve other data imported from a volunteer record demographic form.

To see an example of using this method, search for the Triplicate Reading Average example in the Method library. This method retrieves 3 previously collected ECG readings and then produces an average.

findFormData supports querying for previously collected formData of this same subject only.

Guidelines and Suggestions

Define variables up top to support reusability across studies. See the examples in the Method Library section of this help site.

Errors/warnings in the Formal Expressions syntax checker

The syntax checker by default validates code as “strict mode” JavaScript. If the JavaScript code is not marked 'use strict'  at the start of the file, you may get an error saying:
"Too many errors. (nn% Scanned)"

There are two ways to fix this.

1, Tell the syntax checker you are not using strict mode, paste this at the first line:
/* jshint strict: false */

2, If you want to write JavaScript in strict mode, and get strict mode syntax checking, paste this in the first two lines:
/* globals itemJson, formJson, findFormData, logger, customErrorMessage, findCompletedFormData, findFormData, getItemDataContext */
'use strict';

If you are using other implicit data/methods not included here and get “undefined variable” errors in those lines, add those variables/functions to the list of “globals”.

The list is needed because the editor would flag our implicit methods and implicit data as undefined variables.