Safe_mode

Safe_mode is used precautiously in order to prevent the transformation from breaking. More specifically, the function changes the behavior of a potential exception within the transformation block so it returns null instead of breaking the entire transformation.

Syntax

safe_mode($input, &expression)

Evaluates $input against an &expression. In case of an exception, it changes the exception’s behavior to result in null instead of an invalid transformation and treats error messages as warnings.

Parameters

$input: The key, object, or array that is used as data for the expression.
&expression: The expression that is used for the evaluation.

Example

In the dataset below two key-value pairs are presented. It is worth noticing how one of them has a string value while the other one has a number value.

{
    "a": "none", //string value
    "b": 89  //number value
}

In the transformation below, the sum function that is used to calculate the sum of the two key-value pairs throws an exception as it doesn’t support string values. Thus, it returns null and an invalid transformation error.

{
    SUM:sum([a,b])
}

If the safe_mode function is used in the above-mentioned key (as seen in the transformation below), then, even though it will still return null, instead of an invalid transformation error, a warning message is generated. This is achieved, because of the safe_mode function.

{
    SUM:safe_mode(@, &sum([a,b]))
}

In this example, both cases have the same result which is presented in the code block below:

{
    "SUM": null  //returns null since sum doesn't support string values
}

Notes

While the above example is quite simple, it clearly demonstrates the use of the safe_mode function, even though both of the above transformations have the same result. Usually, safe_mode is used in combination with User Functions or when a Connected Service is called using the service function, as these may throw an exception that is not visible or controllable within the transformation block and which could prevent DocuMotor from generating any output. For example, it can be something that breaks in a User Function’s body or an authentication error related to a connected service. By using safe_mode in such cases (in the same way as demonstrated above), it works like a safety net that ensures that an output will be generated.