-
Notifications
You must be signed in to change notification settings - Fork 19
Declarative Shortcut Format
Shortcuts are defined via a JSON file now. The file is in the flux project's src/shortcuts folder. Only slim mode forms now require coding and a future update should make that optional by generating a form for a shortcut at runtime based on its declaration. This document describes the current JSON format for declaring shortcuts that can be used in slim and full modes (with the exception of the forms in slim mode as noted).
The declarative shortcut file is in JSON format and consists of a list of shortcut definition objects. Each shortcut definition object has a type property and an id property.
Each shortcut definition has an Id property which must be unique across all defined shortcuts in the file. Relationships between shortcuts are defined using the id properties.
Currently, 4 different shortcut types are supported. The shortcut definition's type property specifies which type each shortcut is. The types are each described below.
Two high-level types of shortcuts exist, however. Insert shortcuts put structured information from the patient record into a clinical note. Creator shortcuts indicate new structured pieces of information that should be added to the patient's record. Insert shortcuts use the @ symbol as a prefix while creator shortcuts use #.
In general, shortcuts exist within a context hierarchy. Many shortcuts require some context to make sense. For example, specifying disease progression only makes sense within the context of a specific condition for a specific patient. The patient is always at the root of the context hierarchy. Insert and creator shortcuts can establish a context for subsequent shortcuts. When humans read narrative clinical note, they also require context. A clinician would indicate disease progression only if the condition it applied to was already established within the text of the note. Saying "The patient's disease is stable" only makes sense after establishing that the text is talking about the patient's lobular carcinoma of the breast condition for example.
Insert Value shortcuts have a type of "InsertValue". Insert Value shortcuts are used to insert structured pieces of information from the patient's record. The properties supported within the declaration of an Insert Value shortcut (other than Id and Type) are each described below.
Specifies how the insert value shortcut should get the value it will insert. The value is an object in one of four forms.
"getData": {"object": "patient", "method": "getMRN"},
In form 1, "object" and "method" properties are supplied. The method is invoked on the specified object. The object can be "patient" to invoke a method on the patient.
"getData": {"string": "${name} is a ${age} year old ${gender}",
"params":{"age": {"object": "patient", "method": "getAge"},
"gender": {"object": "patient", "method": "getGender"},
"name": {"object": "patient", "method": "getName"}
}
}
In form 2, a "string" property specifying the string to insert is provided. That string has variables in it indicating by ${name} what to insert. Name within ${name} specifies a lookup within the second property called "params." The name is looked up and an object is returned. That object should follow one of the forms specified to resolve to the value to replace the ${name} variable with within the string.
"getData": {"object": "patient", "method": "getConditions",
"itemKey": "entryInfo.entryId", "itemContext":"specificType.value.coding.0.displayText.value"},
In form 3, four properties are provided within the object. The "method" property specifies the method to call on the "object" property. If object is patient, then the method is invoked on the patient. No other options are supported right now. The result of that method is a list of objects from the model (e.g., Conditions in the example above). The resulting array of objects is mapped into a new object array contains itemKey and itemContext properties. The values of those properties for a specific object returned is given by the specified "itemKey" and "itemContext" properties. The values of those properties specify a path of properties to resolve against the each returned object. For the example above, the itemKey for each returned object would be set to the entryId property of the entryInfo property of the condition. Note that .0 means the first element of an array as normally allowed in JavaScript.
"getData": {"object": "parent", "attribute": "stage"},
In form 4, the "object" property has a value of "parent" to get the value of a property of the value object (an object in the model based on the SHR) associated with the parent context. The "attribute" property specifies the name of the property to get.
For this shortcut to establish as a context for other shortcuts, this property must be true.
If this property is set to true (default is false if not specified), isContext must also be true and then this shortcut will establish a global context that lasts from when it's started until the end of the note. Ending the paragraph where it's added will not end the context like non-global contexts.
The "stringTriggers" property specifies a list of object; each specifies one string that can be used to trigger the shortcut. Each item in the list can take on one of the following forms.
{"name":"@stage", "description": "Stage of cancer based on AJCC"}
The "name" provides the exact string including any prefix while the "description" provides a string describing what the shortcut does when initiated using the specified trigger string.
{"category":"staging", "valueSet":"T", "args":"7", "prefix": "#"}
This form results in a list being retrieved from the Value Set Manager. The "category" and "valueSet" properties indicate which list to return. The "args" property can be used to provide an argument to the Value Set Manager retrieval. For example, the args value of 7 indicates that the 7th edition of the AJCC staging T values should be used. Finally, the "prefix" property indicates that each value retrieved should have the provided value put before it.
The "knownParentContexts" property specifies any parent contexts that the current shortcut can exist within. Not all shortcuts know their parents; in those cases, the parents know their children instead. That is the case for many generic shortcuts used for multiple parent shortcuts like the DateCreator for example. If the context is "Patient" then the shortcut can be used within the patient context. In all other cases, the parent context must be the valid id of another shortcut.
If this property is specified with a true value, the shortcut will not be included in any FullApp instances. If left out, shortcut is not disabled and can appear in any FullApp instances.
The "parentAttribute" property indicates the name of the attribute on the parent shortcut that this shortcut sets. The attribute must be defined on the parent shortcut (either a Creator Base or Creator Intermediary) in its valueObjectAttributes.
The "createObjectForParsing" property is specific for the note parser and specifies the object that is needed for the note parser to parse the shortcut in a note. @active medication is an example of a shortcut that uses this property. It requires a patient object in order to be able to create an active medication. A lookup is performed on the patient to grab the list of active medications associated with the patient. The "createObjectForParsing" property has the following form:
"createObjectForParsing": {"object": "patient", "method": "createActiveMedication", "args": ["$selectedValue"]}
The "object" property is the object needed for the shortcut and in this case is "patient". The method is invoked on the object. The argument is $selectedValue to pass the shortcut's selected value.
Creator Base shortcuts have a type of "CreatorBase". Creator base shortcuts don't have parents other than the patient and typically establish their own context as well.
The "name" property provides a human-readable name to use for this shortcut. The string is used, for example, when the shortcut is a context and has a tab for its potential children in the context panel next to the editor.
The "valueObject" property specifies the entity type of the SHR object that this shortcut supports creation of. This should be the full URL of the object. For example, http://standardhealthrecord.org/oncology/TNMStage indicates that the shortcut supports creation of a TNMStage entry defined in the oncology namespace.
[ {"name":"T", "attribute":"t_Stage", "isSettable":"true", "setMethod":"t_Stage", "childShortcut": "StagingTCreator"},
{"name":"N", "attribute":"n_Stage", "isSettable":"true", "setMethod":"n_Stage", "childShortcut": "StagingNCreator"},
{"name":"M", "attribute":"m_Stage", "isSettable":"true", "setMethod":"m_Stage", "childShortcut": "StagingMCreator"},
{"name":"stage", "attribute":"stage", "isSettable":"false"} ]
The "valueObjectAttributes" property is a list of objects each describing one attribute that the creator shortcut supports. Each attribute is defined by a number of properties in the attribute descriptor object.
The "name" property specifies the name of the attribute. The name is used to refer to the property elsewhere in the shortcut declarations; for example, a child shortcut may indicate that it provides the value for a specific attribute of its parent by its name.
The "attribute" property indicates the name of the property on the value object that this shortcut attribute represents. When this attribute is set, it causes this property to be set on the value object.
The "isSettable" property indicates whether the property is settable or not. Properties that aren't settable do not get set by a child shortcut. Instead, they get set by the other properties being set. For example, the stage attribute on the TNMStage value object gets set by the T, N, and M values being set - not by a child shortcut.
The "setMethod" property indicates the setter property on the value object to use to set the value of this attribute.
The "childShortcut" property indicates what child shortcut (by its id) sets this attribute on this creator. Child shortcuts are used to show what shortcuts make sense when the current shortcut is the active context.
The "updatePatient" property provides the list of methods to call in order to update the patient based on the value object set by the this shortcut. Each element of the list can take 1 of 2 different forms.
{"object":"$parentValueObject", "listAttribute": "observation", "args": [ "$valueObject" ]}
For form 1, the creator shortcut results in a new object being added to an existing list of objects. The "listAttribute" property specifies the attribute on the object specified by the "object" property that is a list of objects that this creator shortcut will add to. The object specified can be $parentValueObject or $valueObject. In addition, the "args" property specifies what arguments to use when setting the list attribute. Args will typically be a single item and be the $valueObject in this case. The example above adds the current creator shortcut's value object (that it created) to the observation list of the parent value object.
{"object":"patient", "method": "addEntryToPatientWithPatientFocalSubject", "args": [ "$valueObject" ]}],
{"object":"$valueObject", "method": "setAssessmentFocusReference", "args": [ "$parentValueObject"]}
For form 2, the method specified by the "method" property is invoked on the object specified by the "object" property passing the arguments provided by the "args" property. The object can be patient (method is invoked on the current patient), $valueObject (the method is invoked on the this shortcut's value object), or $parentValueObject (the method is invoked on this shortcut's parent's value object. The arguments can be simple values or be $valueObject or $parentValueObject to pass this shortcut's value object or its parent's value object respectively.
For this shortcut to establish as a context for other shortcuts, this property must be true.
The "stringTriggers" property specifies a list of object; each specifies one string that can be used to trigger the shortcut. Each item in the list can take on one of the following forms.
{"name":"@stage", "description": "Stage of cancer based on AJCC"}
The "name" provides the exact string including any prefix while the "description" provides a string describing what the shortcut does when initiated using the specified trigger string.
{"category":"staging", "valueSet":"T", "args":"7", "prefix": "#"}
This form results in a list being retrieved from the Value Set Manager. The "category" and "valueSet" properties indicate which list to return. The "args" property can be used to provide an argument to the Value Set Manager retrieval. For example, the args value of 7 indicates that the 7th edition of the AJCC staging T values should be used. Finally, the "prefix" property indicates that each value retrieved should have the provided value put before it.
Some shortcuts support triggers that follow a certain format instead of or in addition to being a specific string. For example, the Date Creator shortcut support specifying a date preceded by a hashtag (#12/12/2015). This property supports specifying a regular expression that triggers can match to trigger this shortcut. Regular expression triggers do not work for autocomplete and do not appear in the right context area of the editor, but they can be entered in the editor. Often they have an associated picker that can be triggered via a string trigger (e.g., #date).
The "form" property specifies the name of the REACT component representing the form to display in slim mode for this shortcut.
Will be implemented in the future to auto-generate a form for a shortcut at runtime unless valueObjectAttributes can be expanded to support it instead.
"#staging #${T} #${N} #${M}"
"#disease status is #${status} #based on #${reasons}${% relative to #reference date #${referenceDateDate}}
The "structuredPhrase" property is used in slim mode to format the structured phrase for this creator shortcut. The structured phrase pulls together all the values specified for the child shortcuts. It is specified as a string with variables within it that filled in by the attributes of this shortcut. ${T} means to get this shortcut's value for its T attribute and replace it in the string. The other supported syntax is ${% which indicates to include all the text between it and its corresponding closing } if the ${attribute} within it has a value. In the second example above, the phrase " relative to #reference date #${referenceDateDate} will only be included in the structured phrase if the referenceDataDate attribute has a value.
"http://standardhealthrecord.org/oncology/BreastCancer",
The value object of the parent context must be of the entry type specified by this property. This shortcut is only valid within such a parent context. If this property is not specified then the parent context's value object does not have to be of any specific type.
The "knownParentContexts" property specifies any parent contexts that the current shortcut can exist within. Not all shortcuts know their parents; in those cases, the parents know their children instead. That is the case for many generic shortcuts used for multiple parent shortcuts like the DateCreator for example. If the context is "Patient" then the shortcut can be used within the patient context. In all other cases, the parent context must be the valid id of another shortcut.
The "description" property provides a description for the shortcut to be used in the slim mode.
This property is NOT USED YET but may be when form generation is included.
Creator Intermediary shortcuts have a type of "CreatorIntermediary". Creator intermediary shortcuts can only exist within a parent context and also are always their own context and can therefore have other creator intermediaries or creator child shortcuts as children to them.
The "name" property provides a human-readable name to use for this shortcut. The string is used, for example, when the shortcut is a context and has a tab for its potential children in the context panel next to the editor.
[ {"name":"date", "toParentAttribute":"enrollmentDateDate", "childShortcut":"DateCreator"} ]
The "valueObjectAttributes" property is a list of objects each describing one attribute that the creator shortcut supports. Each attribute is defined by a number of properties in the attribute descriptor object.
The "name" property specifies the name of the attribute. The name is used to refer to the property elsewhere in the shortcut declarations; for example, a child shortcut may indicate that it provides the value for a specific attribute of its parent by its name.
The "toParentAttribute" property indicates the name of the property on the parent shortcut that this shortcut attribute represents. When this property is set, the value is actually set on the parent context's attribute named by this property.
The "childShortcut" property indicates what child shortcut (by its id) sets this attribute on this creator. Child shortcuts are used to show what shortcuts make sense when the current shortcut is the active context.
The "parentAttribute" property indicates the name of the attribute on the parent shortcut that this shortcut sets. The attribute must be defined on the parent shortcut (either a Creator Base or Creator Intermediary) in its valueObjectAttributes.
For this shortcut to establish as a context for other shortcuts, this property must be true.
The "stringTriggers" property specifies a list of object; each specifies one string that can be used to trigger the shortcut. Each item in the list can take on one of the following forms.
{"name":"@stage", "description": "Stage of cancer based on AJCC"}
The "name" provides the exact string including any prefix while the "description" provides a string describing what the shortcut does when initiated using the specified trigger string.
{"category":"staging", "valueSet":"T", "args":"7", "prefix": "#"}
This form results in a list being retrieved from the Value Set Manager. The "category" and "valueSet" properties indicate which list to return. The "args" property can be used to provide an argument to the Value Set Manager retrieval. For example, the args value of 7 indicates that the 7th edition of the AJCC staging T values should be used. Finally, the "prefix" property indicates that each value retrieved should have the provided value put before it.
The "knownParentContexts" property specifies any parent contexts that the current shortcut can exist within. Not all shortcuts know their parents; in those cases, the parents know their children instead. That is the case for many generic shortcuts used for multiple parent shortcuts like the DateCreator for example. If the context is "Patient" then the shortcut can be used within the patient context. In all other cases, the parent context must be the valid id of another shortcut.
The "description" property provides a description for the shortcut to be used in the slim mode.
The "shortcutGroupName" property is used to group shortcuts together within the right context area of the editor. This property provides the label to show within the context area.
Creator Child shortcuts have a type of "CreatorChild". Creator child shortcuts can only exist within a parent context and never establish their own context.
"subtype": "list"
Indicating that a creator child shortcut is a list using this property causes the setting of the parent attribute to get the current list value, add the new item to it, and then set the current list value. If a creator child represents a list attribute of the parent, this property should be included to make sure it behaves correctly.
The "parentAttribute" property indicates the name of the attribute on the parent shortcut that this shortcut sets. The attribute must be defined on the parent shortcut (either a Creator Base or Creator Intermediary) in its valueObjectAttributes.
The "stringTriggers" property specifies a list of object; each specifies one string that can be used to trigger the shortcut. Each item in the list can take on one of the following forms.
{"name":"@stage", "description": "Stage of cancer based on AJCC"}
The "name" provides the exact string including any prefix while the "description" provides a string describing what the shortcut does when initiated using the specified trigger string.
{"category":"staging", "valueSet":"T", "args":"7", "prefix": "#"}
This form results in a list being retrieved from the Value Set Manager. The "category" and "valueSet" properties indicate which list to return. The "args" property can be used to provide an argument to the Value Set Manager retrieval. For example, the args value of 7 indicates that the 7th edition of the AJCC staging T values should be used. Finally, the "prefix" property indicates that each value retrieved should have the provided value put before it.
Some shortcuts support triggers that follow a certain format instead of or in addition to being a specific string. For example, the Date Creator shortcut support specifying a date preceded by a hashtag (#12/12/2015). This property supports specifying a regular expression that triggers can match to trigger this shortcut. Regular expression triggers do not work for autocomplete and do not appear in the right context area of the editor, but they can be entered in the editor. Often they have an associated picker that can be triggered via a string trigger (e.g., #date).
"date-id",
{ "category": "clinicalTrial", "valueSet": "clinicalTrials", "prefix": "#"}
The "picker" property is used when a string trigger is specified that gets a list of possible values to pick from rather than a single value. Pickers are only used on Creator Child's. The Date Creator specifies a special picker called "date-id" that causes a date picker to display when #date is used. The clinical trial title creator picker uses the second format above to display all the clinical trials to pick from when the #title trigger is used.
The "knownParentContexts" property specifies any parent contexts that the current shortcut can exist within. Not all shortcuts know their parents; in those cases, the parents know their children instead. That is the case for many generic shortcuts used for multiple parent shortcuts like the DateCreator for example. If the context is "Patient" then the shortcut can be used within the patient context. In all other cases, the parent context must be the valid id of another shortcut.
The "description" property provides a description for the shortcut to be used in the slim mode.
The "shortcutGroupName" property is used to group shortcuts together within the right context area of the editor. This property provides the label to show within the context area.
Copyright © 2017 The MITRE Corporation | Approved for Public Release; Distribution Unlimited. Case Number 16‑1988
- Home
- About Flux Notes
- Active Treatment Summary Objects
- Data Standards for Breast Cancer
- Database decision
- Declarative Shortcut Format
- Demo Script
- Deployment Plan - Lite Mode
- Dragon Software Information and Troubleshooting
- Flux Notes Lite Demo Script
- How To Create New Shortcuts
- Interaction Between REACT.js Components in Flux
- JavaScript and HTML Code Style Guide
- Key Application Features
- Minimap Evaluation
- Naming Convention for Visual Components
- NLP Server: Provisioning and Troubleshooting
- Pre Release Testing Script
- Profiling and Performance
- Redux Implementation Guide
- Shorthand Context Problem
- Testing
- Third Party Libraries Changes
- Demo Scenarios -- (out of date)