Tag: <success> - Test for a Successful Command Execution

Definition

The <success> tag is used to define the criteria that needs to be matched in order for a command to be return a successful. The <success> tag is one of two response tags, the other being the <failed> 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 successful. This can contain substitutions.

Type and value combinations

The following are valid combinations of using the type and value attributes.

type Attribute Value	Use of value attribute	Description
ci_match	String	This is a case insensitive compare where the expression defined by value and MUST be an exact match of the response from the device.
ci_in	Regular Expression	This is a case insensitive test to see if the expression defined by value is contained anywhere in the response see from the device.
default	Not required.	This will force this <success> tag to be matched and the task will return success with no further tests performed. This should only ever be used in the last response tag.

When checking device responses it is normal 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.

So when testing device responses, always use ci_in.

Example: Priority Order

When using both the <success> and <failed> tags, the order is important. The tags are processed top first, with the first to match being the returned response.

For example:

   <command>...
      <sucesss 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. Still processed in order, like this:

   <command>...
      <sucesss type=`ci_in` value=`Ok.`/>
      <sucesss type=`ci_in` value=`Command completed successfully.`/>
      <sucesss 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.

Note, these <success> tags use ci_in to check for part of the returned value and not ci_match.

The type default must only be used as the last tag, otherwise any response tags (success or failed) after it will never get tested and should never be applied.

Example: Return Message

The message attribute can be used to display a message back to the user after a command has run successfully. This message can be a fixed string or it can contain substitutions.

Here`s an example of a task that would have an input defined and then use the message attribute to return a message to the user running the task.

   <command>set interface %(port)s speed auto duplex auto
      <success type=`ci_match` value=`` message=`Port %(port)s set to Auto Speed and Duplex.`/>
      <failed type=`default`/>
   </command>

An example message being displayed, would look like:

Parent Tags

-Tag:

Child Tags

• None