# Payload Templating

{% hint style="info" %}
Payload templating allows the customization of the payload of output connectors, rule actions, and access data of the uplink as well as other metadata by making use of a templating language.

The templating language can be used to add properties of the sample to the e-mail action body and subject.
{% endhint %}

### Usage

To trigger the suggestions in the UI, simply enter double open curly brackets (`{{`) in the input field which will show available options. Make sure to end the expression by adding double closing curly brackets (`}}`).

Enclosed in the curly brackets, the access to any data sample or other properties is done using the dot-notation.

Consider the following structure:

```json
{
    "data": {
        "time": "2021-03-02T11:37:00+000",
        "temp": 23.5,
        ...
    },
    ...
}
```

If e.g. the temperature value of the sample is to be added in the email body, the access to this value is as follows: `{{data.temp}}`.   

### JSON Payload Templating

If the target e.g. a Webhook requires a different JSON object structure, the custom payload can be used in combination with the templating syntax to achieve a completely new JSON structure.

Consider the following structure of the sample:

```json
{
    "data": {
        "time": "2021-03-02T11:37:00+000",
        "temp": 23.5,
        "state": "all ok",
        ...
    },
    ...
}
```

If the output to the webhook connector should look something like

```json
{
    "temp": 23.5,
    "time": "2021-03-21T11:37:00+000",
    "state": "all ok",
    ...
}
```

The following template will achieve this:

```json
{
    "temp": {{data.temp}},
    "time": {{data.time}},
    "state": {{data.state}},
    ...
}
```

NOTE: Previously all the templating expressions in JSON were enclosed in quotes in order to be a valid JSON object. This is no longer necessary since the templating engine will replace and encode/escape the value according to type.

### Supported Properties

The following properties are supported:

* `data.*` access any values of the sample
* `meta.*` access any values of the meta object
* `result.*` access any values of the custom rule logic result
* `uplinkMeta` the complete uplink meta-object. See Uplink Meta Properties for sub-properties
* `topic` the data topic
* `timestamp` the timestamp of the sample
* `deviceId` the unique device id of the device triggering the flow
* `akenzaDeviceId` the akenza device id of the device triggering the flow
* `correlationId` the correlation id of the flow
* `device` the complete device object. See Device Properties for sub-properties
* `rule` the complete rule object. See Rule Properties for sub-properties
* `uplinkMetrics` the complete uplink metrics object. See uplink metrics Properties for sub-properties
* `rawData` the complete raw data object. See raw data Properties for sub-properties. Only available for LoRa uplinks
* `dataSources` all data source objects involved in the triggered flow. See Data Source Properties for sub-properties

#### Device Properties

The following properties of a device can be accessed when using template syntax.

**Note**: The prefix `device.` is always required in order to access sub-properties.

* `name` the device name
* `description` the device description
* `integrationId` the integration Id of the device (only for LoRaWAN devices)
* `workspaceId` the workspace Id of the device
* `dataFlowId` the data flow Id of the device
* `connectivity` the connectivity of the device
* `id` the akenza device Id
* `deviceId` the unique device id
* `customFields.*` access Custom Fields values by their name

#### Rule Properties

The following properties of a rule can be accessed when using template syntax.

**Note**: The prefix `rule.` is always required in order to access sub-properties.

* `ruleId` the id fo the rule
* `name` the name of the rule (only for rules)
* `description` the description of the rule
* `workspaceId` the workspace Id of the rule

#### Data Source Properties

The following properties of a data source can be accessed when using template syntax.

To access a specific data source, use `dataSources.X` where `X` is the number of the data source as specified in the rule (starting at 1).

Some properties can be null in certain circumstances (e.g. the `correlationId` or the `device`) if e.g. the rule was triggered by a timer event or the data source is set to access the last sample.

**Note**: The prefix `dataSources.X.` is always required in order to access sub-properties.

* `correlationId` the correlation id of the data source (only available if the data source was triggering the flow)
* `device` the complete device object. See Device Properties for sub-properties
* `deviceId` the unique device id
* `akenzaDeviceId` the akenza device id
* `topic` the topic of the sample
* `timestamp` the timestamp of the sample
* `data.*` access any values of the sample
* `meta.*` access any values of the meta object
* `uplinkMeta` the complete uplink meta object
* `trigger` boolean indicates whether the data source has triggered the uplink
* `deviceInput` boolean indicates if the data source is a device
* `tagInput` boolean indicates if the data source is a tag

#### Uplink Meta Properties

The following properties of uplink metadata can be accessed when using template syntax

**Note**: The prefix `uplinkMeta.` is always required in order to access sub-properties.

* `dataReceived` the ISO-8601 timestamp when the data was received
* `bytesReceived` the number of bytes received in the uplink request
* `processingStart` the ISO-8601 timestamp when the processing was started
* `scriptRunUplinkStart` the ISO-8601 timestamp when script run was started
* `scriptRunUplinkEnd` the ISO-8601 timestamp when script run ended
* `processingEnd` the ISO-8601 timestamp when the processing ended
* `outputProduced` the ISO-8601 timestamp when all output was produced
* `uplinkDuration` the ISO-8601 duration of the whole uplink flow
* `processingDuration` the IOS-8601 duration of the processing
* `scriptRunningDuration` the ISO-8601 duration of the script run

#### Uplink Metrics Properties

The following properties of uplink metrics can be accessed when using template syntax

**Note**: The prefix `uplinkMetrics.` is always required in order to access sub-properties.

* `uplinkSize` the size of the uplink
* `timestamp`the ISO-8601 timestamp when the data was received
* `latitude` the latitude of the device
* `longitude` the latitude of the device
* `locationRadius` the error radius for the location
* `port` the port used when sending the uplink
* `frameCountUp` the frame count up of the uplink
* `frameCountDown` the frame count down of the uplink
* `rssi` the rssi of the uplink
* `snr` the snr of the uplink
* `sf` the spreading factor used to send the uplink
* `txPower` the tx power used to send the uplink
* `numberOfGateways` the number of gateways that received the uplink
* `esp` the esp of the uplink
* `sqi` the signal quality of the uplink
* `batteryLevel` the battery level of the device

#### Raw Data Properties

The following properties of raw data can be accessed when using template syntax

**Note**: The prefix `rawData.` is always required in order to access sub-properties.

* `port` the port of the unprocessed uplink
* `payloadHex` the hex payload of the unprocessed uplink