V2NodesKey/Value
Key/Value
V2

Key/Value

Store and retrieve small key/value records inside the current site environment.

Revision History

0.0.0.1 - Initial release.
0.0.0.6 - Added support for reading legacy compressed values.
0.0.0.8 - Added single-record SetSingle and GetSingle methods.

Setup Notes

You can add this Node to a Workflow without configuring authentication or external access.

Use this Node when you need to keep a simple lookup table in Flowgear, such as matching a source system ID to the corresponding ID in a target system.

  • Key/value records are scoped to the current site environment. A record written in one environment is not available in another environment, unless you write it there as well.
  • Use Group to separate unrelated records. For example, you might use one group for customer IDs and another for invoice numbers.
  • Use stable Group names so you can reuse the same lookup set across multiple Workflows.
  • Group and Key are required and each can be up to 1000 characters long.
  • Values are stored as text. The maximum value size is 32 KB.
  • Each record is timestamped when it is written.

Methods

This Node provides batch and single-record methods for writing values, reading values in a date range, and reading one key directly.

Set

Creates or updates multiple key/value records in a group.

Each item includes a Key, Value, and optional Status. If you do not provide a Status, the Node stores Unknown.

Parameter Type Description
Group String The name of the group that the records belong to.
Items Array The collection of records to create or update. Each item includes Key, Value, and optional Status.
Items.Key String The key to create or update. This value is required and can be up to 1000 characters long.
Items.Value String The value to store for the key. The maximum size is 32 KB.
Items.Status String Optional status metadata for the record. If omitted or blank, the Node stores Unknown.

This method does not return a value.

SetSingle

Creates or updates one key/value record in a group.

If you provide a blank Status, the Node stores Unknown.

Parameter Type Description
Group String The name of the group that the record belongs to.
Key String The key to create or update. This value is required and can be up to 1000 characters long.
Value String The value to store for the key. The maximum size is 32 KB.
Status String Status metadata for the record. If blank, the Node stores Unknown.

This method does not return a value.

Get

Gets the latest value for each key in a group whose stored timestamp falls within a specified range.

DateFrom and DateTo are inclusive. DateFrom must be earlier than or equal to DateTo. If DateFrom is later than DateTo, the Node throws an error.

Parameter Type Description
Group String The group to query.
DateFrom DateTime The inclusive start of the date range to query.
DateTo DateTime The inclusive end of the date range to query.
Return Type Description
Items Array The latest matching record for each key in the group, returned in key order.
Items.Key String The key for the returned record.
Items.Value String The stored value for the key.
Items.Status String The status stored with the key.
Items.Timestamp DateTime The UTC date and time when the record was written.

GetSingle

Gets the current value for one key in a group.

Parameter Type Description
Group String The group to query.
Key String The key to retrieve.
Return Type Description
Item Object The matching record, or no value if the key does not exist.
Item.Key String The key for the returned record.
Item.Value String The stored value for the key.
Item.Status String The status stored with the key.
Item.Timestamp DateTime The UTC date and time when the record was written.

Usage Notes

  • Use Set when you need to write several records. Use SetSingle when you only need to write one record.
  • Use Get when you need records written in a specific date range. Use GetSingle when you need the current value for a known key.
  • If you write the same Key more than once, Get returns the latest matching record for that key in the requested date range.
  • Use the Status field as lightweight metadata when you want to track the state of a record alongside the stored value.
  • The date range filter is based on the stored UTC timestamp. Use UTC-aware values for DateFrom and DateTo when you need precise results.
  • Legacy compressed values are decompressed automatically when they are read.
  • The Node stores values as text. Store a smaller value or use a relational database when you need to associate more data with the key.

Examples

Store source and target identifiers

After a Workflow creates a record in a target system, use SetSingle to store the source record ID as the Key and the target record ID as the Value.

Later, use GetSingle to look up the stored target ID before you send an update.

Track the latest status for a record

Use Set to store the same Key with a new Value or Status each time processing changes.

Use Get with a suitable date range when you need the latest stored state for each key in the group.

See Also