Associate Payload with Correct UID Node Configuration Guide

The Associate Payload with Correct UID Node is designed to intelligently map incoming data to the correct device using values within the payload itself. This is particularly useful when working with array-based or nested data structures where the UID

What It Does

This node extracts or constructs a UID from within the incoming JSON payload, then uses that UID to associate the data with the corresponding device in the system. It can also handle arrays, apply filters, and repackage the data so each item in an array becomes its own payload, if desired.

In addition, the node can assign a timestamp to each payload based on a value found in the payload, ensuring that all data entering Rayven is accurately time-stamped.

 Step-by-Step: How to Configure the Associate Payload with Correct UID Node

1. Add the node

Drag the Associate Payload with Correct UID node onto the canvas from the Transformers section.

2. Define the node name

Give your node a clear name that reflects its role in the workflow (e.g., "UID Mapper - Weather Sensor").

3. Configure UID extraction

Set the Incoming UID JSON key (e.g., meta.device_info.serial).
If this key leads to a compound string, use Delimiter (e.g., :) and Index to extract the correct portion. Indexing starts at 0.

4. Choose UID assignment strategy

• Enable Use incoming UID + extracted string to concatenate both.

• Enable Use JSON Key as UID to assign the extracted string directly as UID.

5. Handle arrays (optional)

• Enable Split Array if the payload contains an array of objects.

• Specify the Array JSON key that points to the array field (e.g., data.sensors).

6. Filter payload contents (optional)

• Use Filter by JSON key to limit which objects are processed.

• Enter the Filter value (e.g., "type": "temperature").

7. Output control

• Enable Single payload per matching object to emit one payload per object.

• Set Interval between output payloads (ms) to throttle flow if needed (e.g., 500 ms).

8. Timestamp assignment (optional)

• Enable Associate Payload with Timestamp from JSON.

• Provide the Timestamp JSON key (e.g., data.timestamp) and Timestamp format (e.g., yyyy-MM-dd HH:mm:ss).

• Set Time zone to ensure consistency with other data sources.

9. Export support

Enable Store data for Node Export capability if downstream tools need to reference the transformed payloads.

 Configuration Fields

 Example: Mapping a Sensor Array to Device UIDs

Payload Input:

Configuration:

• Incoming UID JSON key: meta.device_info.serial

• Delimiter: :

• Index: 1

• Use JSON Key as UID: ✅

• Split Array: ✅

• Array JSON key: data.readings

• Filter by JSON key: type

• Filter value: temperature

• Single payload per matching object: ✅

• Timestamp JSON key: timestamp

• Timestamp format: yyyy-MM-dd HH:mm:ss

• Time zone: America/Los_Angeles

Result:
A single payload is emitted with the UID SF001, containing only the temperature reading, correctly timestamped for Rayven’s processing engine.

 Best Practices

• Keep UID extraction logic simple—flatten nested keys if needed before this node.

• When filtering array contents, use exact keys/values to avoid accidental exclusions.

• Validate timestamp formatting with a sample payload before enabling.

 Use Cases

• Normalize third-party sensor payloads with embedded UIDs.

• Reassign bulk data arrays to Rayven devices.

• Add timestamps to raw payloads before entering data storage.

• Filter only relevant sensor types from multi-sensor arrays.

 FAQ

Q: What happens if the extracted UID doesn't match any Rayven device?
A: The payload is dropped unless fallback or routing nodes are configured.

Q: Can this node handle nested arrays?
A: No, it supports single-level arrays only. Preprocess deeper structures beforehand.

Q: What timestamp formats are supported?
A: Standard formats like ISO 8601, yyyy-MM-dd HH:mm:ss, and Unix timestamps are supported. Ensure the format matches the incoming string exactly.