Control Tokens
The Control Token system ensures that only one person (owner) at a time has control over a tag or set of tags. It is complimentary to the Control Locks system. A lock denies control and a token grants exclusive control (providing that the tag is not otherwise locked).
Upon enabling the Control Token system, all users must request a Control Token for every output.
DO NOT ENABLE THIS FEATURE WITHOUT PROVIDING USERS WITH A WAY TO REQUEST A TOKEN.
It is essential that Request Token Button Widgets exist or that appropriately configured Control Token Box widgets be drawn on any page that contains an output widget.
If a token is applied to a tag, only that token’s owner has control over the tag. A control token restricts user actions. It does not restrict automated actions. Any tag can have only one token. (This is in contrast to Control Locks where multiple locks can be placed on a tag for different reasons.)
The Control Token system can be enabled globally by setting the application property ControlTokensEnabled to 1. (Configuration Properties) Alternatively, it can be enabled for a specific tag tree (or part thereof) by adding the property to a Context tag (or tag type derived from a Context tag) to enable Control Tokens in child tags of that parent. (You can also disable Control Tokens for a section of a tag tree by adding the property to a parent tag and setting the value to 0.) VTScada will check for ControlTokensEnabled starting with the current tag and working up through the scope of the tag tree to the application in general.
Placing a token on a tag grants the token owner control over that tag and all of the children that do not already have another control token. Adding a token to a parent tag does not override any existing token on a child tag.
Tokens are requested, viewed, and managed using widgets that you draw. Do not look to the Tag Browser or tag properties for Control Tokens. Token-related widgets can be found in the palette folder, Tools\Control Tokens.
| Feature | Effect | Use... | Reference |
|---|---|---|---|
|
Security Privileges |
Control who is allowed to write to an output. |
Use in all applications |
Restrict Access to Output Tags |
| Control Locks |
Prevent use and operation of selected equipment via the VTScada screens. If the tag is protected by a privilege, users must also have that security privilege. |
Only where there is a need to lock controls for all users, regardless of privilege. | Control Locks |
| Control Tokens |
Ensure that only the current token owner can write to an output tag. Users must also have the required security privilege and the tag must not be locked. Only one user at a time can hold a Control Token. |
Only where there is a need to restrict control to one operator at a time. | Control Tokens |
VTScada Control Tokens do not override physical switches or alternate controls for the PLC. They apply only to the VTScada user interface.
You can disable the Control Token feature on a site by site basis through an application.
Do so by adding the property ControlTokensEnabled to the parent Context tag(*) of the site and set the value to 0. Tags within that structure can then be operated without first obtaining a Control Token.
(* or Context-based custom type if the parent tag is no longer a Context)
Requesting Control Token Ownership
Authorized users(*) can request a Control Token for that tag either explicitly using a Request Token Button Widget, or implicitly by opening a page that contains an appropriately configured Control Token Box widget.
(* An "authorized user" is anyone with the Token Request / Release privilege, as well as any privilege required to use a given output tag.)
These requests are made using widgets, and can be made for a single output tag or for all the tags under a common parent. If no-one else has a control token on the tag, the default behavior is for the request to be granted immediately.
It may happen that one or more people want to request control over a tag when someone else already has a control token for that tag. What happens in this case depends on your configuration: by default, later requests must wait until the current token owner releases control. You can configure the system such that incoming requests with a higher priority level will automatically take control from the current token owner.
To keep track of who has control and who is requesting control, two separate lists are maintained: the Token list (who has ownership) and the Token Requests list (who is requesting ownership).
The Token Administrator privilege can be granted to selected users so that they can release any existing tokens and can grant or deny any existing token requests. The Token Administrator privilege by itself does not grant the user the ability to request a Control Token.
Releasing Tokens
At any time, you can choose to release tokens that you hold. Do so with a Release Token Button widget that matches the token you wish to release. (Like the Control Token Request button widget, the release button is linked to a tag and affects only the token applied to that tag. A more convenient option might be to use a Token List, where all tokens are shown and you will have the option to release any that you hold.
By default, token owners can release only the tokens that they own. You can change this behavior by setting the application property, ControlTokenCanOnlyRemoveOwnToken, to 0. (This does not affect Token Administrators, who can release anyone's tokens.)
Ownership can be defined in several ways and is set using the ControlTokenOwnerMode property.
As described in the notes for that property, ownership may be linked to any of the user's sign-in session, the user's account in general, the user's current workstation, or to a custom programming hook that you provide.
Global Tokens
Formally known as Root Tag Tokens, a Global Token will grant control over every output in the tag tree. The Request Token Button, Release Token Button and Control Token Box widgets all have a Global Token check box within their properties configuration.
A Global Token does not force the release of other control tokens. If a Global Token has been requested and is available it will be granted immediately-- but control of any output already being controlled by someone with a control token will stay in their control until they release their token. Once the control token for a specific device has been released, the user holding the Global Token will assume control.
The Global Token works by declaring a fictitious 'Root Tag' in the ControlTokenManager. The syntax to use this would look similar to:
\ControlTokenManager.RequestToken(\ControlTokenManager.RootTagID, Level)
The Root Tag name and area can be changed by adding ControlTokenRootTagName and ControlTokenRootTagArea properties.
Token Lifetime
Control Tokens will continue to exist after the holder signs out. You can alter this behavior such that the act of signing out will always release all tokens held by a user, automatically. Do so by setting the property ControlTokenAutoReleaseUponLogout to 1. This also denies all token requests made in that session.
The lifespan of Control Tokens (and Control Token Requests) can be controlled by the properties, ControlTokenMaxAge and ControlTokenRequestMaxAge, neither of which are set by default, meaning that there is no automatic expiry.
Stale Tokens & Requests
These are tokens or requests left behind when a user shuts down the application without releasing (by any means) the tokens or requests that they hold. This can occur with a workstation crash or a user simply shutting down their computer without signing out.
The owner of every token and request will send a "heartbeat" signal to the token server. If a pulse does not arrive for a set amount of time, VTScada will assume that the token or request is stale. The server will release stale tokens and requests when it checks its dictionary of timestamps every ControlTokenMonitorTime seconds or when the list of tokens and requests changes. This behavior is controlled by the following properties:
- ControlTokenEnableOwnerMonitor
Defaults to 1 (TRUE) to enable release of stale tokens. - ControlTokenMonitorTime
Defaulting to one hour (3600 seconds), this is the frequency at which the control token manager checks its list of token and request owners to ensure that it is current and release / deny stale tokens / requests - ControlTokenStaleTokenTime
If there are no requests for the token, it will be determined to be stale after not receiving a heartbeat for one day (86400 seconds) (It has been a day since we heard from the owner.)
The interval also applies to all requests. - ControlTokenPendingRequestStaleTime
If there are requests for the token, it will be determined to be stale after not receiving a heartbeat for one minute (60 seconds) (It has been a minute since we heard from the owner.)
This interval does not apply to any requests. - ControlTokenOwnerHeartbeat
Defaulting to 30 seconds, this is the frequency at which a token owner confirms with the server that it is still active.
Token Actions
As noted, if a user requests a token and no-one else has a token on that tag, the request will be granted immediately.
If a user requests a token and someone else currently has a token for that tag or its parent, then a Token Request will be appended to the Token Request list. This pending request can then be either Granted or Denied, either by the current token holder or by a Token Administrator. If the request is Granted, then the current token holder loses control over the tag and a new token with a new owner is placed. If the token request is Denied, the token request will be removed from the Token Request list. A user cannot have multiple identical token requests.
Releasing a token initiates an auto-granting mechanism where the next person in the list of Token Requests will be granted control (and a new token). They will be removed from the list of Token Requests so that when they release their token, the next request can be granted.
If you hold a token and another user requests control over that tag, you will be presented with the Token Requests dialog:
Your choices are:
- Grant the request. (You will lose control of the tag.)
- Deny the request. (The request will be removed from the Token Request List.)
- Close the dialog without taking action. (The request will remain on the Token Request list and will be granted when you release the Control Token.
Token Levels vs. Token Actions
Like Control Locks, tokens have levels. The default level for token requests is 1 (where lower level numbers indicate higher priorities). All levels grant control over the tag. (There is no equivalent to ControlLockLevelXPreventControl.) Levels are used in combination with application properties to control the behavior when someone else requests a token that you hold.
The relevant properties that control what will happen when someone requests a token that you hold are as follows:
Defaults to 0. Controls whether to grant an automatic token request for a token on a tag that is currently being controlled by another owner.
Defaults to 1. Controls whether automated requests for tokens will be added to the request list.
Defaults to 0. Controls whether to grant a manual token request for a token on a tag that is currently being controlled by another owner.
ControlTokenManualRequestOption
Defaults to 1. Controls whether manual requests for tokens will be added to the request list.
Together, the default values mean: "never release someone else's token and add all requests to the token request list". Levels do not apply.
Note that each of the
Levels will apply to the actions of requesting / granting / denying / releasing tokens if you choose to set these properties to values other than the default. The rules vary according to the values you set for these properties but the overall effect is to allow automated actions and control whether any action can proceed based on a comparison of the priority of the request.
For example, suppose that a user has a control token with a low priority level (3) and another user creates a request with a higher priority level (1). By default, the level is irrelevant and the second user must wait until the first token is released. But you could configure the system such that the act of creating a higher priority request will automatically release the first token and grant a new token to the person making that high priority request. Other combinations are possible.
Three token levels are provided and more can be added (and simultaneously given an indicator color) by inserting ControlTokenLevelXColor properties, where X can be 4, 5, etc. Do not skip values.
Possible values for each of these properties:
| 0 | Never |
| 1 | Always |
| 2 | If request level priority > token level priority (lower number / higher priority takes precedence) |
| 3 | If request level priority >= token level priority |
| 4 | If request level priority < token level priority |
| 5 | If request level priority <= token level priority |
| 6 | If request level priority == token level priority |
| 7 | If request level priority != token level priority |
