Define an Update Variables or Stored Values Action
Use the Update Variables or Stored Values action to set and update variables or stored values using a pre-defined value. Adding multiple variables in a single One-Step Action can reduce the complexity and effort of creating and maintaining One-Step Actions.
When you create variables, they are available in other actions within the One-Step™ Action, including pre/post-steps and expressions. For example, use a One-Step Action to prompt a User for a value (example: name of a Customer), and then store the selected value as a variable (rather than in a temporary Field). The variable can be used throughout the One-Step Action to take different actions depending on which value was selected.
When executing a One-Step Action containing variables, those variables only retain their values while the One-Step Action executes. If the One-Step Action is executed again, the variables have no values until set by this action. If this window is canceled, all User-defined variables are removed and are no longer available for use.
To define an Update Variables or Stored Values action for a One-Step Action:
- Open the One-Step Editor.
- Add an Update Variables or Stored Values action to the Designer board.
- Define general properties and the type of value to update for the Update Variables or Stored Values action:
Option Description Name Provide a display name for the action (this is how the action is identified within the One-Step Action). Stored Value Select this option to update a stored value. Select the ellipsis to open the Stored Value Manager, and then select an existing stored value, or create a new one.
If you select a stored value that contains User-specific values (or if you use this action to update a stored value with a User-specific value), the following warning appears: This stored value has a different value for each User. The value set here will only apply to the current User.
If the User-specific value is not remembered between sessions, you will see the following additional warning: Also, this value will be reset to the default value when the application is restarted.
Clear User-specific Values and Restore the Stored Value to Its Default Value Select this check box to remove any values a User has defined specifically for their own use and restore the stored value to its default value.
This option is only available if a stored value that contains User-specific values is selected.
Based on Scope and Value Select this option to have the action make a selection based on a specified scope and Token Value. Then, select the scope in the drop-down list. Select the Selector button to open the Token menu and select a token that holds the appropriate name or ID. Variable Select this option to define unique variables. Variable Provide a name for the variable. This is the name that is shown in the Token tree for other actions within the One-Step Action.
When you provide a variable name, the Variable is automatically selected.
To rename the variable, select Rename. Type the new name, and select OK.
Data Type Select a Data Type (example: text, number, date/time, logical, JSON/JSON array, XML/XML Collection). If you use XML or JSON data types, the defined value (below) must use the appropriate JSON or XML syntax. New Value Value that will update a variable or stored value. A value cannot be defined if this action is used to clear User-specific values and return stored values to their default values.
Provide text. Select Selector to insert tokens (example: fields, system functions, prompts, expressions, stored values, metrics, and counters) directly into the text.
After Replacing Tokens, Evaluate the Result as a Calculation Select this check box to have the value of the variable or stored value treated as a simple expression that returns a calculated result rather than a string.
This is a powerful feature with almost endless possibilities. For best results, follow the guidelines below.
- Update Stored Value and Variable actions:
Option Description Update another Stored Value or Variable Adds another Update action to either create a new variable, update an existing variable or stored value, etc. Remove this Update action Removes the selected Update action.
The variable may still persist if it is referenced in other places in the One-Step Action.
Edit the condition for when this update occurs Edits the condition for the selected Update action. While the entire Update Stored Values or Variables action (sub-action) may run, if the condition is false for a specific Update action, then that update will not occur. Move the update up in the execution order Moves the selected update up in the execution order. Move the update down in the execution order Moves the selected update down in the execution order.
- Define the Annotations for a One-Step Action.
- Select Save.
Any variables that are not referenced when the One-Step Action is closed are removed.
Variable or Stored Value Treated as an Expression Guidelines
- When you create an expression, use a Token to refer to the values. Tokens are typically selected from the Token tree, but you can enter specific values or Tokens if necessary.
- Enclose string Tokens and string values with single quotation marks (example: 'Incident.Status' = 'Closed').
- Any Tokens that contain non-alphanumeric characters, start with a digit, or match any of the following reserved words require special handling:
- If a Token meets any of the above conditions, it must be enclosed in either square brackets or back quotes. For example, Token# must be written as either:
- [Token#]:Total * [Token#]
- `Token#`:Total * `Token#`
- If a Token enclosed in square brackets contains any square brackets or backslashes within its name, then you must insert a backslash before the brackets or backslashes. If a Token is enclosed in back quotes, then it cannot contain any back quotes within its name. For example, a Token named Token\ would be written as either:
- Total * [Token[\]\\]
- Total * `Token\`
- You can use User-defined values within expressions and compare them to Token values.
- Enclose string values in single quotation marks (example: 'StringToken' = 'John'). If a value includes a single quotation character within its name, then you must insert another single quotation mark before the character.
- Number Tokens do not need to be enclosed in quotation marks (example: NumberToken <= 50.00). You can use scientific notation in numeric values. Only periods can be used as decimal separators to separate the integer part from the fractional part of a number. Commas and other characters are not supported as decimal separators or as thousand separators (example: ten-thousand and five tenths should be entered as 10000.5).
- Enclose date values within pound signs (example: #DateToken# < #01/31/82#).
- You can concatenate expressions using Boolean AND, OR, and NOT operators.Use parentheses to group clauses and force precedence (the AND operator has precedence over other operators). For example: (‘StringTokenLastName’ = 'Smith' OR ‘StringTokenLastName’ = 'Jones') AND ‘StringTokenFirstName’ = 'John'
- The following operators are allowed in comparison expressions:
- The following arithmetic operators can be used in expressions:
- + (addition)
- - (subtraction)
- * (multiplication)
- / (division)
- % (modulus)
- The following functions can be used in expressions:
Convert Description Converts an expression to a specified .NET Framework type Syntax Convert(expression,type) Arguments
expression: The expression to convert
type: The .NET Framework type to which the value will be converted.
Example Convert('StringTokenValue,' 'System.Int32') Exceptions
- Boolean can be converted to and from Byte, SByte, Int16, Int32, Int64, UInt16, UInt64, String, and itself only.
- Char can converted to and from Int32, UInt32, String, and itself only.
- DateTime can be converted to and from String and itself only.
- TimeSpan can be converted to and from String and itself only.
IIF Description Retrieves one of two values depending on the result of a logical calculation. Syntax IIF(expr, truepart, falsepart) Arguments
expr: The expression to evaluate.
truepart: The value to return if the expression is true.
falsepart: The value to return if the expression is false.
Example IIF(TotalTokenName>1000, 'expensive', 'dear')