Common concepts and XML elements
This topic describes general concepts and XML tags that are common to multiple device adapter types.
- Info elements
- Using non-printable characters
- Properties and keyword substitution
- Conditional expressions
- Arithmetic expressions
- Regular expressions
- Syntax not to be used
Info elements
Several elements exist to support the Device Adapter Capabilities report. These are display only elements and do not affect any processing. Names of such elements end with Info, such as <generalInfo> and <supportedOsVersionInfo>. The value for most of these elements is a simple text string, free of all formatting.
Two of these elements, <generalInfo> and <templateFormattingInfo>, support contents that are embedded HTML elements. The information in these elements can be voluminous, so presenting a lot of data requires some way to organize it. To enter HTML elements into these tags, first enter a CDATA tag, followed by the HTML elements. Only a restricted set of elements is supported, not the entire HTML grammar. The HTML must also be well-formed; every start tag must have a corresponding end tag.
The following template shows the supported HTML elements, which you can nest, as needed, to present your information:
<table border="1">
<tr><th>column header</th></tr>
<tr><td>column data</td></tr>
</table>
<ul class="noSpacing">
<li>list item</li>
</ul>
<ol>
<li>list item</li>
</ol>
<p><code>formatted data</code></p>
<p><b>bolded text</b></p>
<p><i>italicized text</i></p>
<p>text <br/> more text</p>
]]></generalInfo>
The only supported attributes are border (for tables) and class="noSpacing" (for more compact unordered lists).
The factory-installed device type adapters have numerous examples that show <generalInfo> and <templateFormattingInfo> CDATA blocks, demonstrating how HTML can be used. Refer to the Cisco IOS and VMware vSwitch device types.
Using non-printable characters
When interacting with a device, it is sometimes necessary to send it a non-printable character, such as a newline, control-C, or control-Y. XML syntax does not allow you to enter non-printable characters into XML content. BMC Network Automation provides you with a way to enter these characters, as follows:
Enter the value as \xnnn – a backslash, followed by the lowercase letter x, followed by the Hex value of the character (as defined by ASCII) in three digits. For example, the control-C character can be entered as: \x003, and a control-Y can be entered as: \x019.
This notation is recognized in the following XML elements. Some accept it in the value of the element; some accept it in an attribute.
Tag | Supported in value? | Attributes |
|---|---|---|
<assign> | yes | value |
<capture> | no | buffer defValue prefix suffix xpath |
<requestHeader> | yes |
|
<requestBody> | yes |
|
<error> | yes |
|
<response> | yes | value |
<syntaxScanInteraction> | no | help |
<interaction> | no | kickAtResponseTimeout |
<command> | yes |
|
<prompt> | yes |
|
<kickAtResponseTimeout> | yes |
|
<textProcessor> | no | search replace |
Properties and keyword substitution
The device type and custom action XML elements support a sort of programming language, where you have statements, if tests, and while or for loops. You also have the notion of variables in the form of properties. A property can either exist or not exist. When it exists, it has a value that can be examined, used, and changed. The existence of a property can also be tested.
To refer to a property, you use a keyword and the system performs a keyword substitution. A keyword is a string with the pattern %...% (a property name surrounded by percent signs). For instance, %property1% refers to the current value of property1. When such a keyword is encountered in the XML code and if a property named property1 exists within the context of the current device connection, its value is substituted in place of the keyword. Otherwise, an empty string is substituted. For example, if the command you want the device to execute is coded as show interface %mgmtIf% and the mgmtIf property has a value of fa0/2/1, then the resulting command is show interface fa0/2/1.
Property substrings are also recognized. For example, a keyword such as %propertyA[3-5]% is replaced by the substring spanning from the 4th through the 6th characters of propertyA's current value (where character counting begins at zero). For example, if propertyA has a value of abcdefgh, then the keyword would be replaced with def.
You create properties by using the <response>, <assign>, or <capture> tags. The system also creates properties, passing information from the user and the internal logic for use in the XML code. Device, agent, global, and runtime substitution parameters can be accessed as properties. For example, %device.realm% refers to the device's realm name.
Keyword substitution is recognized in the following XML elements under the <deviceCommand> and <httpDeviceCommand> elements (used in device type and custom action adapters). Some accept it in the value of the element; some accept it in an attribute.
Tag | Supported in value? | Attributes |
|---|---|---|
<assign> | yes | property value |
<loop> | no | start stop
|
<error> | yes |
|
<response> | yes |
|
<interaction> | no | pauseSeconds |
<command> | yes | sensitivePhrase |
<prompt> | yes |
|
<sleep> | no | timeSeconds |
<capture> |
| buffer prefix suffix xpath |
<get> | yes | sensitivePhrase |
<post> | yes | sensitivePhrase |
<put> | yes | sensitivePhrase |
<requestHeader> | yes |
|
<requestBody> | yes |
|
<delete> | yes |
|
Scope of properties
Normally, once a property is created, it exists for the duration of the connection to the device (that is, until the logout is completed, the connection is broken, and the device action completes). However, some properties are removed based on the their names:
- cmd.*: Any property whose name starts with cmd. exists only to the end of the <deviceCommand> or <httpDeviceCommand> block. It does not cross command blocks.
- loop.*: Any property whose name starts with loop. exists only to the end of the <loop> block. To be more precise, any property named with the namespace attribute as the prefix exists only to the end of its <loop> block, with the default namespace being loop.
- disc.*: Any property whose name starts with disc. is removed during a re-login (such as after a reboot) so that it can be re-discovered correctly. It does not cross device sessions. These properties are also displayed in the transcript.
- fileContents: If a command is performing a configuration snapshot and it captures to the fileContents property, the property is cleared after the data is used to create a configuration (basically at the end of the <deviceCommand> that takes snapshot of the particular configuration). It does not cross commands.
Once a property is removed, you cannot use it in the XML logic unless you create it again. These naming conventions help reduce memory usage (by releasing unneeded properties) and reduce the chance of coding errors (by limiting what properties are available, so you do not code the wrong variable where it should not exist).
Properties set by the system
The following table lists all of the properties populated by the system from the information stored in its database or provided by the user, and describes when they are populated and available for use in the XML code.
In addition, the system populates properties for device, agent, runtime, and global substitution parameters that can be referred to using keywords. The properties are populated prior to the login command. About-substitution-parameters lists the names of the device and agent parameters. For instance, %agent.localhostName% can be coded to plug in the device agent's host name.
Property | Description | Initialization time |
|---|---|---|
accessMode | Primary or auxiliary interface access mode (depending on which interface is used to make the connection); one of telnet, ssh2, https11, https10, http11, http10, webService, or auto | set prior to making the initial connection |
accessPort | Primary or auxiliary interface port (depending on which interface is used to make the connection) | set prior to making the initial connection |
address | Address of the device agent or of the device agent's proxy file server, overridden by the device's NAT address from the primary or auxiliary interface port (depending on which interface is used to make the connection), overridden by the image file server address (when an image file is being transferred) | set before calling any commands that are capable of transferring files (those that copy configuration files or image files) |
cfgBinary | true or false indicating if the configuration file being deployed contains binary data; useful for preventing such files from being deployed in tunneled mode (where the device does not understand the binary stream) | set before calling any configuration deploy commands |
CR | Literal carriage return character (\r or hex \x00D or unicode \u000D) | set prior to making the initial connection |
defaultResponseTimeoutSeconds | From the property, deviceDefaultResponseTimeoutSeconds in the global.properties.imported file, defaulting to 60 | set prior to making the initial connection |
deviceAddress | Primary or auxiliary interface address (depending on which interface is used to make the connection) | set prior to making the initial connection |
deviceCategory | Name of the category of the device | set prior to making the initial connection |
deviceName | Name of the device | set prior to making the initial connection |
disconnectTimeoutSeconds | From the property, deviceDisconnectTimeoutSeconds in the global.properties.imported file, defaulting to 15 | set prior to making the initial connection |
discoverTransferMode | true or false indicating if the device file transfer mode is set to auto | set for the login command |
doCommitAllContexts | From user; true or false depending on the user's selection of the Commit All Security Contexts When Applicable option in the Commit action. | set for the commit command
|
empty | Literal “” or the empty string; %empty% is useful in conditions for checking whether another property has a non-zero-length value | set prior to making the initial connection |
endpointAddress | From user; the endpoint address entered into a Find Endpoint or Quarantine action | set for the getNextSwitch command |
endpointMacAddress | Discovered when searching for an endpoint, contains the endpoint's MAC address on its connected switch | set for the getNextSwitch command |
eraseFilesystem | From user; true or false based on the user choice to delete the current image prior to deployment of a new image, on IOS systems that do not support a delete command for a single file (necessitating the entire filesystem to be erased) | set for Cisco IOS devices only, for the image deploy command |
escape | Literal ASCII escape character (hex \x01B or unicode \u001B) | set prior to making the initial connection |
fileContents.* | From the script being deployed using tunneled mode, divided into lines with successive lines assigned to fileContents.0, fileContents.1, fileContents.2, etc. | set for the deploy command |
fileDigestValue | Calculated MD5 digest or checksum value of the operating system image file that you are deploying | set for the image verification command |
ftpPassword | FTP password specified in the device agent (unencrypted) | set before calling any methods that are capable of transferring files (those that copy configuration files or image files) |
ftpRestrictedPathAccess | From the FTP User Restricted to Home Directory setting on the Admin > Device Agent page When this flag is checked, the property value is set to true to allow for the conditional FTP command syntax | set prior to making the initial connection |
ftpUsername | FTP user name specified in the device agent | set before calling any methods that are capable of transferring files (those that copy configuration files or image files) |
imageArchive | Set to true when an image filename matches the <imageArchiveFilename> regular expression. During Snapshot OS Image, the current image filename is evaluated; during Deploy OS Image, the new image filename is evaluated. | set for the image snapshot and image deploy commands |
imageRecoveryInProgress | Set to true when an image deploy command is being called to recover the original image; else does not exist | set prior to the deploy image command |
injectionTemplate | Set to true or false to indicate if the template being deployed contains an injection template | set before calling any configuration deploy commands |
isWindowsOS | Set to true if the underlying operating system is Windows; else, false | set prior to making the initial connection |
LF | Literal newline or line feed character (\n or hex \x00A or unicode \u000A) | set prior to making the initial connection |
managedBySerial | Set to true when the device security profile indicates that login is through a terminal server, to execute the extra terminal server login steps; else, does not exist | set for the login command |
maxBinaryTransferDurationSeconds | From the system parameter, Timeout for Image File Transfers | set before calling any commands that are capable of transferring files (those that copy image files) |
maxTextTransferDurationSeconds | From the system parameter, Timeout for Script File Transfers | set before calling any commands that are capable of transferring files (those that copy configuration files) |
mergeType | Indicates how the script is to be deployed; one of smartMerge or fullMerge, based on user's selection of the Incremental Merge or Full Merge options in the Deploy to Active action. Used if the device has distinct commands for the two modes and does its own Smart Merge | set before calling any configuration deploy commands |
password | The login password; from device security profile, or from job if the system parameter is set to enter credentials at job creation time (unencrypted) | set for the login command |
privPassword | The privileged password; from device security profile, or from job if the system parameter is set to enter credentials at job creation time (unencrypted) | set for the login command |
privUsername | The privileged user name; from device security profile, or from job if the system parameter is set to enter credentials at job creation time | set for the login command |
rebootTimeoutSeconds | From the system parameter, Timeout for Re-Establishing Connection After a Reboot | set for the image deploy command |
reconnectTimeoutSeconds | From the attribute, reconnectTimeoutSeconds in <interaction> or <httpInteraction> | set for the login command when re-logging in |
saveChoice | From user reboot mode choice indicating what to do if prompted about unsaved changes; value is y when user selected to save; value is n when user selected to discard; property is non-existent during reboots done as part of a Deploy to Stored or custom action. | set for the reboot command |
scpPassword | SCP password specified in the device agent (unencrypted) | set before calling any file-transfer-capable method (those that copy configuration files or image files) |
scpRelativeHomeDirectory | SCP transfer relative home directory specified in the device agent | set before calling any file-transfer-capable method (those that copy configuration files or image files) |
scpUsername | SCP user name specified in the device agent | set before calling any file-transfer-capable method (those that copy configuration files or image files) |
securityContextNameFromUser | The security context name from the device
| set for the login command |
securityContextTypeFromUser | The type of security context from the device; one of admin, system, userDefined, or none | set for the login command |
space | Literal space or blank character (hex \x020 or unicode \u0020) | set prior to making initial connection |
squeezeTimeoutSeconds | From the property, squeezeTimeoutSeconds in the global.properties.imported file, defaulting to 900 | set for the discover image details command |
stopTunnelingOnSyntaxErrors | From user's selection for the Stop on Syntax Errors (Only Tunneled Transfers) option in the advanced options of the Deploy to Active action | set for the Deploy to Active action |
tab | Literal ASCII tab character (\t or hex \009 or unicode \u0009) | set prior to making the initial connection |
targetImageFilesystem | From the user's choice of where to deploy a new operating system image file | set prior to running the discover image details command |
targetSecurityContextName | Name of the security context that is used to create (or destroy) a new guest context on a load balancer or firewall host during container configuration. This value is system for the Cisco FWSM device type. It can be null. | set after successful login |
terminalLogin | Set to true when user is connecting to the device via a Telnet or SSH Session or the SSH proxy | set for the login command |
terminalPrivLogin | Set to true when user is connecting to the device via the SSH proxy and has not used the -non-priv argument | set for the login command |
terminalServerPassphrase | From device security profile (unencrypted) | set for the login command |
terminalServerPassword | From device security profile (unencrypted) | set for the login command |
terminalServerUsername | From device security profile | set for the login command |
transferActivation | Operating system image activation key | set for the image deploy command |
transferAlias | When deploying an operating system image file, the name that the image file will have when it is deployed in the device's filesystem; this is usually the name of the device agent's temporary file | set for the image deploy command |
transferFilename | Name of the file being transferred between the device and the device agent | set before calling any file-transfer-capable method (those that copy configuration files or image files) |
transferMode | Primary or auxiliary interface file transfer mode (depending on which interface is used to make the connection); one of tftp, ftp, scp, tunneled, or auto | set prior to making the initial connection |
transferPath | Directory where the temporary file resides in the device agent's filesystem | set before calling any file-transfer-capable method (those that copy configuration files or image files) |
username | The login user name, from device security profile, or from job if the system parameter is set to enter credentials at job creation time | set for the login command |
Properties used by the system
Once a <deviceCommand> or <httpDeviceCommand> completes execution, control returns to the Java logic, which might look for properties to be populated by the XML logic. If a property is not populated, no error occurs, but the system might be lacking information it displays to the user. The following table describes those properties:
Property | Purpose | Initialized by |
|---|---|---|
cfgFilename | Contains the name of a configuration file on the device; used to set the file name of a binary configuration | snapshot commands |
decodedContents | Contains the ASCII or user-readable version of a binary configuration; used when the <supportedTrail> specifies <capturesDecoded> as true | snapshot commands |
disc.model | Contains the discovered model of the device, which is saved and displayed with the device thereafter; if no model can be discovered, the device defaults to the Unknown model | discover core |
disc.imageName | Contains the discovered operating system image name and version, which is saved and displayed with the device and configurations thereafter and used for OS image name auto-grouping; this is a displayable name and appears in the OS image library | discover core |
disc.imageFilename | Contains the name of the currently running operating system image file on the device; used during image snapshot to preserve the name as the device identifies it, either on the remote image file server or in the OS image library | discover core or discover image details |
disc.version | Contains the discovered operating system version major.minor.build parts; used for testing against the minVersion value of subsequent <deviceCommand> or <httpDeviceCommand> | discover core |
disc.versionShort | Contains the discovered operating system version major.minor parts; used for OS major/minor release auto-grouping | discover core |
disc.supportsFtp disc.supportsScp | When the property exists, then that access mode is considered to be supported; used when the device file transfer mode is set to auto, to set the transfer mode to a concrete mode | discover core |
disc.imageFilesystem | Contains the name of the filesystem where the current operating system file is located; used to determine if a new image file will fit, when it is being deployed onto the same file system | discover core |
disc.imageFileSize | Contains the size of the current operating system image file; used to determine if a new image file will fit without deleting the current image file | discover image details |
disc.imageFilesystemTotalSize disc.imageFilesystemTotalSizeUnits disc.imageFilesystemUsedSize disc.imageFilesystemUsedSizeUnits disc.imageFilesystemFreeSize disc.imageFilesystemFreeSizeUnits disc.targetImageFilesystemFreeSize disc.targetImageFilesystemTotalSize disc.targetImageFilesystemUsedSize disc.targetImageFilesystemFreeSize disc.targetImageFilesystemTotalSize disc.targetImageFileSizeUnits | Used to verify whether the new operating system image file will fit on the disk, when device supports size discovery by discovering combination of these properties | discover core and/or discover image details |
disc.memoryTotalSize disc.memoryTotalSizeUnits disc.memoryUsedSize disc.memoryUsedSizeUnits disc.memoryFreeSize disc.memoryFreeSizeUnits | Used to verify whether the new operating system image will fit in memory, when device supports size discovery by discovering combination of these properties and when device requires memory sizing be validated | discover core and/or discover image details |
disc.baseHostname disc.securityContextName disc.securityContextType | Contains the name of the host system that owns a security context, the discovered context name and type; the name and type are used to validate user input for those values (to verify the context being accessed is the context the user specified); the name is used to populate the user-defined context name when the user enters none; the base host name is used to auto-group the security contexts that reside on the same host together | discover core |
disc.endpointPortLoc disc.endpointPortType | Where the endpoint being searched for in a Find Endpoint or Quarantine action is physically attached; contains the switch port location and type; used to quarantine | get next switch command |
disc.nextSwitchAddress | The next switch in the path to reach the endpoint being searched for during the Find Endpoint or Quarantine actions; used to find the device in the database that is to be searched next for the endpoint | get next switch command |
disc.supportsVlanAcl | Whether or not the device supports VLAN ACLs; used to quarantine using the right type of ACL | discover ACL details |
fileContents | Contains configuration captured from a command's output, usually in a snapshot command in tunneled mode | snapshot commands |
filenameUsedByDevice | Contains a file name that the device uses in file transfer requests as the destination file name; used to find the file on the device agent's filesystem after the file transfer is done | snapshot commands |
result.* | Contains results gathered while running a custom action; displayed in job details; used to populate dynamic fields when custom action is configured to do so | custom action commands |
hardwareInventoryIosEntity.name.* hardwareInventoryIosEntity.descr.* hardwareInventoryIosEntity.pid.* hardwareInventoryIosEntity.vid.* hardwareInventoryIosEntity.sn.* | Results of capturing the name, descr, pid, vid, and sn columns of a show inventory command's output; used to populate the Cisco IOS hardware inventory | discover core |
hardwareInventoryMemory.name.* hardwareInventoryMemory.bytesUsed.* hardwareInventoryMemory.bytesTotal.* hardwareInventoryMemory.bytesFree.* | Results of capturing memory information; used to populate the Cisco IOS hardware inventory; for used, total, and free, these contain bytes counts; all three need not be discovered; if only two are discovered, the third is calculated | discover core |
hardwareInventoryFileSystem.name.* hardwareInventoryFileSystem.bytesUsed.* hardwareInventoryFileSystem.bytesTotal.* hardwareInventoryFileSystem.bytesFeee.* | Results of capturing filesystem information; used to populate the Cisco IOS hardware inventory; for used, total, and free, these contain bytes counts; all three need not be discovered; if only two are discovered, the third is calculated | discover core |
imageChecksumVerified | When the device is able to verify an image file but is unable to emit the file's MD5 checksum, result of performing a verification of a new operating system image file; a true value indicates success; anything else or this property not existing indicates a failure | verify image |
imageDigestValue | The MD5 checksum calculated in a new operating system image file copied into the device | verify image |
transferredBytes | Number indicating how many bytes were transferred in a TFTP PUT request (copying a file from the device to the device agent); used to determine if a possibly asynchronous TFTP request is completed and the file is fully written to the device agent's filesystem | snapshot commands |
useDigest | When this property exists, indicates that the device, during a new operating system image file verification, has calculated and emitted the new file's MD5 checksum, which the system can use to compare against the MD5 checksum it calculated for the file residing in the device agent | verify image |
Conditional expressions
When developing the logic to execute commands or requests on a device, you might need to perform conditional processing. For example, the <condition> element allows you to check if some state is present and execute its inner elements only when true; the inner elements are skipped otherwise. The syntax for a conditional expression supports many types of checks and comparisons and is a little language of its own. The following describes the language in detail. It can be used in the following elements:
- <condition test="expression">
- <assert test="expression">
- <break condition="expression">
- <loop condition="expression">
An expression is made up of boolean tests on string values (either a literal value or a keyword), where two operands are combined with an operator, with one or more spaces before and after the operator. The result of the test is either true or false. The expression is made up of the following clauses, which can be grouped using parentheses (to indicate precedence and to ensure correct evaluation):
Clause | Description |
|---|---|
c1 -AND- c2 | Logical AND of the two boolean conditions (true if both conditions are true) |
v1 -CONTAINS- v2 | Tests whether the string value v2 is contained within the string value v1 |
v1 -EQ- v2 | The strings on the left and the right have the same value |
-EXISTS- p1 | The property by the name following the operator exists; the syntax here requires the use of only the property name (not a keyword with percent signs); for example, -EXISTS- cmd.myPropertyName |
v1 -GE- v2 | v1 is greater than or equal to v2 |
v1 -GT- v2 | v1 is greater than v2 |
v1 -LE- v2 | v1 is less than or equal to v2 |
v1 -LT- v2 | v1 is less than v2 |
-NOT- c1 | The logical reverse of the expression (true flips to false, and false flips to true) |
c1 -OR- c2 | Logical OR of the two boolean conditions (true if either or both conditions are true) |
c1 -XOR- c2 | Logical exclusive OR of the two boolean conditions (true if one condition is true, but not both) |
The order of precedence must be specified by using parentheses, as shown in the following example:
When string inequality comparisons are evaluated, if both values involved start with numeric digits, the algorithm attempts to perform a numeric rather than a string-based comparison. Numeric comparisons can have embedded decimals. For example, “1.1.10 -GT- 1.1.9" evaluates to true.
Typing is implicit. It cannot be declared explicitly. It is usually helpful to think of all values as text strings, especially when keywords are involved, plugging in varying values. Keep in mind that numeric values are supported and are compared in the natural way.
Arithmetic expressions
Certain numeric values in the XML syntax support the use of an arithmetic expression, where you can calculate a value from hard-coded numbers or keywords. This is an expression whose result is a number (versus the preceding conditional expression, whose result is a boolean true or false).
Arithmetic expressions are supported in the following XML elements:
- <interaction reconnectTimeoutSeconds="expression">
- <httpInteraction reconnectTimeoutSeconds="expression">
- <interaction timeoutSeconds="expression">
- <httpInteraction timeoutSeconds="expression">
An arithmetic expression is made up of two decimal digit operands with an operator in between, with one or more spaces before and after the operator. The following arithmetic expressions are supported. They can be combined using parentheses to ensure accurate evaluation.
Clause | Description |
|---|---|
n1 -PLUS- n2 | Adds the values of n1 and n2 |
n1 -MINUS- n2 | Subtracts n2 from n1 |
n1 -MULT- n2 | Multiplies n1 by n2 |
n1 -DIV- n2 | Divides n1 by n2 |
n1 -MOD- n2 | Remainder after dividing n1 by n2 |
Regular expressions
Java-style regular expression syntax (also known as regex syntax) is supported in numerous device adapter elements and attributes. A regex specifies a pattern for matching strings. The following table provides summary of commonly-used syntax. You can find the complete information in the javadoc page for the java.util.regex.Pattern class available from Oracle.
Character(s) | Description | Meaning |
|---|---|---|
^ | caret | Matches the start of the line |
$ | dollar sign | Matches the end of the line |
. | dot | Matches a single character |
.* | dot followed by asterisk | Matches any number of any character; the dot means any character and the asterisk means any number of them |
.+ | dot followed by plus sign | Matches one or more of any character; the dot means any character and the plus sign means one or more |
\s | backslash followed by lowercase letter s | Matches any single whitespace character |
\s* | backslash followed by lowercase letter s followed by asterisk | Matches any number of whitespace characters, including none |
\S | backslash followed by uppercase letter S | Matches any single non-whitespace character |
\S+ | backslash followed by uppercase letter S followed by plus sign | Matches one or more non-whitespace characters |
\d | backslash followed by lowercase letter d | Matches a single decimal digit |
\d+ | backslash followed by lowercase letter d followed by plus sign | Matches one or more decimal digits |
\ | backslash | Escapes a regex metacharacter For example: \$ looks for a literal dollar sign; \. looks for a literal dot |
(\S+) | left parenthesis, followed by backslash, followed by uppercase letter S, followed by right parenthesis | Matches one or more non-whitespace characters, creating a capture group to extract the text that matched (which can be referred to by number and substituted in elsewhere) |
(abc|def|ghi) | left and right parentheses around strings to match separated by bar | Matches one of the enclosed strings – either abc, def, or ghi Note that this also defines a capture group which may or may not be desirable depending on the context; make this a non-capturing group by adding ?: after the left parenthesis: (?:abc|def|ghi) |
Regular expressions can be used in the following XML elements and attributes in those elements:
Tag | Supported in value? | Attributes |
|---|---|---|
<blockSearch> | yes for <commandPattern> element yes for <searchPattern> element |
|
<capture> | no | buffer |
<commentBlocks> | yes for <begin> elements yes for <end> elements yes for <include> elements yes for <exclude> elements yes for <mask> elements |
|
<commentLines> | yes for <line> elements |
|
<contextDefiner> | yes for <command> element yes for <parentBlock> element |
|
<error> | yes |
|
<imageArchiveFilename> | yes |
|
<prompt> | yes |
|
<response> | yes |
|
<sensitiveLines> | yes for <line> elements |
|
<sortedCommand> | yes for <line> elements | parentBlockPattern |
<sortedParameter> | yes for <command> element |
|
<syntaxScanInteraction> | yes for <ignoredLine> element |
|
<syntaxError> | yes |
|
Syntax not to be used
If you examine a factory-installed device adapter, one of your older custom adapters, or the DeviceTypeMap.xsd schema file, you might notice elements and attributes that are not documented elsewhere in this topic or related topics. You should not use these elements in your own adapters. The syntax may be obsolete, or may be intended for internal BMC use only. Obsolete elements can still be present and are considered valid, but the setting is ignored. The following table describes such elements:
Element/Attribute | Status | Explanation |
|---|---|---|
<id> | internal use | Before BMC Network Automation used GUIDs to identify adapters, it used simple numeric IDs, which were not used anymore when device adapters were made more user-extensible. |
<supportsSsh1Access> | obsolete as of 8.3.00 | BMC Network Automation has dropped support for SSH protocol version 1. |
<supportsPrivPassword> | obsolete as of 8.7.00.001 | Indicated that device had a privileged mode; dropped when such information became unnecessary. |
<rebootsAfterLoad> | obsolete as of 8.7.00.001 | Indicated that deploy of an operating system image automatically rebooted; dropped when such information became unnecessary. |
<supportsDiskImageLoad> | obsolete as of 8.2.00 | Indicated that a file system was available for image deployment; replaced with <supportedFileSystems>. |
<supportsPCMCIAFlashCardImageLoad> | obsolete as of 8.2.00 | Indicated that a file system was available for image deployment; replaced with <supportedFileSystems>. |
<containerVlbClassName> | obsolete as of 8.1.04 | Indicated a virtual load balancer Java class name for CLM container management; dropped when such information became unnecessary. |
<javaDeviceCommand> <javaCall> | internal use | Used to implement a custom protocol to a device, where Java code development is required, which is not user-extensible. |
key="some.property.name" | internal use | Used internally for name and message localization (into the local language), where values are extracted from a properties file that you cannot change and should not use. If you copy/paste an element from a factory-installed adapter with a key attribute, you should delete the key attribute and enter a value for the element in your local language. For example, if a factory-installed adapter has: <name key="trailName.someTrailIdString"/> When you copy this to your own adapter, replace it with: <name>My Own Trail Name</name> |