Device type CLI interaction XML element reference

Identifies this part of the processing

Must be unique among the device commands in the device type. This GUID might refer to a standard processing phase, or, for custom trails and custom actions, it might refer to a GUID you generated. The standard GUIDs are listed below.

true or false to indicate if the <deviceCommand> should be attempted a second time if the first time results in some command timing out.

Default is false. Use this element if timeouts are random and flaky.

String containing general notes, warnings, quirks, or anything else special about this device command that might affect how users use it

Use a CDATA tag to enclose HTML elements that format this information for display in the Device Adapter Capabilities report. Refer to Common concepts and XML elements for the CDATA tag.

true or false to indicate if the <deviceCommand> performs a tunneled snapshot or a tunneled deploy function.

This element is used to inform users about supported tunneled operations in the Device Adapter Capabilities report.

String containing a message describing the situation to the users when this assertion fails. See Assertions for more details. 

An <assert> tests the condition. When the condition evaluates to anything except false, the assertion passes and processing proceeds to the next element. If the condition evaluates to false, the assertion fails; processing stops and the status specified in onFailure is reported to the executing span action (and ultimately to the user in the job's results). An assert element contains the following attributes:

• condition: (Required) The expression to be evaluated. See Conditional expressions for the supported syntax.
• onFailure: One of the following values, indicating the severity of the failed assertion.
  • abort: The calling span action should fail with an error.
  • warning: The calling span action should succeed with a warning.
  • skip: The calling span action should treat the device as skipped.

An <unassign> removes the specified property from the current set of connection properties if the property exists. This element contains the following attribute:

• property: (Required) The name of the property to be removed.

Contains command elements that are executed when the condition evaluates to true. See condition for more details. 

A <condition> tests that some processing state is present. When its test expression evaluates to true, execution proceeds into the contained elements. When the test expression does not evaluate to true, then the contained elements are skipped. This element contains the following attribute:

• test: (Required) The expression to be evaluated. See Conditional expressions for the supported syntax.

Defines a command to send to the device and processing of the device's output from running the command. See Interactions for more details.

This element contains the following attributes and child elements:

• optional: true or false to indicate if this interaction is optional. When optional, the system looks to match the data read from the device against the prompts in this interaction or any subsequent interactions up to and including the next non-optional interaction. See this discussion for more details. 

• disconnect: One of never, sometimes, or always to indicate if the execution of this interaction might cause the system to be disconnected from the device (such as during a reboot). If the system knows that a disconnect is normal, it simply reconnects (instead of treating the disconnect as an error). See this discussion for more details. 
• regex: true or false to indicate if the <prompt>, <response> or <error> element, or <capture> element's prefix or suffix attributes contain regular expressions. See Regular expression support for more details. 
• responseJitterMilliSeconds: Number that controls how the system reads the device's response, specifying how long a delay there may be between characters. A longer jitter might be necessary if the device tends to take pauses while emitting output (that is, its output is in bursts with little pauses in between). A device may be jittery if it is busy doing other things than servicing this command, where it is context switching in and out of producing the command's output. See this discussion for more details. 
• timeoutSeconds: Number indicating how long to wait for the device to begin to emit response.
• reconnectTimeoutSeconds: Number that controls how long the system waits before reconnecting to the device after a disconnect (such as to allow the device to reboot). This attributes overrides the system parameter Timeout for Re-Establishing Connection After a Reboot.
• kickAtResponseTimeout: String to send to the device when the device seems to be stuck waiting for input and has not emitted any response. Overrides any <kickAtResponseTimeout> defined in the header of the device type. You may specify non-printable characters using \xnnn notation, where nnn is the numeric hex value for the character (for instance, \x003 is the control-C character).
• <prompt>: String containing the prompt that must be received from the device before sending the command. May be a regular expression, if the regex attribute is true. This element contains the following attribute:
  • jitterMilliSeconds: Number that controls how the system reads the prompt from the device, specifying how long a delay there can be between characters.
• <command>: (Required) String containing the command to be executed by the device. This element contains the following attributes:
  • omitEOL: true or false to indicate if an end-of-line sequence should be added to the string.
  • stutterMilliseconds: Number defining the pause between characters. Pausing a little bit after sending each character can mimic how a human types. Some devices cannot read its command line at machine speed, but only at human speed. Some devices try to auto-complete as you type, which can slow down its input processing. A longer stutter slows down the input of the command into the device so that the device is able to read it without losing any characters. See this discussion for more details. 
  • sensitive: true or false to indicate if the command contains sensitive data (such as a password). Such data is sent to the device in the clear text, which normally would show up in the transcript in the clear text. When this flag is true, the command is masked in the transcript. See this discussion for more details. 
  • sensitivePhrase: The string in the command that is to be masked; used only when sensitive is true. If this is present, only part of the command is masked; else, the entire command is masked.
• <pauseSeconds>: Number of seconds to pause (do nothing) after sending the command and before reading the response. Normally, no such pause is done, but if the device spends a long time silently running the command, the system might consider the device to be non-existent and error out. Adding a pause can resolve such errors.
• <response>: String containing an expected response. May be a regular expression, if the regex attribute is true. If there are multiple <response> elements, they are checked in order and the checking stops as soon as a match is made. So it may be necessary to code the most specific responses first, and the most general responses last (if it is important to distinguish between responses by setting a property). That is, be careful not to match the wrong response. See this discussion for more details.
  • property: String containing the name of the property to populate with the value of the response. That is, the value of the response element is the response you expect from the device, which may be a just a trailing piece of what the device emits, or might be just a success message that comes out at the end. It is this value that is assigned to the property (not the entire output from the device).
• <responseBlockReference>: Specifies the name of a previously-defined <responseBlockDeclaration>, to use the referenced responses here. See this discussion for more details.
• <error>: String containing an expected response that indicates an error has occurred; <error> elements take precedence over <response> elements. May be a regular expression, if the regex attribute is true. If there are multiple <error> elements, they are checked in order and the checking stops as soon as a match is made. So it may be necessary to code the most specific errors first, and the most general errors last (if it is important to distinguish between errors by setting a property). Note that when an error is matched, execution of the <deviceCommand> terminates; it does not move on to the next interaction; the error is reported to the user as a failed job. Any <finallyBlock> is executed, as well as the logout <deviceCommand>; these sections can utilize any property this error has set. See this discussion for more details.
  • property: String containing the name of the property to populate with the value of the error.
  • retry: true or false to indicate the entire <deviceCommand> should be re-tried once if this error occurs. See this discussion for more details. 
• <errorBlockReference>: Specifies the name of a previously-defined <errorBlockDeclaration>, to use the referenced errors here. See this discussion for more details. 
• <capture>: String containing the value to be assigned to the property. See this reference and examples for a complete discussion.
• <syntaxErrorCheck>: Indicates that the command's output should be checked for syntax errors; the errors are defined in the <syntaxErrors> element. When a syntax error is found, the property is set to true. The property can now be used for conditional logic (such as breaking out of a loop).

Indicates point at which the XML from an injection template is to be inserted. See About device configuration management for more information about using injection templates.

Starts a processing loop and contains the interactions and other elements to be executed repeatedly until the loop termination condition is reached. See this discussion for more details. This element contains the following attributes:

• associativeFlag: true or false to indicate whether the property array being iterated over in a for-each type loop is an associative array or not. An associative array would be a collection of properties of the form "%MyProp[A]%", "%MyProp[B]%", ... while a non-associative array would be a collection of properties of the form "%MyProp.0%", "%MyProp.1%", ...
• namespace: String containing the namespace to use for this loop. The namespace is used as a prefix for the name of the counter and variable properties. It is also used to remove any property which matches the value "namespace.*" after the loop is complete. Allowing different loops to use different namespaces allows you to nest loops. The default namespace value is "loop".
• condition: Expression that, when it evaluates to false, terminates the loop. See this discussion for the supported syntax.
• counter: String containing the name of the property that is used as a loop counter, getting incremented by one each pass through the loop.
• input: Holds an input string which will be "iterated" over to assign individual values to the variable property, used in the for-each type of loop.
• inputSeparator: If the input is not already divided into lines, specifies how to divide it, such that the pieces can be iterated over.
• start: Initial value for the counter.
• stop: Final value for the counter.
• variable: String containing the name of the property that contains the current loop variable, getting updated to the next input value each pass through the loop.
• <break>: Defines a condition to be checked that, when evaluated to true, causes the loop to be terminated.
  • condition: (Required) Expression to be evaluated. See this discussion for the supported syntax.

Indicates that the system should pause for the specified number of seconds before continuing on to the next element. See this discussion for more details. 

Defines how to test or validate a command line on the device and processing of the device's output from testing the command. Commands are validated by entering each one at the CLI, followed by (usually) a question mark. When the device reads the question mark, it (usually) echoes out the available legal command syntax. The system evaluates the response and then erases the entered command line and goes on to the next line.

In addition to the special elements shown at left, the other elements that can be used inside the <syntaxScanInteraction> are <prompt>, <command>, <pauseSeconds>, <response>, <error>, and <capture>. These are described above in the <interaction> element.

• help: The character or string that, when added to the end of a command line, makes the device check the command line's syntax (such as a question mark).
• lineErasure: One of never, first, last, or separate, indicating when a command line entered to check its syntax should be cleared off the command line. Default is never. Depending on the internals of the device's CLI processor, timing might affect how it reacts to the issuing of the control-U line erasure request. If the line is erased too soon, some devices might not process the input command at all or might not emit all of their help text, causing spurious reporting of syntax errors.
  • never: Do not use control-U for line erasure. You should include line erasure explicitly in the <command>.
  • first: Insert the control-U before the command being checked.
  • last: Append the control-U after the command being checked and the help string.
  • separate: Send the control-U alone in a separate interaction (the system generates the interaction).
• regex: true or false to indicate if the <prompt>, <response>, or <error> elements contain regular expressions.
• replaceCtrlCWith: String containing replacement for any control-C character in the command line being checked. Many devices use control-C as a delimiter for multi-line commands (such as banners). The device might interpret such a control-C as an interrupt, killing off the config mode session the system is using for syntax checking. So, here you specify that control-C should be replaced with something non-disruptive.
• responseJitterMilliSeconds: Number that controls how the system reads the device's response, specifying how long a delay there can be between characters.
• timeoutSeconds: Number indicating how long to wait for the device to emit response.
• useCtrlU: true or false to indicate if the system should erase a tested command line using the control-U sequence (which is a standard keyboard input to erase whatever has been typed in to that point).
• <blockEntryError>: String containing an error reported when a block is entered that could not be detected when the block header line is checked for valid syntax. If a block is entered and the device emits an error message matching this element, the interior of the block is not checked. The matching is done per the regex flag set at the interaction level. This interaction must include a <prompt>, which is used as a good response.
• <blockSearch>: Specifies how to find block data in configuration trails other than the running trail, to help the system identify added versus edited blocks. That is, if you are checking the syntax of a template, the system normally checks the running configuration for whether a block is being added or edited. But if the settings reside in a different configuration, the system fails to find it unless you define it here. For example, in Cisco IOS, VLAN, settings might be located in the vlan.dat trail.
  • <commandPattern>: (Required) String containing a case-insensitive regular expression that matches the block header line in the script being validated. This is the command line as you would enter it at the CLI to enter the block.
  • <searchPattern>: (Required) String containing a case-insensitive regular expression that matches the same data in the non-running trail (which might or might not be in the form of command lines. For example, it might contain the output of a show command).
  • <trail>: (Required) String containing the GUID of a configuration trail where the data matching the search pattern appears.
• <ignoredLine>: Regular expression (case insensitive) that specifies a command line that should not be scanned or validated. If a block header or the initial line of a multi-line command happens to match one of these, then the entire block/multi-line command is skipped.
• <contextDefiner>: Specifies inner commands that affect legality of subsequent commands. That is, sometimes a block contains a sequence of ordered commands, where the first command line creates something and the following lines use it. If the system were to validate all the lines, the first one would pass but the subsequent lines would fail due to the component not being created. By using this element, you tell the system not just to validate the first line, but to execute it as well, which renders the subsequent lines valid when they are tested. The system assumes that the line that creates the component is valid only when the component does not exist and is invalid when it already exists (meaning user cannot change that creation line).
  • <parentBlock>: (Required) String containing a case-insensitive regular expression that matches the block header line for blocks that contain the command line sequence of interest.
  • <illegalChangeErrorMsg>: String containing an error message to report to you if you try to syntax scan the command line that creates the component when the component already exists (meaning you are trying to change something that is not allowed to be changed).
  • <command>: (Required) String containing a case-insensitive regular expression that matches the command line that creates the component and leads the sequence of dependent commands.
• <synonym>: Specifies that there are two different commands that identify the same device component. When scanning a script that includes blocks, the system must be able to determine whether a block is new or is already present in the current running configuration. If a device component is defined with one command in the running configuration, but you can use a different command to refer to the same device component in a template, then a <synonym> ties these two commands together as referring to the same device component, and the system will not mistake an edit for an addition.
  
  • <command>: (Required) String containing a case-insensitive regular expression that matches the command as it can appear in the script being scanned. The type can be block or negatedList to indicate where this command can appear. Use block when the device component can be defined in the block header of a block. Use negatedList when the device component can be defined as a sequence of individual commands with the same prefix. Use capture groups to identify bits of the command that should be plugged into the alternateCommand to identify a particular instance of the device component (such as a particular access control list).
  • <alternateCommand>: (Required) String containing a case-insensitive regular expression that matches the command as it can appear in the current running configuration. The type can be set the same as for <command> above. Use capture group numbers within braces to identify where parts of the matched command should be substituted to identify a particular instance of a component.

String containing a regular expression that indicates a syntax error in a device's response

The response is checked against these expressions when the <syntaxErrorCheck> element appears in an <interaction>, and at the end of a Deploy To Active span action.

Contains elements that are to be executed at the end of the <deviceCommand>, even if an error has occurred in preceding elements.

For example, if the system copied a temporary file to a device that should be deleted, the <finallyBlock> can perform the temporary file deletion whether processing the file occurred with or without an error. See this discussion for more details. 

Elements that can be used inside a finally block are: <assert>, <assign>, <condition>, <interaction>, <loop>, <sleep>.

0E8DB22F-DEF8-987E-1AFB-7BE8BBCC9BEA

Logs in to the device. Executed by the system after the connection is made.

1E91FAD6-FBB7-5D7C-120F-ABD77583A086

Discovers core properties, especially the model and operating system version of the device. Executed by the system after the login.

2993A257-F634-4FFA-560F-B921EE64D6AC

Discovers additional properties relevant to image management. Executed by the system after core discoveries during image snapshot and deploy actions.

CC467978-4675-AEA9-A6D1-95A14D51D656

Discovers properties indicating the types of access control lists supported by a device, for the purpose of using them in a quarantine action. The system executes this before making the changes to the device that implement the quarantine.

388DFC1D-2DF0-D833-5762-F5121A797069

Makes a snapshot of the running configuration.

4E005EF8-BAC1-BD15-EF63-DDC6D2547FFE

Makes a snapshot of the startup configuration.

89F733B6-4C59-CF2B-BD10-CD9EA41BA6DB

Makes a snapshot of the current operating system image file.

5421B3AE-2C94-0519-5D07-B4971BB15C7D

Deploys a configuration or a template to the active running configuration.

61A43CB3-2D57-66F7-32E3-59A1A1CD291E

Deploys a configuration or a template to the stored startup configuration.

905E3CF3-2DAE-2FBE-D466-B933FB675F5D

Deploys a new operating system image file.

0F008DB4-DCDB-FE9E-BE50-24A86F88FBE2

Performs a line-by-line syntax check of the commands in a configuration or a template.

7023D2D2-1A14-7DB8-14F6-8B8485C5015E

Commits unsaved changes to the stored configuration.

0DD240D0-5C2E-C943-CBE9-88E2E58F9454

Reboots the device.

E6C631FC-33CA-812E-55D5-6CF772428705

Logs out of the device. Executed by the system as the last phase, to disconnect from the device cleanly, such that the device has no lingering open connection or dangling logged-in user or the like.

A11600D7-30A0-4378-6B50-A7449E2AAE9A

Declares a new operating system image.

B1B1198E-FF0E-7791-D77C-32901BC11901

Deletes the current operating system image file.

C86240C6-54EF-F268-6242-BDC42F74E7C8

Activates the new operating system image (when an activation key is supplied).

AA954719-1830-4C31-EEA8-F0D9CC7982D9

Verifies that an operating system image file has been copied to the device without being corrupted, using md5 checksums.

FB13C6B2-D973-A0F1-1E46-0AA438834D3E

Get the next switch on the path to reach an endpoint. The system executes this as part of the Find Endpoint and Quarantine Endpoint actions.