SkySpark by SkyFoundry

11. Actions

Overview

Actions provide a mechanism to invoke predefined arbitrary Axon expressions as user friendly commands. Actions are associated with a record using the actions tag which defines a table of actions available on that record. For example, on a writable point you might create actions to invoke manual overrides.

Actions are invoked using the the invoke Axon function and the invokeAction REST operation.

Actions Tag

Actions are registered on a record using the actions tag. This tag must be a string with a Zinc encoded grid of the action definitions. The following columns are supported:

You can add your own arbitrary tags to actions too. Typically this is done for customizing security.

Examples for mapping point writes into user actions:

// writable point
ver:"2.0"
dis,expr
"Manual Set","pointOverride($self, $val, $duration)"
"Manual Auto","pointAuto($self)"
"Emergency Set","pointEmergencyOverride($self, $val)"
"Emergency Auto","pointEmergencyAuto($self)"

// Bool writable point (on/off conveniences)
ver:"2.0"
dis,expr
"Manual On","pointOverride($self, true, $duration)"
"Manual Off","pointOverride($self, false, $duration)"
"Manual Auto","pointAuto($self)"
"Emergency On","pointEmergencyOverride($self, true)"
"Emergency Off","pointEmergencyOverride($self, false)"
"Emergency Auto","pointEmergencyAuto($self)"

Expr Macros

The expr column is a macro string where the variable names map to predefined types:

bool       Bool
number     Number
str        Str
date       Date
time       Time
dateTime   DateTime
duration   Number with duration unit
dates      DateSpan
site(s)    nav(equip, stop: site)
equip(s)   nav(equip, stop: equip)
point(s)   nav(equip, stop: point)
self       the Dict of the target record
val        Bool, Number, Str typed based on point's kind, unit, enum tags

Security

Actions permit tailoring of security at a fine granularity. You can apply the actionAccessFilter tag to a user record to control which actions are available to each user. The invoke function will raise a PermissionErr if the user has an actionAccessFilter and the action row does not match the filter.

Action security works with two modes:

Let's consider a common example of writable point overrides. The functions to invoke overrides require admin permission. So by default no operator users have access to these functions. But we can construct a security model where some operators have tailored access to override commands. Consider these actions table:

// action table requiring hvac level 2
ver:"2.0"
dis,expr,hvac
"Manual Set","pointOverride($self, $val)",2
"Manual Auto","pointAuto($self)",2

// action table requiring lighting level 3
ver:"2.0"
dis,expr,lighting
"Manual Set","pointOverride($self, $val)",3
"Manual Auto","pointAuto($self)",3

We can grant users access to the actions above as follows:

// grants user access only to actions with hvac level 2 and below
actionAccessFilter: "hvac <= 2"

// grants user access to hvac and lighting commands level 3 and below
actionAccessFilter: "hvac <= 3 or lighting <= 3"