...

Formal Expression Dev Tooling in ClinSpark

Note that this tooling was introduced in ClinSpark 1.5.2.

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

...

...

Here is an overview of the editor and testing harness:

...

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 internal team uses VS Code to do this.

{
    "item": {
        "nameid": "VS_Significance"136424,         "dataType": "string",         "dataCollectionStatus": "Unsaved",  // Unique ID for the item data
"sasFieldName": "VSCLSIG",         "codeListItemsname": ["AE_START_DATE",           // Name {of the item (e.g., 'Adverse Event Start Date')
         "codedValuedataType": "CSincompleteDatetime",  // Data type (e.g., 'string', 'date', 'incompleteDatetime')
        "decodedataCollectionStatus": "Clinically Significant"
    Complete",// Status: 'Complete', 'In Progress', etc.
       }, "sasFieldName": "AESTDTC",         // Corresponding {SAS field      name
         "codedValuevalue": "NCS"2024-08- T13:39: ",      // Captured value (can be incomplete)
        "decodecodeListItems": "Not[ Clinically Significant"             }  // Optional: List of allowed coded values
],         "measurementUnits": [],  {
      "measurementUnit": null,         "valuecodedValue": null"CS",         "outOfRange": false,// Coded value
                "nonconformantMessagedecode": null,
   "Clinically Significant" // Meaning of coded value
     "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": {           "namecodedValue": "DemographicsNCS",
    "studyEventName": "Day -28 to   Day -2",     "cohortdecode": { "Not Clinically Significant"
          "id": 88, }
       "name": "12Nov2020" ],
        "epochmeasurementUnits": {[],        // Array of applicable measurement "id": 80,units
        "measurementUnit": null,    "name": "Screening"  // Specific measurement unit    }
(if used)
   },     "timepointoutOfRange": nulltrue,     "canceled": false,     "dataCollectionStatus": "Complete"

Here you will also find metadata about the subject/volunteer

"subject": {
    "id": 165,
    "locked": false, // Whether the value is out of an acceptable range
        "screeningNumbernonconformantMessage": "S440113001"null,  // Message if "leadInNumber": "L0001",
 the item is nonconformant
  "randomizationNumber": "1302",     "subjectStudyStatuslength": "Active"null,     "subjectEligibilityType": "Unspecified",     "volunteer": {    // Optional: Length constraint for "id": 135,the value
        "initialssignificantDigits": "M-M"null,     // Optional: Number  "age": 30,of significant digits allowed
        "sexMalecanceled": false true,          "dateOfBirth": "1990-XX-05"   // Whether this item has been canceled
    }
}

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

...

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": "Form Name",                // Name of the form (e.g., 'Demographics')
        "studyEventName": "Event Name",      // Name of the study event
        "cohort": {                         // Cohort-related metadata
            "id": 88,
            "name": "Cohort Name",
            "epoch": {
                "id": 80,
                "name": "Screening"         // Epoch or phase name
            }
        },
        "timepoint": null,                   // Timepoint (if applicable)
        "canceled": false,                   // Whether the form is canceled
        "dataCollectionStatus": "Complete",  // Status: Complete, In Progress, etc.
        "subject": {                         // Information about the subject/volunteer
            "id": 165,
            "screeningNumber": "S440113001", // Subject screening number
            "randomizationNumber": "1302",   // Randomization number
            "subjectStudyStatus": "Active",  // Status of subject in study
            "volunteer": {                   // Volunteer details
                "id": 135,
                "initials": "M-M",
                "age": 30,
                "sexMale": true,
                "dateOfBirth": "1990-XX-05" // Supports incomplete dates
            }
        },
        "itemGroups": [                     // Array of item groups within the form
            {
                "itemGroupRepeatKey": 1,    // Identifier for repeated groups
                "items": [                  // Array of individual items
                    {
                        "name": "Item Name",   // Name of the item
                        "dataType": "string",  // Data type (e.g., string, date, etc.)
                        "value": "some value", // Collected data value
                        "canceled": false,     // Whether the item is canceled
                        "sasFieldName": "SAS_NAME", // SAS field name mapping
                        "codeListItems": []    // Optional: Code list if applicable
                    }
                ]
            }
        ]
    }
}

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.