Redaguoti

Bendrinti naudojant


How to use custom functions with the MedTech service device mapping

Many functions are available when using JMESPath as the expression language. Besides the built-in functions available as part of the JMESPath specification, many more custom functions can also be used. This article describes how to use the MedTech service-specific custom functions with the MedTech service device mapping.

You can use the MedTech service Mapping debugger for assistance creating, updating, and troubleshooting the MedTech service device and FHIR® destination mappings. The Mapping debugger enables you to easily view and make inline adjustments in real-time, without ever having to leave the Azure portal. The Mapping debugger can also be used for uploading test device messages to see how they'll look after being processed into normalized messages and transformed into FHIR Observations.

Function signature

Each function has a signature that follows the JMESPath specification. This signature can be represented as:

return_type function_name(type $argname)

The signature indicates the valid types for the arguments. If an invalid type is passed in for an argument, an error occurs.

Important

When math-related functions are done, the end result must be able to fit within a C# long value. If the end result is unable to fit within a C# long value, then a mathematical error will occur.

As stated previously, these functions can only be used when specifying JmesPath as the expression language. By default, the expression language is JsonPath. The expression language can be changed when defining the expression.

For example:

"templateType": "CalculatedContent",
    "template": {
        "typeName": "heartrate",
        "patientIdExpression": {
            "value": "insertString('123', 'patient', `0`) ",
            "language": "JmesPath"
        },
        ...
    }

This example uses the insertString expression to generate the patient ID patient123.

Literal values

Constant values can be supplied to functions.

  • Numeric values should be enclosed within backticks: `
    • Example: add(`10`, `10`)
  • String values should be enclosed within single quotes: '
    • Example: insertString('mple', 'sa', `0`)

For more information, see the JMESPath specification.

Exception handling

Exceptions can occur at various points within the device data processing lifecycle. Here are the various points where exceptions can occur:

Action When Exceptions that can occur during parsing of the device mapping Outcome
Device mapping parsing Each time a new batch of device messages are received, the device mapping is loaded and parsed. Failure to parse the device mapping. System attempts to reload and parse the latest device mapping until parsing succeeds. No new device messages are processed until parsing is successful.
Device mapping parsing Each time a new batch of device messages are received, the device mapping is loaded and parsed. Failure to parse any expressions. System attempts to reload and parse the latest device mapping until parsing succeeds. No new device messages are processed until parsing is successful.
Function execution Each time a function is executed against device data within a device message. Input device data doesn't match that of the function signature. System stops processing that device message. The device message isn't retried.
Function execution Each time a function is executed against device data within a device message. Any other exceptions listed in the description of the function. System stops processing that device message. The device message isn't retried.

Mathematical functions

add

number add(number $left, number $right)

Returns the result of adding the left argument to the right argument.

Examples:

Given Expression Result
n/a add(`10`, `10`) 20
{"left": 40, "right": 50} add(left, right) 90
{"left": 0, "right": 50} add(left, right) 50

divide

number divide(number $left, number $right)

Returns the result of dividing the left argument by the right argument.

Examples:

Given Expression Result
n/a divide(`10`, `10`) 1
{"left": 40, "right": 50} divide(left, right) 0.8
{"left": 0, "right": 50} divide(left, right) 0
{"left": 50, "right": 0} divide(left, right) mathematic error: divide by zero

multiply

number multiply(number $left, number $right)

Returns the result of multiplying the left argument with the right argument.

Examples:

Given Expression Result
n/a multiply(`10`, `10`) 100
{"left": 40, "right": 50} multiply(left, right) 2000
{"left": 0, "right": 50} multiply(left, right) 0

pow

number pow(number $left, number $right)

Returns the result of raising the left argument to the power of the right argument.

Examples:

Given Expression Result
n/a pow(`10`, `10`) 10000000000
{"left": 40, "right": 50} pow(left, right) mathematic error: overflow
{"left": 0, "right": 50} pow(left, right) 0
{"left": 100, "right": 0.5} pow(left, right) 10

subtract

number subtract(number $left, number $right)

Returns the result of subtracting the right argument from the left argument.

Examples:

Given Expression Result
n/a subtract(`10`, `10`) 0
{"left": 40, "right": 50} subtract(left, right) -10
{"left": 0, "right": 50} subtract(left, right) -50

String functions

insertString

string insertString(string $original, string $toInsert, number pos)

Produces a new string by inserting the value of toInsert into the string original. The string is inserted at position pos within the string original.

If the positional argument is zero based, the position of zero refers to the first character within the string.

If the positional argument provided is out of range of the length of original, then an error occurs.

Examples:

Given Expression Result
n/a insertString('mple', 'sa', 0) "sample"
{"original": "mple", "toInsert": "sa", "pos": 0} insertString(original, toInsert, pos) "sample"
{"original": "suess", "toInsert": "cc", "pos": 2} insertString(original, toInsert, pos) "success"
{"original": "myString", "toInsert": "!!", "pos": 8} insertString(original, toInsert, pos) "myString!!"

Date functions

fromUnixTimestamp

string fromUnixTimestamp(number $unixTimestampInSeconds)

Produces an ISO 8061 compliant time stamp from the given Unix timestamp. The timestamp is represented as the number of seconds since the Epoch (January 1 1970).

Examples:

Given Expression Result
{"unix": 1625677200} fromUnixTimestamp(unix) "2021-07-07T17:00:00+0"
{"unix": 0} fromUnixTimestamp(unix) "1970-01-01T00:00:00+0"

fromUnixTimestampMs

string fromUnixTimestampMs(number $unixTimestampInMs)

Produces an ISO 8061 compliant time stamp from the given Unix timestamp. The timestamp is represented as the number of milliseconds since the Epoch (January 1 1970).

Examples:

Given Expression Result
{"unix": 1626799080000} fromUnixTimestampMs(unix) "2021-07-20T16:38:00+0"
{"unix": 0} fromUnixTimestampMs(unix) "1970-01-01T00:00:00+0"

Tip

See the MedTech service article Troubleshoot errors using the MedTech service logs for assistance fixing errors using the MedTech service logs.

Next steps

Overview of the MedTech service device mapping

Overview of the MedTech service FHIR destination mapping

Overview of the MedTech service scenario-based mappings samples

Note

FHIR® is a registered trademark of HL7 and is used with the permission of HL7.