Shared State Task

To temporarily store a single value for Processes, Shared State Task can be used. It's commonly needed to either keep a changing value in memory over multiple executions, or pass a value to another Process asynchronously, which becomes easy when using local cache. Instead of more static storage such as Environment Variables, or more complex setup using separate database or file storage, Shared State abstracts the storage into simple key-value pairs to save and query.

What is Shared State Task?

Shared State can be used as a local cache in Frends Processes, to save string values into a database for specified duration, using a key to identify the value later. It can be chosen by the developer whether the value is available for all Processes in the same Agent Group, or only to the current Process being developed.

Same shape can be adjusted to perform different operations on the Shared State. One Shared State Task can then be used to read a value from Shared State using the specified key, and another can be used to store a value for that key. Other operations also include extending the Time To Live (TTL) value for the key, as well as update or delete the key and value with it.

Types of Shared State Task

While there is only one Shared State Task shape in Frends, which always stores the values to the same place, the shape has multiple operations it can perform.

AddOrUpdate

This operation updates an existing value with the specified key, or creates a new key and value pair, if the key does not yet exist. Essentially ensures that after this operation, a key with the specified value will exist for the specified duration.

GetOrAdd

Instead of updating a value for an existing key, it will retrieve the value if the key exists. Otherwise, it will create a new key and value pair with the specified values. This operation makes sure that any existing value will not be overwritten, but the key will exist and contain a value after the operation.

TryAdd

Creates a new key and value pair, as long as the key doesn't exist yet. Will not overwrite or return a value from existing key.

TryGetValue

If the specified key exists, returns its value.

TryRemove

Deletes a key and its value, if it exists.

TryUpdate

Updates a value for the specified key in the store, but will not create a new key value pair, if the key does not yet exist. Will also reset the Time To Live (TTL) value for the key value pair.

GetTTL

Retrieves the Time To Live (TTL) value for the specified key, giving information about for how long the key will still exist. Won't update the key value pair or its TTL value.

UpdateTTL

Resets the Time To Live (TTL) value for the specified key value pair, to the specified duration.

Usage

In order to use Shared State Task, add it to your Process canvas and connect it as part of your Process using two Sequence flows. Like other Tasks, Shared State Task must be connected between Trigger and a Return or a Throw shape, i.e. the Proces cannot start or end with a Task.

Once added to your Process, configure the shape's name and Shared State operation from the list. Then you can define the values for the key, value and the pair's TTL value, slightly varying what fields are available by the operation selected. You can also optionally make the value available to all Processes in the Agent Group, or only to this one Process.

Architecture

Shared State storage in Frends is based on the configured database for each Agent Group. Sharing the stored values between multiple Agents requires a shared database all the Agents can connect to. If a centralized and shared database is not used for storing the configuration data, but instead each Agent uses a local SQLite database, sharing the Shared State values between Agents is not possible.

For concurrency in High Availability configuration, SQL Server is recommended to be used to ensure consistency in the data. Because SQLite is file-based database, concurrent access to the data is not possible due to file locking scenarios, which can cause issues in Processes running at the same time.

Configuration

To set up a Shared State Task, add the shape to Process canvas and connect it as part of your Process. After that, you can configure the parameters for the shape.

The following configuration parameters are available for Shared State Task.

Display name

Shapes can be given a display name in Frends Processes to distinquish them from each other. Shape's display name has no technical purpose and is only for documentational and visual purposes only. For shapes returning a #result reference value, the display name can be used to specify which result is meant.

Display name is given to the shape by double-clicking it on the canvas or through its configuration parameters.

Type

Shared State Task's operation specifies what the shape does and thus what configuration parameters it has available. You can check the possible types at Types of Shared State Task section of this article.

Key

Key specifies the name of the value in Shared State storage, by which it can also be fetched or targeted for operations. Allows purely textual value or C# expression, as well as Handlebars syntax with text values, to make the keys more dynamic in nature.

Value

If the operation supports entering a value to insert or update a key with, Value parameter will be available. Any data can be written to Shared State storage as long as it is JSON serializable. This is the content that can be retrieved with the Key.

Time To Live (TTL)

Time duration specifying how long the key-value pair will exist in the Shared State storage. Specified as number of minutes or hours, at minimum the value is one minute. Maximum TTL value is 30 days, meaning 720 hours.

Update operations allow refreshing the TTL value, resetting the remaining TTL to whatever is specified for the Shared State operation.

Throw an exception on failure

When enabled, the shape will throw an exception If the Shared State operation fails for some reason, for example TryAdd is used but the key already exists. The Process execution will end to the thrown exception, unless caught with a Catch shape. If this parameter is not enabled and the operation fails, the Shared State Task's result will contain the information that the operation failed.

Available for all Processes in Agent Group

When enabled, the key-value pair stored in this Process is available in other Processes as well. Requires a shared database between Agents for multiple Agents to access the values.

This option needs to be also enabled in other Shared State Tasks for them to be able to access a value that is created with this parameter enabled.

Skip logging result and parameters

Toggle option to select if the values of this shape should be included in logging or not. Default is false. If set to true, Process Instance logs will show the result and parameter values of this shape as << Omitted >>.

Promote result as

Toggle option to select if the result value of this shape should be promoted in the Process Instance list, and an text input field if set to true. Default is false. Promoted values appear in the Process Instance list in their own column along with error and result values. Promoted value column is named with the text input field appearing when this is set to true.

Promoted values are always logged fully in the Process Instance view, regardless of the log level settings.

Reference Values

Shared State Task provides a #result reference value, which contains its operation's result values.

#result

#result reference value can be used to access earlier shape's return value. For Scope shapes, the value is specified using Return shape, while for Task's the #result is populated directly by the Task.

When Return shape is used to end Foreach or While shapes, the expression or HTTP content values in Return shape are available through #result reference value as an array of values for each iteration.

#result reference value by default references the last Task's or Scope shape's return value. Instead of unnamed #result reference, you can also use named #result reference value.

Named #result

Named #result reference value is used with square brackets, much like dictionary's or object's fields would be used, such as #result[Handle elements] or #result[HTTP Request]. This way it can be specified which shape's result you are using.

When using named #result reference value with Scope shapes and Return shapes, it should be noted that the #result reference value is named by the Scope shape and not by the Return shape, although the value is specified in the Return shape. Thus, when using the named #result value, such as #result[Handle elements], the Scope shape's name should be used.

#result.Success (Bool)

Boolean value indicating whether the operation was successful or not. For example, when retrieving a value using TryGetValue, the operation is deemed failed if the key does not exist. It is successful however, if the key exists but it does not have a value.

#result.Value (Dynamic)

Value assigned to the key that was being retrieved from or inserted to Shared State storage. Data type will be dynamic. Data stored into Shared State must be JSON serializable, so the resulting value is also usable as a JSON value.

#result.Message (String)

Textual information about the Shared State Task's execution to help with development and debugging.