Instruction Parameters
Our example instruction did not require any input parameters. For instructions that require parameters, TIMS allows you to define each parameter, along with its type, and various other attributes.
If you specify a parameter in TIMS, you will be prompted to enter a parameter value each time you run the instruction. The previous entry entered during that editing session is remembered.
Let's change our example to accept a single parameter.
Remove the existing instruction and then click the Add Parameter toolbar on the TIMS menu
Enter a parameter name WhoAmI
The parameter pattern - by which it will be referred to in code - is automatically inserted for you, wrapped by the required % symbols.
Field | Description |
|---|---|
Name | Parameter name - must be unique in the instruction |
Pattern | When the instruction is run, this text will be substituted in the instruction payload and readable payload with the parameter's value. The text must be enclosed by % symbols and should be the same as the unique paramter name. |
Hint Text | The alternative text to show (instead of the name) in the readable payload. |
Data Type |
|
Default Value | default value for the parameter. |
Control Type |
|
Control Placeholder | The text to show as a prompt to the user if th econtrol s empty. Valid for Free Text only. |
Control Metadata | Ths must match an existing custom property type (e.g. "Coverage Tag"). Valid only for Custom Property Key and Value. |
Control Source | The parameter name of the corresponding custom property key. Valid only for Custom Property Value. |
Validation Regular Expression | Regular expression, in .NET Framework regular expression syntax. Valid only for string Free Text fields. |
Validation Max Length | Maximum number of characters. Valid only for string Free Text fields. |
Validation Allowed Values | List of allowed values, separated by commas. Valid only for Value PIcker entry type. |
Note
In order for a user to enter parameter values when running an instruction in Explorer, the Readable Payload must include the same parameter names. For example: Say hello to %WhoAmI%
Add an instruction in the top pane of TIMS
select "%WhoAmI%";
Run the instruction. You are prompted for a parameter value.
Enter a parameter value and press OK. The instruction runs and the result is displayed.
Note
Parameter patterns are case-sensitive. %whoami% would not be the same parameter as %WhoAmI%
Instruction parameter considerations
Since parameter values are substituted directly into the Agent’s payload, you must take care to avoid the possibility of SQL or statement injection. Tachyon takes precautions against this (e.g. escaping double-quotes and backslashes within string parameter values), but you should consider the following when parameterizing instructions:
Although the format %ParameterName% is the preferred convention for a parameter placeholder, you are free to use any substitution placeholder you wish
Parameters should be defined as the most appropriate data type (string, integer, float, Boolean)
String parameters should, where possible, be constrained using a regular expression to prevent invalid input
Placeholders for string parameters should be placed within double-quotes within the Agent Language – the Tachyon Consumer API will automatically perform escaping of the parameter’s value
Placeholders for non-string parameters should not be placed in double-quotes
Within SQL statements, you may wish to consider using a CAST("%parameter%" AS NUMBER) expression for type-safety
Although it is possible to use parameters to build "dynamic statements" within the Agent Language, it is NOT recommended unless you take extreme care (and limit the possible values which can be supplied for the parameter)
Adding multiple parameters
If you add more parameters, then when you run an instruction you see all parameters and their current values in the parameters dialog, like this
Managing parameters
As with resources, parameters that have been added are shown in the footer pane of the script pane, like this
Click on a parameter dropdown to see the parameter menu.
Insert substitution pattern
This option just inserts the parameter pattern (such as %WhoAmI%) in the script pane.
Edit...
This option brings up the parameter dialog which we saw earlier, and allows you to change any property of the parameter
Remove
This option removes (deletes) the parameter. Any references to the parameter in instruction code will also be removed, and replaced with the current value of the parameter. For example, if I remove the %WhoAmI% parameter my code changes to
select "Andrew";
Parameter properties
The parameter dialog shows a number of parameter properties which control how it appears in the Tachyon Explorer along with default values, validation patterns and so forth. Because each field has a descriptive tooltip that appears when you hover over it, I will not repeat this information in the documentation here.
Note
In earlier versions of TIMS the parameter properties dialog includes a field for Numeric Restrictions. It is ignored. This feature does not exist yet. This field is removed from later versions of TIMS, pending support for this feature in a future version of Tachyon.
Tip
See Instruction Definition Reference (ParameterJson) for more detail about parameters.