Chart Scope and Variables
Chart-Scoped Variables
Charts can have variables created within them. The term “scope” means a collection of named variables that are accessible to the elements of a Chart. Each chart instance gets its own, private scope. Scopes are basically free-form name-value maps, whose values may be any Python object, including scalar and multivariate types.
Each chart gets a scope object that can be accessed from all steps and transitions within that chart. When starting a chart (for example, from a script), you’ll be able to pass variables to the chart: those variables will appear in the chart’s scope.
By defining a variable as chart-scoped, all of the scripts and expressions in the chart may access the variable. Variables that will be referenced by multiple elements should be made chart-scoped.
Chart Parameters
The Begin Step of a chart allows Chart Parameters to be defined. Chart Parameters are chart-scoped variables that the Chart expects to be initialized with. Values may be defined for each parameter, but can be overridden when a Chart is called, or starts. If the parameter values are override, then the initial values will be ignored.
One of the chart parameters defined on the begin step may be marked as the Key Param. This means that this parameter may be used as an identifier for the chart. For example, suppose your chart defined the automation process for a car through an assembly line. You might define the car's VIN as the key param. This means that instances of this chart may be identified by the VIN they were started with.
SFC parameters are unable to store entire QualifiedValue objects, such as those returned by the system.tag.readBlocking function. However fields of a QualifiedValue, such as the value (.value), can still be stored in parameter.
Defining Variables in Actions
Chart-scoped variables may also be defined on Action Steps in a Chart. To define a chart-scoped variable, "chart." should to be concatenated before the variable name. Creating a variable called "partNumber" on an Action Step's On Start would use the following syntax:
chart.partNumber = 111
As long as the name of the variable matches a pre-existing variable, then the new value will be assigned. If a script on an Action attempts to reference a variable that has not yet been defined, the script will create it.
Built-in Variables
There are a number of built-in variables maintained by the SFC engine that can be read through the chart scope.
| SFC built-in Variables | Description |
|---|---|
| chart.instanceId | The string UUID of the running chart instance. |
| chart.startTime | A java.util.Date object that indicates when the chart instance started running. |
| chart.runningTime | An integer representing the number of seconds the chart has been running for. |
| chart.parent | The chart scope of the enclosing chart (if any). null if this chart was not executed as part of an enclosing step. |
| chart.running | Returns true if the chart is in the running state |
| chart.state | An integer representing the state of the chart. See chart.state values. |
| chart.abortCause | Should the Chart abort, returns the exception. Only available on the Chart's On Abort event script. |
chart.state
| Value | State |
|---|---|
| 0 | Aborted |
| 1 | Aborting |
| 2 | Canceled |
| 3 | Canceling |
| 4 | Initial |
| 5 | InitPaused |
| 6 | Paused |
| 7 | Pausing |
| 8 | Resuming |
| 9 | Running |
| 10 | Starting |
| 11 | Stopped |
| 12 | Stopping |
| 13 | Suspended |
| 14 | RedundantInactive |
Reserved Words
Certain chart scoped variables may interfere with the internal functions of the chart. For example, creating a variable like chart.values will conflict with a Python Dictionary's values() method and therefore the chart will show an error. Since SFC charts use Python Dictionaries to manage chart scoped variables the methods associated with Python Dictionary's act like reserved words.
In addition to the built-in variables above, the following names should be avoided when declaring chart or step variables:
| clear | copy | fromkeys | get | has_key |
| items | keys | setdefault | update | values |
Chart-Scoped Variables in Transitions
Because Transitions use Ignition's Expression Language, references chart-scoped variables uses different syntax. chart-scoped variables can be denoted by typing the name of the variable between the "{" and "}" characters. The "partNumber" variable from above would look like the following:
{partNumber}
Referencing chart-scoped variables in Transitions allows you to easily control the flow of a chart. This is commonly used to create a {counter} that blocks flow of the chart until a certain condition has been met.
Chart Monitoring
Once chart-scoped variables have been defined, their values can be viewed while the chart is running in the Chart Monitoring section. This allows for easy troubleshooting from the Designer. More details can be found on the Monitoring and Debugging Charts page.
