glean-js

glean.js

The glean.js module is a fully in-browser platform for visualising and executing GLEAN workflows.

How to use

1. Manually author a GLEAN workflow. You can base yourself on the exemplar workflow. In general, your workflow should use the GLEAN constructs defined in the glean ontology. You will also need to define HL7 FHIR ActivityDefinitions with data constraints on allowed user input data - these are also included in the exemplar.

2. Convert your GLEAN workflow into an executable format. For this purpose, use the genjs tool that was compiled into a jar file (genjs.jar). For instance, to convert the exemplar workflow:

java -jar genjs.jar -folder [your local path/]glean/glean-js/wf/test -cig example -ns http://example.org/

Where:

• folder is a directory with a cig/ subfolder keeping all CIG-related artefacts. The tool will generate a tmp/ folder for temporary output and an out/ folder with the final output.
• name is the name of your CIG file (without extension) under the cig/ subfolder ("example" for the exemplar workflow).
• ns is the namespace used to define your GLEAN workflow tasks ("http://example.org/" is the one used in the exemplar workflow).

(You can find the source of genjs under glean-core)

3. Copy and update one of the example tree or form HTML files to respectively get an interactive workflow or a data-oriented form. You will have to replace the FSM constructor with the relative path to your executable workflow file (e.g., "/wf/test/out/example_local.js"), and the RdfInputHandler argument with your CIG namespace (e.g., "http://example.org/").

4. Run a local HTML server to view your HTML file (e.g., python3 -m http.server, pointing your browser to http://localhost:8000).

A bit more detail

Looking at the contents of an example HTML file:

let inputHandler = new RdfInputHandler("http://example.org/");

let source = new FSM("/wf/test/out/example_local.js");
await source.load();

let cig = new VisualCIG({ source: source, input: inputHandler, container: '#main-container' });
cig.show();

The InputHandler will get user input values, i.e., manually entered into the workflow, and provide them to the DataSource for processing. Currently, we implemented an RdfInputHandler that extracts user input as RDF data, which is structured using RDFa annotations from the HTML input forms. These RDFa-annotated HTML input forms are automatically generated in step (2) above - you can find them under the tmp/html folder in your given directory (see here for an example).

The DataSource will subsequently process this input data and update task states accordingly. The FSM data source is a JavaScript engine that implements the Finite State Machine (FSM) execution semantics of GLEAN, as defined here in N3. Essentially, the user input (RDF data) is converted into an set of JavaScript objects; the FSM engine then checks whether this new data requires any tasks to transition to new states, and, if so, updates the workflow state. Alternatively, the DataServer data source allows for communication with a FHIR-compliant web server; any user input is sent to the server, which then calculates new task states and returns them to the data source. To act as a FHIR-compliant web server, you can look into the fhir-server module.

The CIG represents a concrete visualization of a CIG - currently, we support VisualCIG, which shows an interactive visual workflow, and CIGForm, which shows a data-oriented form geared towards quick data entry. The CIG receives task state updates from the DataSource and updates its visualization accordingly.