8. plugin

Sub-keyword	Notes
name	Defines the name of the plugin to apply.
action	Specifies the action to perform with this plugin.
parameters	Lists individual operations for a given plugin.action.

Plugin: Dates with time

Bundles functionality for handling date values with time. This is referenced as name: date-time.

parse

Identifies how to read an incoming date-time value; outputs an ISO-8601 string.

Optional parameters

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. The default is ISO. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to parse the input (ex: yyyy MM/dd HH:mm:ss). Learn about accepted formats.
timeZone: string	The time zone of the input. See possible time zone values. The default is UTC. If the input already includes an offset or time zone information then this parameter is unused.
outputTimeZone: string	The time zone of the output. The default is UTC.

Example

Example: Parse input for date-time plugin

yaml

1
"25 Nov 2016 13:23:12 Z"

Example: Parse in config modifier for date-time plugin

yaml

1
plugin:
2
  name: date-time
3
  action: parse
4
  parameters:
5
    standard: RFC2822

Example: Parse output for date-time plugin

yaml

1
2016-11-25T13:23:12.000Z

render

Reads an ISO-8601 string and outputs into the specified format.

Required parameters

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. The default is ISO. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to parse the input (ex: yyyy MM/dd HH:mm:ss). Learn about accepted formats.

Optional parameters

Parameter	Notes
timeZone: string	The time zone of the input. See possible time zone values. The default is UTC. If the input already includes an offset or time zone information then this parameter is unused.

Example

Example: Render input for date-time plugin

yaml

1
"2016-05-25T09:08:34.123Z"

Example: Render in config modifier for date-time plugin

yaml

1
plugin:
2
  name: date-time
3
  action: render
4
  parameters:
5
    standard: HL7
6
    timeZone: America/Denver

Example: Render output for date-time plugin

yaml

1
20160525030834

now

Generates the current DateTime and then renders the output.

Required parameters

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. The default is ISO. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to parse the input (ex: yyyy MM/dd HH:mm:ss). Learn about accepted formats.

Optional parameters

Parameter	Notes
timeZone: string	The time zone of the input. See possible time zone values. The default is UTC. If the input already includes an offset or time zone information then this parameter is unused.

Example

Example: Now input

yaml

1
n/a

Example: Now in config modifier for date-time plugin

yaml

1
schema:
2
  plugin: 
3
    name: date-time
4
    action: now
5
    parameters:
6
      standard: RFC2822

Example: Now output for date-time plugin

yaml

1
Tue, 06 Sep 2022 15:19:42 +0000

Plugin: Dates

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to render the input (ex: yyyy MM/dd). Learn about accepted formats.

Parameter	Notes
standard: string (mutually exclusive with custom)	A named identifier for the format of the input. Learn about accepted formats.
custom: string (mutually exclusive with standard)	A custom-defined format for how to parse the input (ex: yyyy MM/dd). Learn about accepted formats.

Parameter	Notes
dashes: boolean	Controls if the output is rendered with or without dashes. If not specified, the default is true.

Plugin: Phone numbers

Parameter	Notes
renderFormat: string	Specifies the output to render. If not specified, the default is e164. Learn about accepted formats.

Plugin: Text formatting

Bundles functionality for manipulating text values. This is referenced as name: text.

upper-case

Converts an input string to upper case.

There aren't any required or optional parameters for upper-case.

Example

Example: Upper-case input for text plugin

yaml

1
"hello world"

Example: Upper-case in config modifier for text plugin

yaml

1
plugin:
2
  name: text
3
  action: upper-case

Example: Upper-case output for text plugin

yaml

1
"HELLO WORLD"

lower-case

Converts an input string to lower case.

There aren't any required or optional parameters for lower-case.

Example

Example: Lower-case input for text plugin

yaml

1
"HELLO WORLD"

Example: Lower-case in config modifier for text plugin

yaml

1
plugin:
2
  name: text
3
  action: lower-case

Example: Lower-case output for text plugin

yaml

1
"hello world"

trim

Removes leading and trailing whitespace from the input string.

Optional parameters

Parameter	Notes
normalizeWhitespace: boolean	Indicates whether whitespace is converted. The default is true, which converts any whitespace within the input string to one character whitespace. For example, Bob Smith becomes Bob Smith. The false value doesn't convert whitespace within the input string. For example, Bob Smith stays the same.

Example

Example: Trim input for text plugin

yaml

1
"  a   b c "

Example: Trim in config modifier for text plugin

yaml

1
plugin:
2
  name: text
3
  action: trim

Example: Trim output for text plugin

yaml

1
"a b c"

split

Splits a string value on a supplied separator and returns the resulting string array. This optionally allows retrieving a specific value by index, returning only the string.

Required parameters

Parameter	Notes
separator: string	A string value used to split the input string.

Optional parameters

Parameter	Notes
getIndex: number	A number that'll be used to retrieve a specific value using a zero-based index.
fromEnd: boolean	If true, the start index begins from the end of the array and retrieves the last value first. If specified, getIndex is required. If not specified, the default is false.

Example

Example: Split input for text plugin

yaml

1
"a,b,c"

Example: Split in config modifier for text plugin

yaml

1
plugin:
2
  name: text
3
  action: split
4
  parameters:
5
    separator: ','

Example: Split output for text plugin

yaml

1
[
2
  "a",
3
  "b",
4
  "c"
5
]

replace

Identifies an input string value and replaces occurrences of a given search value with a new value.

Global replace

This is a global replace operation. All occurrences of the search value are replaced with the new value.

There's no attempt to trim or normalize whitespace. If you require that functionality, you'll first need to sanitize your input value with the trim operator.

Required parameters

Parameter	Notes
newValue: string	A string value that serves as the replacement value. If not specified, the plugin returns an undefined value.

Optional parameters

Parameter	Notes
searchValue: string	The value that newValue replaces. If not specified, this defaults to a single whitespace.

Example

Example: Replace input for text plugin

json

1
"identifier": [
2
  {
3
    "system": "urn:redox:1a359110-47eb-40f6-924c-1e67079574a4:wshmrn",
4
    "type": {
5
      "text": "WSHMRN"
6
    },
7
    "value": "050050184"
8
  },
9
  ...
10
],

Example: Text plugin selector

json

1
$.entry[?(@.resource.resourceType=="Patient")].resource.identifier[*]

Example: Replace in config modifier for text plugin

yaml

1
if:
2
  operator: all
3
  terms:
4
    - get: type.text
5
  then:
6
    if:
7
      operator: equals
8
      terms:
9
        - get: type.text
10
        - constant: WSHMRN
11
      then:
12
        merge:
13
          - {}
14
          - properties:
15
              type:
16
                properties:
17
                  text:
18
                    constant: MR
19
              system:
20
                get: system
21
                plugin:
22
                  name: text
23
                  action: replace
24
                  parameters:
25
                    newValue: mr
26
                    searchValue: wshmrn
27
      else:
28
        comment: do nothing
29
  else:
30
    comment: type.text does not exist, do nothing

Example: Replace output for text plugin

json

1
"identifier": [
2
  {
3
    "system": "urn:redox:1a359110-47eb-40f6-924c-1e67079574a4:mr",
4
    "type": {
5
      "text": "MR"
6
    },
7
    "value": "050050184"
8
  },
9
  ...
10
],

Plugin: Arrays

Bundles functionality for handling array values. This is referenced as name: array.

The array options are:

filter
find
join
last
sort
unique
without

Review examples for each below.

filter

Returns an array of values that match the specified value.

Required parameters

Parameter	Notes
match: string	A string value used to compare to other values within an input array.

Optional parameters

Parameter	Notes
partial: boolean	The default value is false. Indicates that a partial match won't be performed. If set to true, performs a case-sensitive partial match for the specified value(s). Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted: 1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching. 2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Parameter

Notes

partial: boolean

The default value is false. Indicates that a partial match won't be performed.

If set to true, performs a case-sensitive partial match for the specified value(s).

Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted:

1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching.

2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Example

Example: Filter input for array plugin

yaml

Example: Filter in config modifier for array plugin

yaml

1
plugin:
2
  name: array
3
  action: filter
4
  parameters:
5
    match: 1

Example: Filter output for array plugin

yaml

find

Returns the first value that matches the specified value; otherwise, returns undefined if no match is found.

Required parameters

Parameter	Notes
match: string	A string value used to compare to other values within an input array.

Optional parameters

Parameter	Notes
partial: boolean	The default value is false. Indicates that a partial match won't be performed. If set to true, performs a case-sensitive partial match for the specified value(s). Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted: 1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching. 2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Parameter

Notes

partial: boolean

The default value is false. Indicates that a partial match won't be performed.

If set to true, performs a case-sensitive partial match for the specified value(s).

Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted:

1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching.

2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Example 1

Example: Find input for array plugin

yaml

Example: Find in config modifier for array plugin

yaml

1
plugin:
2
  name: array
3
  action: find
4
  parameters:
5
    match: 1

Example: Find output for array plugin

yaml

1
1

Example 2

Example: Find and partial input for array plugin

yaml

1
[
2
  {
3
    "firstName": "Joseph",
4
    "lastName": "Wilson"
5
  },
6
  {
7
    "firstName": "John",
8
    "lastName": "Doe"
9
  }
10
]

Example: Find and partial in config modifier

yaml

1
plugin:
2
  name: array
3
  action: find
4
  parameters:
5
    match:
6
      firstName: 'Jo'
7
      lastName: 'Do'
8
    partial: true

Example: Find and partial output for array plugin

yaml

1
{
2
  "firstName": "John",
3
  "lastName": "Doe"
4
}

join

Creates a string from the contents of the array and the separator.

Required parameters

Parameter	Notes
separator: string	A string value that'll be inserted immediately after each element in the array, excepting the final value in the array.

Example

Example: Join input for array plugin

yaml

1
[
2
  "a",
3
  "b",
4
  "c"
5
]

Example: Join in config modifier for array plugin

yaml

1
plugin:
2
  name: array
3
  action: join
4
  parameters:
5
    separator: ','

Example: Join output for array plugin

yaml

1
"a,b,c"

last

Retrieves the last element in an array.

There aren't any required or optional parameters for last.

Example: Last input for array plugin

yaml

Example: Last in config modifier for array plugin

yaml

1
plugin:
2
  name: array
3
  action: last

Example: Last output for array plugin

yaml

1
3

sort

Sorts the array as indicated.

This operator can sort both primitive and object arrays.

Optional parameters

Parameter	Notes
order: Array of Objects	Directs how to sort the input array. If not specified, a primitive array is sorted in asc order. An object array isn't sorted. If direction isn't specified, the array is sorted in asc order. If multiple directions are specified, they're evaluated in order. For example, it might sort an array first by age, then by last name. If you specify any direction other than asc or desc, the order parameter is ignored and not applied. If any other directions are defined, they are also ignored. If by isn't specified, a primitive array is sorted according to direction. An object array isn't sorted.

Parameter

Notes

order: Array of Objects

Directs how to sort the input array.

If not specified, a primitive array is sorted in asc order. An object array isn't sorted.

If direction isn't specified, the array is sorted in asc order. If multiple directions are specified, they're evaluated in order. For example, it might sort an array first by age, then by last name. If you specify any direction other than asc or desc, the order parameter is ignored and not applied. If any other directions are defined, they are also ignored.

If by isn't specified, a primitive array is sorted according to direction. An object array isn't sorted.

Example

Example: Sort input for array plugin

yaml

1
[
2
  {
3
    "name": "John",
4
    "age": 30
5
  },
6
  {
7
    "name": "Jane",
8
    "age": 35
9
  }
10
]

Example: Sort in config modifier for array plugin

yaml

1
plugin:
2
  name: array
3
  action: sort
4
  parameters:
5
    order:
6
      - by: age
7
        direction: desc

Example: Sort output for array plugin

yaml

1
[
2
  {
3
    "name": "Jane",
4
    "age": 35
5
  },
6
  {
7
    "name": "John",
8
    "age": 30
9
  }
10
]

unique

Returns an array of distinct values.

Optional parameters

Parameter	Notes
match: string	A string value that'll be used as the de-duplication key for a non-primitive array. If a primitive array, the value of match is ignored. If an object array, the value of match uses that object property value as the de-duplication key.

Example

Example: Unique input for array plugin

yaml

1
[
2
  "a",
3
  "b",
4
  "c",
5
  "a"
6
]

Example: Unique in config modifier for array plugin

yaml

1
plugin:
2
  name: array
3
  action: unique

Example: Unique output for array plugin

yaml

1
[
2
  "a",
3
  "b",
4
  "c"
5
]

without

Returns an array of values that don't match the specified value.

Required parameters

Parameter	Notes
match: string	A string value used to compare to other values within an input array.

Optional parameters

Parameter	Notes
partial: boolean	The default value is false. Indicates that a partial match won't be performed. If set to true, performs a case-sensitive partial match for the specified value(s). Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted: 1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching. 2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Parameter

Notes

partial: boolean

The default value is false. Indicates that a partial match won't be performed.

If set to true, performs a case-sensitive partial match for the specified value(s).

Some array actions accept a boolean partial parameter. When this is set to true the following rules are enacted:

1) The value of parameters.match can be a string value or an object (as makes sense for your input value). Non-string values will use exact matching.

2) If multiple key/value pairs are provided in parameters.match and logic is used, each key/value pair must partially match.

Example

Example: Without input for array plugin

yaml

Example: Without in config modifier for array plugin

yaml

1
plugin:
2
  name: array
3
  action: without
4
  parameters:
5
    match: 1

Example: Without output for array plugin

yaml

Plugin: Uniform Resource Identifiers (URIs)

Parameter	Notes
isComponent: boolean	Indicates whether the underlying value should be interpreted as a full URI or just a URI component.

Parameter	Notes
isComponent: boolean	Indicates whether the underlying value should be interpreted as a full URI or just a URI component.

Plugin: Universally Unique Identifiers (UUIDs)

Plugin: Value conversions

Bundles functionality for converting from one value type to another. This is referenced as name: convert.

string-to-boolean

Converts a set of string values to their boolean equivalent.

Supported conversions

'true' to true
'yes' to true
'no' to false
'false' to false
'null' to null

If the input value isn't a string or any of the values listed above, then the response returns undefined.

Also note that either single or double quotes are supported for any of the string values.

There aren't any required or optional parameters for string-to-boolean.

Example

Example: String-to-boolean input

yaml

1
"yes"

Example: String-to-boolean in config modifier

yaml

1
plugin:
2
  name: convert
3
  action: string-to-boolean

Example: String-to-boolean output

yaml

1
true

boolean-to-string

Converts a boolean value to its string equivalent.

Supported conversions

true to 'true'
false to 'false'

If the input value isn't a boolean, then the response returns undefined.

Also note that either single or double quotes are supported for either of the string values.

There aren't any required or optional parameters for boolean-to-string.

Example

Example: Boolean-to-string input

yaml

1
true

Example: Boolean-to-string in config modifier

yaml

1
plugin:
2
  name: convert
3
  action: boolean-to-string

Example: Boolean-to-string output

yaml

1
"true"

number-to-string

Converts a numeric value to its string equivalent.

Supported conversions

123 to '123'
-100 to '-100'
123.1 to '123.1'
9007199254740992 to '9007199254740992'

If the input value isn't numeric, then the response returns undefined.

Also note that either single or double quotes are supported for either of the string values.

There aren't any required or optional parameters for number-to-string.

Example

Example: Number-to-string input

yaml

1
1

Example: Number-to-string in config modifier

yaml

1
plugin:
2
  name: convert
3
  action: number-to-string

Example: Number-to-string output

yaml

1
"1"

string-to-number

Converts a string value to a numeric value.

Supported conversions

'123' to 123
'-100' to -100
'123.1' to 123.1
'9007199254740992' to 9007199254740992

If the input value isn't a string, then the response returns undefined.

Also note that either single or double quotes are supported for either of the string values.

There aren't any required or optional parameters for string-to-number.

Example

Example: String-to-number input

yaml

1
"1"

Example: String-to-number in config modifier

yaml

1
plugin:
2
  name: convert
3
  action: string-to-number

Example: String-to-number output

yaml

1
1

Phone numbers

Identifier	Output as E.164
+18001234567	+18001234567 (stays the same)
800.123.4567	+18001234567
800-123-4567	+18001234567
800 123 4567	+18001234567
tel:+1-800-123-4567	+18001234567
8001234567	+18001234567
(800) 123-4567	+18001234567
18001234567	+18001234567
(800) 123-4567ext987	+18001234567

Identifier	Example
e164	+18001234567
international	+1 800-123-4567
national	(800) 123-4567
rfc3966	tel:+1-800-123-4567
significant	8001234567

Dates with time

Standard

Identifier	Example(s)
HL7	20220729114900 20220729114900.123 20220729114900-0600
ISO	2016-05-25T09:08:34.123 2016-05-25T09:08:34.123-06:00
HTTP	Sun, 06 Nov 1994 08:49:37 GMT Sunday, 06-Nov-94 08:49:37 GMT Sun Nov 6 08:49:37 1994
SQL We currently only render with offsets, not timezones	2017-05-15 09:12:34 2017-05-15 09:12:34.342-06:00 2017-05-15 09:12:34.342 America/Los_Angeles
milliseconds Number of milliseconds since January 1, 1979 at midnight UTC/GMT	1659095340000
seconds Number of seconds since January 1, 1979 at midnight UTC/GMT	1659095340
RFC2822 We currently only render date-times that look like Fri, 29 Jul 2022 11:49:00 +0000	25 Nov 2016 13:23:12 GMT Fri, 25 Nov 2016 13:23:12 +0600 25 Nov 2016 13:23 Z

Custom

Custom formats

A custom format is a build-your-own format. You can use commonly used tokens to build a format that suits your needs. These formats aren't recognized as industry-regulated, but the tokens are well known, all the same.

You can use either a custom or standard format, not both.

Token	Description	Example output
S	millisecond, no padding	54
SSS	millisecond, padded to three	05
s	second, no padding	4
ss	second, padded to two padding	04
m	minute, no padding	7
mm	minute, padded to two	07
h	hour in 12-hour time, no padding	1
hh	hour in 12-hour time, padded to two	01
H	hour in 24-hour time, no padding	13
HH	hour in 24-hour time, padded to two	13
Z	narrow offset	+5
ZZ	short offset	+05:00
	techie offset	+0500
z	IANA zone	America/New_York
a	meridiem	AM
d	day of the month, no padding	6
dd	day of the month, padded to two	06
EEE	day of the week, as an abbreviated localized string	Wed
EEEE	day of the week, as an unabbreviated localized string	Wednesday
M	month as an unpadded number	8
MM	month as a padded number	08
MMM	month as an abbreviated localized string	Aug
MMMM	month as an unabbreviated localized string	August
yy	two-digit year, interpreted as >1960	14
yyyy	four-digit year	2014
D	localized numeric date	9/6/2014
DD	localized date with abbreviated month	Aug 6, 2014
DDD	localized date with full month	August 6, 2014
DDDD	localized date with full month and weekday	Wednesday, August 6, 2014

Dates

8. plugin

Definition

Nesting level

Common plugins

Accepted formats