Skip to content

Tag: <failed> - Test for a Failed Command Execution

Definition

The <failed> tag is used to define the criteria that needs to be matched in order for a command to be returned failed. The <failed> tag is one of two 'response' tags, the other being the <success> tag.

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:

Parameters

  • 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 type and value attributes.

type value Description
ci_match String Case insensitive match where the expression defined by value MUST exactly match the response from the device.
ci_in Regular Expression Case insensitive search for the expression defined by value in the response from the device.
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_in over 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 <failed> and <success> tags, the order is important. The tags are processed starting from the top, with the first to match being the returned response. For example:

1
2
3
4
<command>...
   <success type='ci_match' value=''/>
   <failed type='default' />
</command>

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.

!! note The above example is actually the default response tags configuration if no response tags are specified inside a <command> tag.

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
<command>...
   <success type='ci_in' value='Ok.'/>
   <success type='ci_in' value='Command completed successfully.'/>
   <success type='ci_in' value='Done.'/>
   <failed type='default' />
</command>

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
<command>set interface %(port)s speed auto duplex auto
   <success type='ci_match' value=''/>
   <failed type='default' message='Port %(port)s speed and duplex NOT set.'/>
</command>

Parent Tags

Child Tags

  • None