Important

   

Starting from version 8.9.03, BMC Network Automation is renamed to TrueSight Network Automation. This space contains information about TrueSight Network Automation 8.9.03 and the later service packs for 8.9. For earlier releases, see BMC Network Automation 8.9.

Device type HTTP interaction XML element reference

This section describes all of the XML elements allowed in the command execution part of a device type adapter, for interacting with an HTTP- or HTTPS-based device.

These elements can appear within a <httpDeviceCommand> parent element that defines the interactions for a particular part of the processing.

TagDescription
<guid>

Identifies this part of the processing

It 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 that you generated. For a list of standard GUIDs, see Standard GUIDs.

<retry>

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

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

<generalInfo>

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.

<supportsTunneled>

true or false to indicate if <httpDeviceCommand> performs a tunneled snapshot or a tunneled deploy function

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

<assert condition="" onFailure="abort">

String containing a message describing the situation to the user 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).

  • 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.
<assign property="" value="" append="false" omitEOL="false" encodeForUrl="false">

String containing a Bean shell script if the value requires complex calculations supported only by a full programming language (Java)

An <assign> populates a property with a value. That property can then be used in subsequent elements. See assign for more details.

  • property: (Required) The name of the property to be populated.
  • value: The value to be assigned to the property, if it is not calculated by a Bean shell script.
  • append: true or false to indicate if the value is to be appended to any existing value in the property.
  • omitEOL: true or false to indicate if a newline separator should be appended to an existing value before appending the new value.
  • encodeForUrl: true or false to indicate if the value should be encoded to make it suitable for later use as a URL parameter in an HTTP request.
<condition test="">

Contains 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. The <condition> element contains the following attribute:

<httpInteraction disconnect="never" regex="false" responseJitterMilliSeconds="10" timeoutSeconds="60" reconnectTimeoutSeconds="480" kickAtResponseTimeout="" comment="" ignoreExceptions="false" includeResponseHeaders="false" skipExceptionOnBadStatusCode="false">

<get queries="" sensitive="false" sensitivePhrase="">

<post form="" redirectionPrefix="" sensitive="false" sensitivePhrase="">

<put form="" sensitive="false" sensitivePhrase="">

<delete>

<response property="" value="">

<responseBlockReference name="">

<error property="" retry="false">

<errorBlockReference name="">

<capture xpath="" buffer="" defValue="" prefix="" suffix="" includePrefix="false" includeSuffix="false" optionalPrefix="true" optionalSuffix="false" ignorePrefix="false" ignoreSuffix="false" eagerPrefix="false" eagerSuffix="true" append="false" omitEOL="false" ignoreFailure="false" multipleValues="false" index="" iterVariables="" iterArrays="" failsafe="false">

<form>

<requestHeader b64Encode="false">

<requestBody b64Encode="false">

Defines a request to be sent to the device over the HTTP/HTTPS protocol and processing of the device's reply to the request.

  • disconnect: One of never, sometimes, or always to indicate whether the execution of this interaction can 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).
  • regex: true or false to indicate if the <response> or <error> or both elements contain regular expressions.
  • responseJitterMilliSeconds: Number that controls how the system reads the device's response, specifying how long a delay there can be between characters. A longer jitter might be necessary if the device can be bursty sending replies while it is busy doing other things.
  • 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). 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).
  • comment: String containing a comment to insert into the transcript (which the user can see) describing the interaction, to facilitate troubleshooting.
  • ignoreExceptions: true or false to indicate if HttpExceptions are to be ignored while executing this interaction.
  • includeResponseHeaders: true or false to indicate if received HTTP headers should be included in the interaction's response. When true, each header appears on a separate line as name:value pairs for use in captures.
  • skipExceptionOnBadStatusCode: true or false (default) to indicate whether the HttpInterpreter should skip throwing an HttpException if a bad status code is found in the response. Disabling this can be helpful if you want to use an error tag (with a property setting) to perform more fine-grained error handling, instead of just having an exception thrown which aborts the entire HttpDeviceCommand that the httpInteraction is a part of.

    Note: Setting this flag to false is different than setting the ignoreExceptions flag to true. Setting ignoreExceptions to true prevents the entire HttpDeviceCommand that the httpInteraction is a part of, from aborting when an exception is thrown. In addition, skipExceptionOnBadStatusCode also skips the normal trailing processing of the response received (including skipping the matching of error tags).
  • <get>: String containing the URL that is to receive the GET request. See this example.
    • queries: String containing the prefix specifying the subset of properties to use to populate query parameters to send with the GET request when it is executed. That is, any property whose name starts with this prefix, plus a dot, will be added to the request as a query parameter. The name of the query parameter will be the property name stripped of the prefix and the dot.
    • sensitive: true of false to indicate if the request contains sensitive data (such as a password). Such data is sent to the device in the clear, which normally would show up in the transcript in the clear. When this flag is true, the request is masked in the transcript. See this discussion for more details.
    • sensitivePhrase: The string in the request that is to be masked; used only when sensitive is true. If this is present, only part of the request is masked; else, the entire request is masked.
  • <post>: String containing the URL that is to receive the POST request. See this example.
  • form: String containing the name of the form being filled in in the request body.
  • redirectionPrefix: String that specifies a path to prepend to any redirection URLs received in response to this post request. This provides a hint as to how to compose the URL involved, to work around glitches in underlying third-party software.
  • sensitive: true of false to indicate if the request contains sensitive data (such as a password). Such data is sent to the device in the clear, which normally would show up in the transcript in the clear. When this flag is true, the request is masked in the transcript.
  • sensitivePhrase: The string in the request that is to be masked; used only when sensitive is true. If this is present, only part of the request is masked; else, the entire request is masked.
  • <put>: String containing the URL that is to receive the PUT request. See this example.
    • form: String containing the name of the form being filled in in the request body.
    • sensitive: true of false to indicate if the request contains sensitive data (such as a password). Such data is sent to the device in the clear, which normally would show up in the transcript in the clear. When this flag is true, the request is masked in the transcript.
    • sensitivePhrase: The string in the request that is to be masked; used only when sensitive is true. If this is present, only part of the request is masked; else, the entire request is masked.
  • <delete>: String containing the URL that is to receive the DELETE request. See this example.
  • <response>: String containing an expected response or reply. 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 piece of the rely (such as a success code). 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 reply 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 <httpDeviceCommand> terminates; it does not move on to the next interaction; the error is reported to the user as a failed job. Any <finallyBlock> will be executed, as well as the logout <httpDeviceCommand>; 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 that the entire <httpDeviceCommand> should be re-tried once if this error occurs.
  • <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 the XML reference for a complete discussion.
  • <form>: String containing the name of the form in the body of the reply that needs to be filled in as the body of the next request. See this example for more information.
  • <requestHeader>: String that specifies a field to be included in the request's header, formatted as fieldName.fieldValue. Set b64Encode to true if the string may contain binary or if the recipient expects an encoded value, to encode the data in base64. See this example for more information.
  • <requestBody>: String that specifies the body to be included in the request. Set b64Encode to true if the string may contain binary or if the recipient expects an encoded value, to encode the data in base64.
<injectTemplate/>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.

<loop associativeFlag="false" namespace="loop" condition="" counter="" input="" inputSeparator="" start="" stop="" variable="">

<break condition="">

Starts a processing loop and contains the interactions and other elements to be executed repeatedly until the loop termination condition is reached. See loop for more details.

  • 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 evaluates to false, terminates the loop. See Conditional expressions 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 broken up into lines, specifies how to break it up, 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 will contain 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 evaluates to true, causes the loop to be terminated. See Conditional expressions for the supported syntax.
<sleep timeSeconds="0">
Indicates the system should pause for the specified number of seconds before continuing on to the next element. See sleep for more details.

<syntaxErrors>

<syntaxError>

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.
<finallyBlock>

Contains elements that are to be executed at the end of the <httpDeviceCommand>, 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 with an error. See finally for more details.

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

Back to top

Standard <httpDeviceCommand> GUIDs

The following table lists standard GUIDs:

GUIDDescription
0E8DB22F-DEF8-987E-1AFB-7BE8BBCC9BEALogs 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.

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

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

Back to top

Was this page helpful? Yes No Submitting... Thank you

Comments