Premium Feature — Available in the Enterprise Edition. Learn more or contact LabKey.

A metadata file written in JSON is used to configure the fields and categories for abstraction. The file configures the field categories and lists available, as well as what type of values are permitted for each field.

Metadata JSON files may be used to control a variety of implementation specific configurations, such as understanding common fields of a specific type of cancer report or case file. Implementing conditional or branching logic (if this is true, show these extra fields) can also be included using metadata.json files.

Metadata Fields

The metadata JSON file defines fields for abstraction using these properties:

  • field: (Required/String) The field name.
  • datatype: (Required/String) The type of the field.
  • closedClass: (Optional/Boolean) If true, the field is closed (only values on a pulldown menu can be selected). Otherwise and by default, arbitrary values can be entered into the field, whether or not they are on the expected list.
  • diseaseProperties: (Optional/Array of properties) The group of disease diagnoses for which this field is presented to abstractors. For example, if the field is shown for all types of disease, with four options on a dropdown list, the field might look like:
    "diseaseProperties":[
    {"diseaseGroup":["*"],
    "values":["brain","breast","GI","GU"]
    }]
  • multiValue: (Optional/Boolean) If true, the field supports entry of multiple values. Otherwise, and by default, each field accepts a single value.
  • hidden: (Optional/Boolean) If true, the field is hidden in the initial state and only shown if enabled by conditional logic. Otherwise and by default, the field will be shown to the abstractor from the beginning.
  • disabled: (Optional/Boolean) If true, the field is shown, but disabled (grayed-out) in the initial state and only enabled to receive input via use of conditional logic. Otherwise and by default, the field will be enabled from the beginning.
  • listeners: (Optional) See Conditional or Branching Logic below.
  • handlers: (Optional) See Conditional or Branching Logic below.

Basic Example

Download this sample file for a simple example:

Here, a Pathology category is defined, with table and field level groupings, and two tables with simple fields, "ClassifiedDiseaseGroup" and "Field1", a boolean.

{
"pathology": {
"groupings": [
{
"level": "table",
"order": "alpha",
"orientation": "horizontal"
},
{
"level": "field",
"order": "alpha",
"orientation": "horizontal"
}
],
"tables":[
{"table":"EngineReportInfo",
"fields":[
{"field":"ClassifiedDiseaseGroup",
"datatype":"string",
"closedClass":"False",
"diseaseProperties":
[
{"diseaseGroup":["*"],
"values":["disease1","disease2","disease3"]
}
]
}
]
},
{"table":"Table1",
"fields":[
{"field":"Field1",
"datatype":"string",
"closedClass":"True",
"diseaseProperties":
[
{"diseaseGroup":["*"],
"values":["Yes","No"]
}
]
}
]
}
]
}
}

Enable Multiple Values per Field

To allow an abstractor to multiselect values from a pulldown menu, which will be shown in the field value separated by || (double pipes), include the following in the field definition:

“multiValue” : “True”

Conditional or Branching Logic

Conditional or branching logic can be used to control the fields and options presented to annotators. For example, options could vary widely by disease group or whether metastasis is reported. To introduce conditional logic, use listeners and handlers within the metadata JSON file.

To enable or disable the field upon initial opening of the abstraction/annotation screen, use the disabled boolean described above.

Listener Configurations

A listener configuration includes the following properties:

  • field: (Required/String) The name of the field to listen to and respond to changes in.
  • tableName: (Optional) Specifies the table in which the listened-to-field resides. Defaults to the same table as this field definition resides in.
  • recordKey: (Optional)
    • If record key level grouping is configured, specifies the record key of the field to listen on. This can be used in conjunction with tableName to target a very specific field that this field definition needs to respond to.
    • If omitted, this will default to the sub table that this field definition resides on.
    • An optional wildcard value of "ALL" can be specified which will listen to all subtables for the table associated with this field definition.
  • handlers: (Required/Array of handler configurations) The configurations which define which changes to respond to and how to respond to such changes

Handler Configurations

  • values: (Required/Array of strings) The values to attempt to match on; can have explicit values or can be an empty array to match arbitrary input.
  • match: (Optional - Defaults to "EQUALS") Determines how the above values are to be interpreted for the specified action to be taken. This field is a string constant, options:
    • EQUALS - matches the exact values for either the array or single value
    • NOT_EQUALS
    • IS_NOT_BLANK - matches any (non-blank) value
    • EQUALS_ONE_OF - matches any of the values in the array
    • NOT_EQUALS_ANY_OF - does not match any of the values in the array
  • success (Optional) The behavior this field will exhibit if the value expression is matched. This field is a string with possible values (“ENABLE” | “DISABLE” | “SHOW” | “HIDE”)
  • failure (Optional) The behavior this field will exhibit if the value expression is not matched. This field is a string constant (“ENABLE” | “DISABLE” | “SHOW” | “HIDE”)

Conditional Logic Examples

Scenario 1: You have two fields, "Metastasis" and "Cancer Recurrance", and only want to show the latter if the former is true, you would define the "Cancer Recurrance" field as:

{
"field":"Cancer Recurrence",
"datatype":"string",
"listeners" : [{
“field” : “metastasis”,
“handlers” : [{
“values” : [“true”],
“success” : “SHOW”,
“failure” : “HIDE”
}
]
}

Scenario 2: A field called diseaseGroup is a multi-select type. You want to enable a field only if the selections : “brain”, “lung”, and “breast” are selected and disabled otherwise. Within the definition of that field, the listeners portion would read:

“listeners” : [{
“field” : “diseaseGroup”,
“handlers” : [{
“values” : [“brain”, “lung”, “breast”],
“match” : “EQUALS”,
“success” : “ENABLE”,
“failure” : “DISABLE”
}
]
}]

Scenario 3 : You want a field to be shown only if any selection is made on the multi select field "testsCompleted". Within the field definition, the listeners section would look like:

“listeners” : [{
“field” : “testCompleted”,
“handlers” : [{
“values” : [],
“match” : “IS_NOT_BLANK”,
“success” : “SHOW”,
“failure” : “HIDE” // will hide if there is no selection
}
]
}]]

Related Topics

Discussion

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand all collapse all