By default, Liquid provides a set of standard filters to assist template creation. Besides these filters, FHIR Converter also provides some other filters that are useful in conversion, which are listed below. If these filters do not meet your needs, you can also write your own filters.
Filter | Description | Syntax |
---|---|---|
get_first_segments | Returns first instance of the segments | {% assign result = hl7v2Data | get_first_segments: 'segment1|segment2|...' -%} |
get_segment_lists | Extracts HL7 v2 segments | {% assign result = hl7v2Data | get_segment_lists: 'segment1|segment2|...' -%} |
get_related_segment_list | Given a segment and related segment name, returns the collection of related named segments | {% assign result = hl7v2Data | get_related_segment_list: parentSegment, 'childSegmentName' -%} |
get_parent_segment | Given a child segment name and overall message index, returns the first matched parent segment | {% assign result = hl7v2Data | get_parent_segment: 'childSegmentName', 3, 'parentSegmentName' -%} |
has_segments | Checks if HL7 v2 message has segments | {% assign result = hl7v2Data | has_segments: 'segment1|segment2|...' -%} |
split_data_by_segments | Given an HL7 v2 message and segment name(s) as the separator(s), returns the message list split by separator(s). Note: Each segment separator will be retained as the first segment of each message in the list, while the segments before the first separator (which may be empty) will be retained as the first message in the list without any separator. |
{% assign result = hl7v2Data | split_data_by_segments: 'segment1|segment2|...' -%} |
Filter | Description | Syntax |
---|---|---|
get_first_ccda_sections | Returns first instance (non-alphanumeric chars replace by '_' in name) of the sections | {% assign firstSections = msg | get_first_ccda_sections: 'Problems' -%} |
get_ccda_section_lists | Returns instance list (non-alphanumeric chars replace by '_' in name) for the given sections | {% assign sections = msg | get_ccda_section_lists: 'Problems' -%} |
get_first_ccda_sections_by_template_id | Returns first instance (non-alphanumeric chars replace by '_' in name) of the sections by template id | {% assign firstSections = msg | get_first_ccda_sections_by_template_id: '2.16.840.1.113883.10.20.22.2.5.1' -%} |
Filter | Description | Syntax |
---|---|---|
char_at | Returns char at position index | {{ 'foo' | char_at: 0 }} #=> 'f' |
contains | Returns true if a string includes another string | {{ 'foo' | contains: 'fo' }} #=> true |
escape_special_chars | Returns string with special chars escaped | {{ '\E' | escape_special_chars }} #=> '\\E' |
unescape_special_chars | Returns string after removing escaping of special char | {{ '\\E' | unescape_special_chars }} #=> '\E' |
match | Returns an array containing matches with a regular expression | {% assign m = code | match: '[0123456789.]+' -%} |
to_json_string | Converts to JSON string | {% assign msgJsonString = msg | to_json_string -%} |
to_double | Converts string to double | {{ "100.01" | to_double }} |
base64_encode | Returns base64 encoded string | {{ decodedData | base64_encode }} |
base64_decode | Returns base64 decoded string | {{ encodedData | base64_decode }} |
sha1_hash | Returns SHA1 hash (in hex) of given string | {{ inputData | sha1_hash }} |
gzip | Returns compressed string | {{ uncompressedData | gzip }} |
gunzip_base64_string | Returns decompressed string | {{ compressedData | gunzip_base64_string }} |
Filter | Description | Syntax |
---|---|---|
is_nan | Checks if the object is not a number | {{ true | is_nan }} #=> true |
abs | Returns the absolute value of a number | {{ -2019.6 | abs }} #=> 2019.6 |
pow | Returns the base to the exponent power, that is, base^exponent | {{ 3 | pow: 3 }} #=> 27 |
random | Returns a non-negative random integer that is less than the specified maximum. | {{ 100 | random }} #=> 52 |
sign | Returns either a positive or negative +/- 1, indicating the sign of a number passed into the argument. If the number passed into is 0, it will return a 0. Note that if the number is positive, an explicit (+) will not be returned | {{ -5 | sign }} #=> -1 |
truncate_number | Returns the integer part of a number by removing any fractional digits | {{ -34.53 | truncate_number }} #=> -34 |
divide | Divides first number by the second number and return a double | {{ 5 | divide: 2 }} #=> 2.5 |
Filter | Description | Syntax |
---|---|---|
add_hyphens_date | Adds hyphens to a date or a partial date that does not have hyphens to make it into a valid FHIR format. The input date format is YYYY, YYYYMM, or YYYYMMDD. The output format is a valid FHIR date or a partial date format: YYYY, YYYY-MM, or YYYY-MM-DD. | {{ PID.7.Value | add_hyphens_date }} |
format_as_date_time | Converts valid HL7v2 and C-CDA datetime to a valid FHIR datetime format. The input datetime format is datetime or partial datetime without hyphens: YYYY[MM[DD[HH[MM[SS[.S[S[S[S]]]]]]]]][+/-ZZZZ]. For example, the input 20040629175400000 will have the output 2004-06-29T17:54:00.000Z. Provides parameters to handle different time zones: preserve, utc, local. The default method is preserve. | {{ PID.29.Value | format_as_date_time: 'utc' }} |
now | Provides the current time in a specific format. The default format is yyyy-MM-ddTHH:mm:ss.FFFZ. | {{ '' | now: 'dddd, dd MMMM yyyy HH:mm:ss' }} |
add_seconds | Adds double seconds on a valid FHIR datetime (e.g.2021-01-01T00:00:00Z). Provides parameters to handle different time zones: preserve, utc, local. The default method is preserve. | {{ "2021-01-01T00:00:00Z" | add_seconds:100.1, 'utc' }} |
date | This is the standard Liquid date filter. In the underlying DotLiquid implementation, .NET date formats are used (standard & custom). | {{ msg.date | date: "yyyy-MM-ddTHH:mm:ss.fff" }} |
DateTime filters usage examples:
- add_hyphens_date
{{ "2001" | add_hyphens_date }} -> 2001
{{ "200101" | add_hyphens_date }} -> 2001-01
{{ "20010101" | add_hyphens_date }} -> 2001-01-01
- format_as_date_time
{{ "20110103143428-0800" | format_as_date_time }} -> 2011-01-03T14:34:28-08:00
{{ "20110103143428-0800" | format_as_date_time: 'preserve' }} -> 2011-01-03T14:34:28-08:00
{{ "20110103143428-0800" | format_as_date_time: 'utc' }} -> 2011-01-03T22:34:28Z
[Note] :
format_as_date_time
andadd_hyphens_date
are used to convert HL7v2 and C-CDA date and datetime format to FHIR. For other date or datetime's reformat, please refer to the standard filter date.
- now
{{ "" | now }} -> 2022-03-22T06:50:25.071Z // an example time
{{ "" | now: 'dddd, dd MMMM yyyy HH:mm:ss' }} -> Tuesday, 22 March 2022 06:52:15
{{ "" | now: 'd' }} -> 3/22/2022
[Note] : Input string will not affect the result.
- add_seconds
{{ "1970-01-01T00:01:00.000+10:00" | add_seconds: -60, 'utc' }} -> 1969-12-31T14:00:00.000Z
{{ "1970-01-01T00:01:00Z" | add_seconds: 60.1230 }} -> 1970-01-01T00:02:00.123Z
{{ "1970-01-01T00:01:00+14:00" | add_seconds: 60, 'preserve' }} -> 1970-01-01T00:01:01+14:00
[Note] : If the input is a partial datetime without time zone, it will be set to the first day of the year and 00:00:00 clock time with local time zone as suffix. e.g. In the location with +08:00 time zone, the input string "201101031434" will be filled to "20110103143400+0800". The template {{ "201101031434" | format_as_date_time: 'utc'}} will output 2011-01-03T06:34:00Z when running at +08:00 location.
Filter | Description | Syntax |
---|---|---|
to_array | Returns an array created (if needed) from given object | {% assign authors = msg.ClinicalDocument.author | to_array -%} |
concat | Returns the concatenation of provided arrays | {% assign ethnicCodes = ethnicCodes1 | concat: ethnicCodes2 -%} |
batch_render | Render every entry in a collection with a snippet and a variable name set in snippet | {{ firstSections.2_16_840_1_113883_10_20_22_2_5_1.entry | to_array | batch_render: 'Entry/Problem/entry', 'entry' }} |
Filter | Description | Syntax |
---|---|---|
get_property | Returns a specific property of a coding with mapping file CodeSystem.json | {{ PID.8.Value | get_property: 'CodeSystem/Gender', 'code' }} |
generate_uuid | Generates an ID based on an input string | {% assign patientId = firstSegments.PID.3.1.Value | generate_uuid -%} |
generate_id_input | Generates an input string for generate_uuid with 1) the resource type, 2) whether a base ID is required, 3) the base ID (optional) | {{ identifiers | generate_id_input: 'Observation', false, baseId | generate_uuid }} |
By default, Liquid provides a set of standard tags to assist in template creation. Besides these tags, FHIR Converter also provides some other tags useful in conversion, which are listed below. If these tags do not meet your needs, you can write your own tags.
Tag | Description | Syntax |
---|---|---|
evaluate | Evaluates an ID with an ID generation template and input data | {% evaluate patientId using 'Utils/GenerateId' obj:msg.ClinicalDocument.recordTarget.patientRole -%} |
mergeDiff | Merge diff JSON on input JSON data. The input data and difference in content should be a valid JSON format. | {% mergeDiff msg -%} <diff json> {% endmergeDiff -%} |
Examples to use mergeDiff
Add or update an item:
{% mergeDiff msg -%}
{
"added": "value"
}
{% endmergeDiff %}
Remove an item:
{% mergeDiff msg -%}
{
"removed": ""
}
{% endmergeDiff %}
Choice type item:
Using [x]
to represent item with choice type. ( e.g. value[x] includes
valueString, valueReference, valueInteger, etc. )
The key in diff json can use [x]
to simplfy the template.
Here is a sample to remove choice type element for "value":
{% mergeDiff msg -%}
{
"value[x]" : ""
}
{% endmergeDiff %}
Examples for STU3 input
Since FHIR resources are in JSON format and since the FHIR STU3 and R4 versions of resources have the same structure and share most datetypes, the mergeDiff tag can be widely used in FHIR STU3 to R4 conversion.
Here is an example to convert ChargeItem resource from STU3 to R4 :
ChargeItem.liquid:
{% mergeDiff msg -%}
{
"definitionUri" : {{msg.definition | to_json_string | default : '""'}},
"performer" : [ {{ msg.participant | to_array | batch_render: 'ChargeItem/ChargeItemPerformer', 'msg' }} ],
"participant" : "",
"definition" : ""
}
{% endmergeDiff -%}
_ChargeItemPerformer.liquid:
{% mergeDiff msg -%}
{
"function" : {{msg.role | to_json_string | default : '""'}},
"role" : ""
}
{% endmergeDiff -%}
In this sample, the field "definition" will be renamed to "definitionUri" and field "participant" will be renamed to "performer". All other other fields in the ChargeItem resource are copied as is from STU3 to R4.