Free-Form Response Templates
Before reading on, please refer to the previous About Regions, Targets, and Markers section for general information on output blocks and targets.
The command output of free-form templates consists of lines and words.
A free-format region can contain simple targets, Regex targets, or a combination of these.
To edit a free-form response template:
Click into the Response Template column, then click the Edit Responsebutton next to the template that you want to edit.
The Response Template Editor appears as shown in Figure:Response Template Editor Window , with the command's output displayed in the Command Response pane at the left.
Figure:Response Template Editor Window
Select a marker area and click the Create marker button.A Marker item is added to the Regions and Targets pane. In the Properties pane below, which displays the item's properties, edit the name and the optional description as desired.
When specifying targets in free-form outputs, you might need to use markers to support target resolution.
Markers represent a mode of identifying a well-defined piece of response text, as described in About Regions, Targets, and Markers. For adding a simple target, select a token in the command output and click the Create target button.A Free-format and a Target item are added to the Regions pane.
In the Properties pane, edit the properties of the Target item as follows:
- Target name: A target name reflecting the target type that is automatically assigned upon creation.
- Target data type: The target data type, which can be String or Number.
- Target description: An optional target description.
- Type of target: For plain targets this parameter is set to the Text target value.
- Name of column to get value from: For free-format response templates, this information is N/A.
For simple targets within free-format regions, the Regular expression template, Regular expression, Value of C1, and Repeating search fields are not available.
- Value selected: The actual value of the selected target.
- Export results: When this option is selected, the target value becomes available as a statistic via the step return variable.
Example:
Let us consider the response of a ping command as illustrated by the image below:
and assume we were interested in retrieving the number of lost packets displayed in the command output.
If we marked the 0 output portion as a simple target, for the given example the target value displayed in the Value selected field would then be 0. To add a target that matches a user-defined regular expression, click the
Regex target button.The entire command output appears selected and a Free-format and a RegexSearch item are added to the Regions pane.
In the Properties pane, specify the properties of the Regex target in place as follows:
- Target name: A target name reflecting the target type that is automatically assigned upon creation.
- Target data type: The target data type, which can be String or Number.
- Target description: An optional target description.
- Type of target: This parameter is set to a Regex target value.
- Name of column to get value from: For free-format response templates, this information is N/A.
- Regular expression template: A regular expression specifying a pattern to match. The regular expression template comprises a regular expression part, which corresponds to the target value that is actually retrieved, and a user-specified sub-string defined in the Value of C1 field.
For example, a [0-9]* C1 template contains a variable length digits sequence followed by a space and the C1 sub-string.
The following regular expression templates are supported:
[0-9]* C1 : Denotes all strings consisting of any number of digits, followed by a user-defined C1 string.
[0-9]* =C1 : Denotes all strings consisting of any number of digits, terminated by the `=' character, and followed by a user-defined C1 string.
[0-9]* %C1 : Denotes all strings consisting of any number of digits, terminated by the `%' character, and followed by a user-defined C1 string.
[0-9]* ,C1 : Denotes all strings consisting of any number of digits, terminated by the `,' character, and followed by a user-defined C1 string.
[0-9]* :C1 : Denotes all strings consisting of any number of digits, terminated by the `:' character, and followed by a user-defined C1 string.
[0-9a-zA-Z]* C1 : Denotes all strings consisting of any number of digits, lower-case or upper-case characters, and followed by a user-defined C1 string.
[0-9a-zA-Z]* =C1 : Denotes all strings consisting of any number of digits, lower-case or upper-case characters, terminated by the `=' character, and followed by a user-defined C1 string.
[0-9a-zA-Z]* %C1 : Denotes all strings consisting of any number of digits, lower-case or upper-case characters, terminated by the `%' character, and followed by a user-defined C1 string.
[0-9a-zA-Z]* , C1 : Denotes all strings consisting of any number of digits, lower-case or upper-case characters, terminated by the `,' character, and followed by a user-defined C1 string.
[0-9a-zA-Z]* :C1 : Denotes all strings consisting of any number of digits, lower-case or upper-case characters, terminated by the `:' character, and followed by a user-defined C1 string.
C1 [0-9]* : Denotes all strings preceded by a user-defined C1 string, and followed by a string consisting of any number of digits.
C1 =[0-9]* : Denotes all strings preceded by a user-defined C1 string and the `=' character, and followed by a string consisting of any number of digits.
C1 %[0-9]* : Denotes all strings preceded by a user-defined C1 string and the `%' character, and followed by a string consisting of any number of digits.
C1 , [0-9]* : Denotes all strings preceded by a user-defined C1 string and the `,' character, and followed by a string consisting of any number of digits.
C1 :[0-9]* : Denotes all strings preceded by a user-defined C1 string and the `:' character, and followed by a string consisting of any number of digits.
C1 [0-9a-zA-Z]* : Denotes all strings preceded by a user-defined C1 string, and followed by a string consisting of any number of digits, lower-case or upper-case characters.
C1 =[0-9a-zA-Z]* : Denotes all strings preceded by a user-defined C1 string and the `=' character, and followed by a string consisting of any number of digits, lower-case or upper-case characters.
C1 %[0-9a-zA-Z]* : Denotes all strings preceded by a user-defined C1 string and the `%' character, and followed by a string consisting of any number of digits, lower-case or upper-case characters.
C1 ,[0-9a-zA-Z]* : Denotes all strings preceded by a user-defined C1 string and the `,' character, and followed by a string consisting of any number of digits, lower-case or upper-case characters.
C1 :[0-9a-zA-Z]* : Denotes all strings preceded by a user-defined C1 string and the `:' character, and consisting of any number of digits, lower-case or upper-case characters.- Regular expression: An editable regular expression corresponding to the selected regular expression template.
For example, for the sample [0-9]* C1 template considered above, the corresponding formula is (?<end>\d+)(?<md>[\s]+)(?<ft>C1).
The formula comprises three sections, <end>, <m(id)d(le)>, and <f(irs)t>, which correspond to the [0-9]*, the space, and the C1 parts respectively.
You can enter absolute values (both numeric and string) as well as variables as input here. To enter a variable, you need to precede it with a dollar sign ($).
The regular expression language specification is documented at the Microsoft website located at the following location: http://msdn.microsoft.com/en-us/library/az24scfc.aspx.
- Value of C1: A user-defined sub-string that is part of the previously defined regular expression template. You can enter absolute values (both numeric and string) as well as variables as input here. To enter a variable, you need to precede it with a dollar sign ($).
- Value selected: The actual value of the selected target, which corresponds to the <end> portion of the regular expression.
- Repeating search: When this option is selected, the defined Regex target is searched repeatedly in the defined free-format region. If more than one occurrence is found, the Value selected field displays a list of values.
- Export results: When this option is selected, the target value becomes available as a statistic via the step return variable.
Example 1: Given the response of a ping command illustrated by the image below, let us assume we were interested in retrieving the number of lost packets displayed in the command output.
If we defined a Regex target, specified a C1 = [0-9]* regular expression template and chose a `Lost' value for the C1 string, for the given example the target value displayed in the Value selected field would then be .
Example 2: Also considering the previous command output, let us assume we were interested in obtaining the minimum, maximum, and average round trip values. If we define a Regex target, specified a C1 = [0-9]* regular expression template, chose a `Minimum | Maximum | Average' value for the C1 string, and selected the Repeating Search option, for the given example the target values displayed in the Value selected field would then be 129 131 130. To add more than one target, repeat step 3 and/or 4.Alternatively, selecting a region or a target entry in the Regions pane and clicking the
button removes it from the pane.
Choose the File > Save or File > Save as command to save the Response Template into the resources database.While working with the Response Template Editor, when you choose an item in the Regions and Targets pane, the corresponding area in the command output in the Response Command pane is highlighted, as shown below:
While working with the Response Template Editor, you can use the
Edit > Paste command to replace the Command Response pane content with some pasted text.When saving a template from the Response Template Editor, it is saved in a folder under the Response Templates folder comprising all templates. If you want to save a Response Template to a different location, either on the same machine or on another network machine, use the Export command from the Manage Resources window instead, as described in Manage Storage.
More sample Response Template creation procedures are given in Response Templates Creation Samples.
See Also