a!toJson() Function

Converts a value into a JSON string.

Parameters

a!toJson( value, removeNullOrEmptyFields, useTextForPreciseDecimals )

Keyword	Type	Description
value	Any Type	The value to convert into a JSON string.
removeNullOrEmptyFields	Boolean	Determines whether fields with values that are null, empty strings, or empty arrays are removed from the JSON output. Default: false.
useTextForPreciseDecimals	Boolean	Determines whether Number (Decimal Precise) values are represented as quoted strings in the JSON output. When false, Number (Decimal Precise) values are represented as unquoted numbers. Default: false.

Returns

Text

Using the function

The following sections cover important details about the a!toJson() function.

Using the value parameter

The value parameter in a!toJson() must be a record, a dictionary, a map, a CDT, or a list.

Using the removeNullOrEmptyFields parameter

The removeNullOrEmptyFields parameter removes all fields with values that are null, empty strings, or empty arrays from the generated JSON request body. This is important for certain web services, such as those that follow the OData protocol. Some web services treat fields with null values differently from fields that aren't included in the request body at all. Omitting a field may mean "don't modify the field," while sending a null value for that field would mean "write a null value to the field."

The behavior of removeNullOrEmptyFields can also be leveraged for integrations that send a JSON request body by selecting the checkbox labeled Remove fields with null or empty values from generated JSON.

Using the useTextForPreciseDecimals parameter

The useTextForPreciseDecimals parameter controls how a!toJson() represents Number (Decimal Precise) values in the JSON output. Number (Decimal Floating) and Number (Integer) values are not affected.

Depending on the parameter value, the following occurs:

• true: Number (Decimal Precise) values are output as quoted strings (for example, "412.97"). Use this setting when the receiving system supports high-precision string-encoded numbers.
• false (default): Number (Decimal Precise) values are output as unquoted numbers (for example, 412.97). Use this setting when the receiving system expects standard JSON numbers.

Feature compatibility

The table below lists this function's compatibility with various features in Appian.

Feature	Compatibility	Note
Portals	Incompatible
Offline Interfaces	Incompatible
Sync-Time Custom Record Fields	Incompatible
Real-Time Custom Record Fields	Incompatible	Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.
Process Reports	Incompatible	Cannot be used to configure a process report.
Process Events	Partially compatible	If autoscale is enabled, can be used to configure a supported process event node (such as a start event or timer event).
Process Autoscaling	Compatible	Can be used in autoscaled processes.
Event Consumer Filter Conditions	Incompatible	Cannot be used in filter conditions.
Event Consumer Event Handlers	Compatible	Can be used in event handler expressions.

Old versions

There are older versions of this function . You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.

Old Versions	Reason for Update
a!toJson_17r1	Improved support for datetime values. This removes the need to create a supporting conversion rule.
a!toJson_26r9	Support the Number (Decimal Precise) data type.

To use the latest version of the function, replace the function with a version suffix with a new function reference.

To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.

Feedback