<failed> - Test for a Failed Command Execution
<failed> tag is used to define the criteria that needs to be matched in order for a command to be returned failed.
<failed> tag is one of two 'response' tags, the other being the
These two tags are used together to create a set of possible matches, applied in order, that will be processed against the response of a device.
This tag has the following attributes:
type (ci_match, ci_in, default): This defines the type of test to be performed. More detail below.
value (str): This is the value that the test will use to compare to the device output. More detail below.
message (str): This defines a message to be displayed back to the user running the task, when the task fails. This can contain substitutions.
Type and value combinations
The following are valid combinations of using the
|ci_match||String||Case insensitive match where the expression defined by
|ci_in||Regular Expression||Case insensitive search for the expression defined by
|default||Not required.||If no other cases are met, default to failed with no further tests performed. This should only ever be used as the last test.|
It is common to use
ci_match even if you know the exact return string from the device.
This is because the device can output non-printed control characters or additional line breaks that are not obvious when looking manually at a device response.
Example: Priority Order
When using both the
<success> tags, the order is important.
The tags are processed starting from the top, with the first to match being the returned response.
1 2 3 4
This will return success if just the prompt comes back on its own, i.e. no other text output. This is because the
<success> tag is matching a value of nothing.
If the device returns any text at all then the
<success> tag won't match but the
<failed> tag will as this is set to default.
The above example is actually the default response tags configuration if no response tags are specified inside a
If there are several options for a successful outcome of the command, then multiple
<success> tags can be used:
1 2 3 4 5 6
In this case any of the
<success> tags could match and return a success.
If none match then the default of failed will apply.
Example: Return Message
The message attribute can be used to display a message back to the user after a command has failed. This message can be a fixed string or it can contain substitutions.
Here's an example of a task that has an input defined, and then uses the
message attribute to report back to the user.
1 2 3 4