Object set conditions

The Automate application offers multiple different object set conditions that allow users to automatically trigger effects when object data changes in a predefined object set.

Object data changes can come from the backing dataset, from Action types, or from external applications.

Depending on the evaluation latency, data changes may be picked up by an automation within minutes or within an hour. Learn more in the evaluation latency section.

Moreover, certain object set conditions expose effect input parameters. These are variables that can be used inside of effects to, for example, access the objects that triggered the automation. The type of parameter depends on the execution mode and the condition.

There are currently five different condition types that operate on object sets:

• Objects added to set: Triggers when a new object appears in an object set.
• Objects removed from set: Triggers when an object leaves an object set.
• Objects modified in set: Triggers when an object is modified in an object set.
• Metric changed: Triggers when an aggregated metric increases or decreases.
• Threshold crossed: Triggers when a metric threshold is crossed or when a function returns true.

Object set definition

Most object set condition types require you to start by specifying an object set to monitor. You can either dynamically define an object set in the user interface, select a saved object set, or select a function that returns an object set. Once you've defined the object set you want to monitor, use the preview button to validate that it includes the expected objects.

When dynamically defining an object set, start by selecting your desired object type. Then, you can optionally add filters to narrow down the monitored object set. For example, the Support Ticket object type shown below is further narrowed to only monitor objects with the Status Open. When no filters are selected, you are monitoring all objects of that type. The selected object type and filters influence whether the object set can be monitored live or scheduled. Learn more about this in the evaluation latency section.

Function-generated object sets

The example below uses a Function to return the 10 highest priority tickets. Used in an "objects added" condition, the effects will run whenever a new ticket enters this set. Note that a function must return an ObjectSet<T> to be used here.

Copied!
1
2
3
4
5
6
7
8
9
10
11
/**
 * This function returns the 10 most recent highest priority tickets
 */
@Function()
public get10HighestPrioritySupportTickets(): ObjectSet<DemoTicket> {
    const highPriority = Objects.search()
    .demoTicket()
    .orderBy(ticket => ticket.timestamp)
    .orderBy(ticket => ticket.priority)
    .take(10);
}

Learn more about authoring a Function to use with Automate and see the example function in this section.

Condition types

This section provides more detailed information on the individual object set condition types.

Objects added to set

The Objects added to set condition triggers every time an object gets added to your predefined object set. Start by specifying your object set according to the object set definition section above.

In case you specified an object set filter, new objects or object edits from users may trigger your objects added to set condition. In the example shown below, we monitor an object set of Support Tickets with status property value Open. There are two ways how the condition could be triggered: either a new Support Ticket object with status Open is created, or an existing Support Ticket changes its status to Open.

If you do not specify any filters on the object set, you are effectively monitoring all objects of the type. That means the automation will only trigger for completely new objects being added to the ontology.

After setting up the object set definition, you can also define the execution mode for effects. By default batched execution will be selected. Learn more about the different execution modes.

The Objects added to set condition exposes objects that triggered the condition as an effect input. Depending on the selected execution mode, this can be either a single Added object or an object set of Added objects. Learn more about how to use effect inputs.

The supported evaluation latency for this condition type is:

• Live evaluation
• Scheduled evaluation

Objects removed from set

The Objects removed from set condition triggers every time an object gets removed from your predefined object set. Start by specifying your object set according to the object set definition section above.

In case you specified an object set filter, object edits from users may trigger your objects removed from set condition. For example, if we monitor an object set of Support Tickets with status property value Open, then the condition will trigger when the the status of an Open ticket changes to any other status.

After setting up the object set definition, you can also define the execution mode for effects. By default batched execution will be selected. Learn more about the different execution modes.

The Objects removed from set condition exposes objects that triggered the condition as an effect input. Depending on the selected execution mode, this can be either a single Removed object or an object set of Removed objects. Learn more about how to use effect inputs.

The supported evaluation latency for this condition type is:

• Live evaluation
• Scheduled evaluation

Objects modified in set

The Objects modified in set condition triggers every time an object gets modified in your predefined object set. This condition type is appropriate if you are looking to monitor any property value change in an object set. When you are looking to trigger an automation when an object is changed to a specific value, the object added to set condition is a better choice.

Start by specifying your object set according to the object set definition section above. After defining your object set, you can limit the properties you want to watch as shown in the image below. When no properties are selected, any property change in the monitored object set will trigger the automation.

Additionally, you can specify Include objects added and Include objects removed. These options control whether modifications on objects that are simultaneously added to (or removed from) the monitored object set will be considered a modification and trigger the automation. That means when disabling both options, only objects that already were in the object set and that remain in the object set after modification will trigger the automation.

In the example shown below, we are monitoring the status of Support Ticket objects that belong to the location USA. We enabled Include objects added and disabled Include objects removed. This means that Support Ticket objects that were deleted would not trigger the automation, because they leave the monitored object set. The same applies to tickets whose status property changes while the location changes, for example, to UK; because they leave the object set and Include objects removed is disabled, the automation would not trigger. However, we are counting objects that were added to the object set as modified because Include objects added is enabled. Thus, a Support Ticket object that changes its location from UK to USA would trigger the automation. The same applies to newly created objects with the location USA.

After setting up the object set definition, you can also define the execution mode for effects. By default batched execution will be selected. Learn more about the different execution modes.

The Objects modified in set condition exposes objects that triggered the condition as an effect input. Depending on the selected execution mode, this can be either a single Modified object or an object set of Modified objects. Learn more how to use effect inputs in the effect sections.

The supported evaluation latency for this condition type is:

• Live evaluation

Metric changed

The Metric changed condition triggers every time an object set metric changes in a predefined object set. Example metrics are the total count of objects in the set, or aggregations like the average of numeric object property values. Start by specifying your object set according to the object set definition section above.

Next, you can select the metric property. You can either choose:

• Total count of objects in object set; or
• The average, max, min, or sum of a specific numeric property from across the entire monitored object set

Then, select either Increases or Decreases as the change type.

For the example shown below, the automation would trigger whenever the average value of the carbon monoxide property over all air quality sensors in New York increases.

The supported evaluation latency for this condition type is:

• Scheduled evaluation

Threshold crossed

With the Threshold crossed condition you can define a set of checks that return true or false over time. When all checks return true, the threshold is considered crossed. Effects are triggered and activity is recorded whenever the threshold is crossed in either direction.

You can compose condition items that consist of UI-defined logic and function-backed logic.

The supported evaluation latency for this condition type is:

• Scheduled evaluation

UI defined

To define a threshold condition item via UI, click Add condition and select Condition as condition type. Next, you need to specify a saved object set. Then, depending on the object type of the saved object set, you can select a property that you want to compare. Afterward, select a comparison operator, and finally a metric or static value to compare against.

An example threshold crossed condition that is defined in the user interface is shown below. In this example, the condition checks for when the maximum value across all air quality sensors in New York is less than 0.05.

Function backed

Instead of defining the condition items via UI, you can also use the function condition type. Function-backed conditions are designed to allow more complex condition definitions, including anything not supported by the default threshold rule options. Function-backed conditions work by defining and publishing a function that returns a single Boolean value of true or false. The function will be called when the monitor is evaluated, and the response must indicate the result for that execution. If the status has changed, an event will be recorded.

Learn more about authoring a Function to use with Automate and see the example function in this section.

The example below uses a Function to compute whether more than fifty percent of air quality sensors are unhealthy. If that is the case, it returns true otherwise false.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
/**
 * This function calculates whether more than fifty percent of the passed air quality sensors are considered unhealthy.
 * A sensor is considered unhealthy when the carbon monoxide value passes `0.05`.
 */
@Function()
public async areMoreThanFiftyPercentOfSensorsUnhealthy (airQualitySensors: ObjectSet<automateExampleAirQualitySensor>): Promise<boolean> {
    const totalSensorCount = await airQualitySensors.count();
    const unhealthySensorCount = await airQualitySensors.filter(sensor => sensor.carbonMonoxide.range().gt(0.05)).count();
    if (totalSensorCount === null) {
        return false;
    }

    return ((unhealthySensorCount ?? 0) / totalSensorCount) > 0.5;
}

Objects exist in set

The Objects exist in set condition can be set up to periodically trigger an automation on an entire object set. This condition is configured in combination with a schedule.

When using this condition, affected object parameters can be set up to inject objects into any effects. Batch size and parallelization settings are respected when using this condition. This condition allows you to run an effect over a large set of objects while avoiding function or action timeouts, since batching will be handled.