Examples of HTTP-based XML elements

BMC Network Automation supports HTTP-oriented device communication (HTTPS 1.0, HTTPS 1.1, HTTP 1.0, and HTTP 1.1). The device runs an HTTP server and BMC Network Automation is the client, acting like a web browser, a REST API, or other web services client. To interact with such a device, a device type adapter specifies the requests BMC Network Automation makes to the device's web server, and specifies how to react to the responses sent back.

This topic describes the various child tags allowed within the <httpDeviceCommand> tag, within a given <deviceType> tag that defines a device type adapter. It describes the most commonly used features of those tags and presents examples to help you code your own adapters. For a complete description of all the available elements and attributes, see Device type HTTP interaction XML element reference.

httpInteraction

An <httpInteraction> is a block that defines HTTP-based commands such as get, post, put, and delete to be executed on a target device. This element can include the following sub-elements:

• get: Sends an HTTP GET request.
• put: Sends an HTTP PUT request.
• post: Sends an HTTP POST request.
• delete: Sends an HTTP DELETE request.
• requestHeader: Defines the header of the request. 
• requestBody: Defines the body of the request.
• form: Defines name/value pairs to fill into a received form.
• response: Defines the response that device is going to exhibit after the request execution.
• error: Defines the response that device is going to exhibit after the request execution that indicates an error has occurred.
• capture: Enables you to capture the defined pattern as property from the device response.

Start a web search and capture the result into a property

The following example shows an HTTP interaction that initiates a search on www.google.com and captures the results page into property_1:

<assign property="googleQueries.hl" value="en"/>
<assign property="googleQueries.q" value="Acme"/>
<httpInteraction> 
    <get queries="googleQueries">/search</get>
    <response>Acme</response>
    <capture ignoredSuffix="true">
        <property name="property_1"/>
    </capture>
</httpInteraction> 

Back to top

Fill in a form

The following example shows an HTTP interaction sequence that captures name/value pairs within the form tag parsed from fooForm.html and posts them back to processFooForm.cgi with the modification, field_1=value_1.

<httpInteraction>
    <get>/fooForm.html</get>
    <response>Foo Form</reaponse>
    <form>fooForm</form>
</httpInteraction>
<assign property="fooForm.field_1">value_1</assign>
<httpInteraction>
    <post form="fooForm">/processFooForm.cgi</post>
    <response>Foo Accepted</response>
</httpInteraction>

In the first interaction, the device returns a form that the user would normally fill in using a web browser. In the second interaction, the body of the request is filled in with the name/value pairs for the form fields. The names and values are derived from the properties prefixed with the specified name of the form, which is fooForm in this example. The property name following the prefix is the name of the form field (field_1 in this example). Therefore, the XML code must create and assign values to the properties using the right names in order for the form to be populated correctly.

HTTP responses that involve 4xx or 5xx status codes cause the connection to abort. 3xx redirection codes that are unambiguous are handled automatically, while ambiguous redirection codes cause the connection to abort.

Response packets that contain multiple status codes are not supported. To work around this, you can specify an ignoreExceptions="true" attribute in the <httpInteraction> tag, which causes any HttpException thrown during the execution of that interaction to be ignored.

Back to top

Send HTTP request headers with the request

The following example shows an HTTP interaction sequence that sends request headers with the request.

If <requestHeader> contains the attribute b64Encode="true", the value of <requestHeader> is encoded in Base64. Default value for the b64Encode attribute is false.

<httpInteraction>
    <get>/URI</get>
    <response>200</response>
    <!-- key/value seperated by "." -->
    <requestHeader b64Encode="true">%Name%.%Value%</requestHeader>
    <requestHeader>%Name%.%Value%</requestHeader>
</httpInteraction>

Back to top

Send request body with the POST request

The following example shows an HTTP interaction sequence that sends request body with the POST request:

<httpInteraction ignoreExceptions="true">
    <post>/URI</post>
    <response>201</response>
    <requestBody>%bodyContent%</requestBody>
</httpInteraction>

Back to top

Send request body with the PUT request

The following example shows an HTTP interaction sequence that sends request body with the PUT request:

<httpInteraction>
    <put sensitive="true" sensitivePhrase="%password%">/api/4.0/edges/edge-3/firewall/config/defaultpolicy</put>
    <response>204</response>
    <requestHeader b64Encode="true">Authorization.%username%:%password%</requestHeader>
    <requestBody>               
    	<?xml version="1.0" encoding="UTF-8"?>
	    <firewallDefaultPolicy>
	        <action>%runtime.Permission%</action>
	        <loggingEnabled>true</loggingEnabled>             
	    </firewallDefaultPolicy>
    </requestBody>
</httpInteraction>

In the above snippet, the sensitive and sensitivePhrase attributes enable you to hide a phrase. If you want to hide a phrase, set the sensitive attribute to true, else set it to false. Set the sensitivePhrase attribute to the value you want to hide. It is masked in the transcript anywhere it appears.

Back to top

Send a delete request

The following example shows an HTTP interaction sequence that sends a DELETE request:

<httpInteraction ignoreExceptions="true">
    <delete>/URI</delete>
    <response>204</response>
</httpInteraction>

Back to top