Populating data from TRIM
From DOC
Application data can be created and updated under program control using Tolven APIs. However, a declarative mechanism can be used that requires no programming and can be configured without taking down the server.
This mechanism is used by the TRIM creator and rule processor to pull information from a document into placeholders and is also used to pull information from a placeholder into lists and other derived data elements. The process of populating application data begins in the application metadata which resides in the database. However, it is easier to visualize this configuration by looking at a xxx.application.xml file.
Contents |
Populating a placeholder
In order to understand how this process works, you must first be familiar with Placeholder Binding.
The first example shows the configuration of a Patient placeholder.
<placeholder name="patient" ...>
<field name="lastName" internal="string01">
<from>#{role.player.name.EN['L'].formattedParts['FAM']}</from>
</field>
<field name="firstName" internal="string02" >
<from>#{role.player.name.EN['L'].formattedParts['GIV[0]']}</from>
</field>
<field name="middleName" internal="string03" >
<from>#{role.player.name.EN['L'].formattedParts['GIV[1]']}</from>
<from>NMN</from>
</field>
<field name="homeTelecom" >
<from>#{trim.isName['reg/evn/patient.*'].act.participation['subject'].role.player.telecom.TEL['H'].value}</from>
</field>
...
In this example, you will notice that each field has a <from> element. In general, a <from> contains a value that will be used to populate the containing field when a placeholder of this type is created or updated.
Expression Language
The example above makes use of Java Expression Language (EL). The EL provides a concise format for selecting data from complex structures such as a TRIM document. When evaluated, a number of Expression Language Variables are made available for use in the EL.
Access to the underlying TRIM
The underlying TRIM, if from a TRIM, is available using the variable named trim. For example,
<from>#{trim.description}</from>
returns the description field of the TRIM underlying this placeholder.
Relative access to TRIM
Accessing elements of a TRIM starting at the root of the TRIM is fairly limited: A TRIM could contain placeholder binding instructions at various locations. For example, an HL7 CDA R2 TRIM might have sections and subsections containing observations that should all be extracted to become observation placeholders. A much more flexible approach allows you to specify a relative path into the TRIM starting at the RIM object (Act, Role, or Entity) containing the binding instruction for that placeholder.
Assume that the TRIM underlying this placeholder contains the following XML:
...
<participation name="subject" typeCode="SBJ">
<role classCode="PAT">
<bind application="echr">
<placeholder>
<path>echr:patient</path>
</placeholder>
</bind>
...
<id>
<II>
<root>#{computeIDRoot(account)}</root>
<extension>#{patient.path}</extension>
</II>
</id>
...
The corresponding placeholder in the application.xml can then reference the role containing the binding instruction using the role variable, regardless of where or how deep into the TRIM that binding instruction is found.
<field name="lastName" internal="string01">
<from>#{role.player.name.EN['L'].formattedParts['FAM']}</from>
</field>
If the binding instructions were on an Act, then the variable would be named act. Similar for an Entity though binding on an RIM Entity is not common or advised.
Access to account
The Account object is available for use in EL. Account contains preferences which may influence how a placeholder is populated. However, since all placeholder data is automatically partitioned by account, there is nothing required from the account.
From element is optional
The from element is optional. If omitted, then it is assumed that some other mechanism will be populating the placeholder, or the field will be left null.
In the following example, there is no <from> element because the column is computed from other fields in the placeholder.
<column name="Name" internal="string01,string02,string03" format="%s, %s %s" reference="true" width="20.0"/>
Multiple <from> Elements
A field can contain more than one <from> element as you will see with the middleName field. Tolven will use the first <from> that returns a non-null value. So, in the example of middleName, if no middle name is found in a trim document, then the literal NMN is used. The null feature is particularly important when a placeholder can have different kinds of underlying documents: CCR, TRIM, etc: If the document is not a TRIM document, then Tolven just moves on to the next <from> in the list. This is an important concept in Tolven: The placeholder element acts as a normalization point which allows different kinds of documents/messages to contribute to the same kind of Placeholder. For example, a Patient placeholder could be created as the result of a CCR message and then updated using a TRIM document.
Conditional EL
In some cases, you may only want to get a field value from certain TRIMs. In the following example, the isName element is added to the EL. This element will return a null if the name of the trim does not match the regular expression in the index. This immediately stops the evaluation and returns null. If the name of the trim does match, then it returns the trim object (again) and evaluation proceeds.
In the following example, the phone number is only retrieved if extracting from a patient registration TRIM. If another TRIM was configured to create a patient placeholder, perhaps for a clinical trial, the patient's phone number would not be extracted from the TRIM.
<field name="homeTelecom" >
<from>#{trim.isName['reg/evn/patient.*'].act.participation['subject'].role.player.telecom.TEL['H'].value}</from>
</field>
See also: Populating List items
