XML shorthand variables are a feature of the Custom Task which simplify the Jython code you write. In particular - XML shorthand variables simplify code for getting values from the input DOM, and setting values in the output DOM.
You can enable this feature through the checkboxes near the top of the Custom Task.
Without this feature, it is generally necessary to write Jython code as below in order to set a field in an HL7 message. This example assumes that no input or output parameters have been defined on this Custom Task - that is, only the root node "TaskData" exists:
input_message_string = engine.inputDom.getDocumentElement().getFirstChild().getNodeValue()
hl7msg = util.makeHL7Message(input_message_string)
hl7msg.setField('TEST_PATIENT', 'PID', 5)
engine.outputDom = util.makeXMLDocument('TaskData')
text_node = engine.outputDom.createTextNode(hl7msg.toString())
engine.outputDom.getDocumentElement().appendChild(text_node)
You can use MD Link functions such as util.appendText() to simplify this code, but not very much. It can be simplified much more if you use XML shorthand variables.
If you select the input and output XML shorthand variables checkboxes, you can replace the code above with this code:
hl7msg = util.makeHL7Message(input)
hl7msg.setField('TEST_PATIENT', 'PID', 5)
output = hl7msg.toString()
This is because the XML shorthand variables feature causes MD Link to do two things: i) define the variable "input" to have a value equal to the string contents of the root element of input DOM, and ii) reads the variable "output" and construct the root element of the output DOM from it's value.
We can simplify the last line even further:
hl7msg = util.makeHL7Message(input)
hl7msg.setField('TEST_PATIENT', 'PID', 5)
output = hl7msg # Note that no "toString()" is required
You don't need to call "toString()" on the hl7msg object, because the XML shorthand variables feature will do it for you.
The variables "input" and "output" will only be defined if you haven't declared any parameters under the "Parameters" tab. If you have some parameters defined, then the variables defined will have names the same as those parameters. For example you may have defined two input parameters named FirstName and LastName, and a single output parameter named FullName, like this:
Say you want to concatenate FirstName and LastName, with a space in between, to create FullName. Without the XML shorthand variables feature, you will need to write code like this:
FirstName = engine.inputDom.getElementsByTagName('FirstName').item(0).getFirstChild().getNodeValue()
LastName = engine.inputDom.getElementsByTagName('LastName').item(0).getFirstChild().getNodeValue()
FullName = FirstName + ' ' + LastName
engine.outputDom = util.makeXMLDocument('TaskData')
fullNameElement = engine.outputDom.createElement('FullName')
fullNameElement.appendChild(engine.outputDom.createTextNode(FullName))
engine.outputDom.getDocumentElement().appendChild(fullNameElement)
With the XML shorthand variables feature - both "input" and "output" checkboxes selected - you can replace all of the code above with a single line:
FullName = FirstName + ' ' + LastName
If you define nested levels of parameters, they will appear as XML shorthand variables also. The separate levels of parameters will be separated by an underscore character. For example, with parameters like this:
You can write code like this:
DatabaseInfo_RecordDescription = Patient_LastName + Patient_FirstName + Insurance_IDNumber
For parameters that can appear more than once in the input message - that is, you have defined them to have multiple ("*") cardinality - the XML shorthand variable will appear as a list of strings, instead of a string. For example, with parameters like this:
You can write code like this:
for idnum in IDNumber: if idnum == 'TEST': engine.cancel()
Note that MD Link didn't append an "s" to "IDNumber" to indicate the plural. The variable name that appears in the script is exactly the same as the parameter name that you defined in the parameter tree.
If a certain XML element is not present in the input message, MD Link will set its corresponding input variable to None. None is a Python keyword that is similar to null in other programming languages.
Using None, you could write code such as this to fail if the FirstName element is not in the input message:
if FirstName == None:
engine.fail('FirstName is not present. This is forbidden.')
With this script, if an input message such as the following is passed to the task, the task will succeed:
<?xml version="1.0" encoding="UTF-8"?>
<TaskData>
<FirstName>John</FirstName>
</TaskData>
But an input message such as this one will cause a failure:
<?xml version="1.0" encoding="UTF-8"?> <TaskData> </TaskData>
Note that the element being not present (None) is different from the element being present and empty. An example of FirstName being empty is an input message such as this one:
<?xml version="1.0" encoding="UTF-8"?>
<TaskData>
<FirstName></FirstName>
</TaskData>
We can expand our script to deal with this empty string case:
if FirstName == None:
engine.fail('FirstName is not present. This is forbidden.')
elif FirstName == '':
engine.fail('FirstName is empty. Also forbidden.')
We can simplify the above script using a feature of Python that checks for both the None and empty cases with one "if" condition:
if FirstName:
engine.fail('FirstName is either not present or empty. Forbidden.')Likewise, for output variables, if you set an output variable to None, this will cause the corresponding element to not be created in the output. If you set the output variable to '' (the empty string), then it will be present but empty.
MD Link will escape some characters in order to make your parameter names into valid Jython variable names. If you would like to see which XML shorthand variables are defined for your script, add this line of code to your script and run it:
print globals()
This line of code will print a full list of variables, including all of the XML shorthand variables, to the logs.
The XML shorthand variables feature currently can't handle multiple output messages (that is, use of the plural engine.outputDoms instead of the singular engine.outputDom) or a parameter tree that contains nested elements with multiple cardinality. For these cases, you will need to write your code the conventional way using low-level DOM functions or MD Link util functions.