HTTP adapter request and response for a Put action

The Put action is similar to the post action except that the Put action can also send a data file to the URL. The Put action requires the enclosed document to be stored under the specified URL.

Data is sent in the following formats using the Put action:

Simple text data
XML data using <parent> and <child> elements

The following figure describes the elements of an HTTP adapter request with a Put action.

Elements of an HTTP adapter request with a Put action

Element

Description

Required

Specifies the name of the adapter

Default value: HTTPAdapter

Specifies the URL where the content is to be sent

Yes

<use-ssl- certificate>

Specifies whether to establish a secure connection

Set the value of this element to true when <action> uses HTTPS.
Set the value of this element to false or leave it blank when <action> uses HTTP.

Valid values: true, false (default)

<install-certificate>

Specifies whether to install certificates

Set the value of this element to true if you prefer to have security certificates installed automatically (a common practice). Set the value of this element to false if you prefer to manually export the security certificate from the specified target server and manually import it into the BMC Atrium Orchestrator's local peer's cacerts file (a rare practice).

Valid Values: true, false (default)

<allow-unsigned-certificate>

Specifies whether to allow unsigned certificates from trusted zones

Set the value of this element to true, if you are using self-signed SSL certificates (a common practice).

On ecommerce sites or military installations, if you need to use signed certificates such as Verisign or Thawte, set the value of this element to false (a rare practice).

Valid values: true, false (default)

<pass-phrase>

Specifies the Java Standard Trust Key Store passphrase

Warning

The value of the <passphrase> element is the passphrase for the cacerts certificate stored on the BMC Atrium Orchestrator local peer (CDP or AP) and not the specified target host.
Changing the passphrase can be tricky and might destroy the cacerts security file integrity.

Verify the cacerts passphrase using the following command in UNIX or Linux:

$ /opt/bmc/ao/cdp/jvm/bin/keytool -list -keystore
/opt/bmc/ao/cdp/jvm/lib/security/cacerts

Default value: changeit

<file-path>

Specifies the path of the file to be sent to the URL

<file-content-type>

Specifies the content type of the file to be uploaded

Default value: Plain

Conditional; used if the adapter request contains a <file-path> element

<data-format>

Indicates the desired data type for the adapter response

Valid values: xml, html (default)

<ntlm-authentication>

Indicates whether to use NTLM authentication for the target server for the specified user credentials

The adapter supports both NTLMv1 and NTLMv2 authentication.

Valid values: true, false (default)

If the value of the parameter is true, the adapter uses NTLMv1 or NTLMv2 authentication (based on the server configuration) to authenticate the user. Else, the adapter uses basic authentication.

<user-name>

Specifies the user name to be used for basic authentication

Specifies the password corresponding to the user name provided for basic authentication

<character-set>

Specifies the supporting CharSet

Also called character set, it includes identifiers describing a series of universal characters.

Note

If you do not specify the supporting character set, the adapter response is parsed based on the character set in the HTTP response header.

<http-connection-properties>

Specifies an XML document that includes HTTP connection properties, which contain the <user-name> and <password> elements for basic or NTLM authentication

The XML document also includes information such as content-type in the HTTP request header before executing the HTTP request.
For an example of connection properties, see XML sample of <http-connection-properties> element.

Note

The user name and password properties are not set in the request header and are case sensitive.

<user-name>

Specifies the user name required for basic or NTLM authentication specified in <http-connection-properties>

Specifies the password corresponding to the user name specified in <http-connection-properties>

<data>

Specifies the information to be sent

The information can be simple text (see XML sample of simple text format) or an XML document to specify parent and child (see XML sample of parent and child format) tags.

<signature-properties>

Contains the elements that specify information about the public key (X.509 certificate) and the private key that are used for the digital signature

Note

If you specify signature-properties in the adapter configuration and an adapter request, the values in the request override the values in the configuration.

The <signature-properties> element can contain the mode attribute that specifies the format in which the public (X.509 certificate) and private keys are provided for signing the HTTP request.

You can provide the keys using one of the following formats:

Java Keystore (JKS)
Privacy Enhanced Mail (PEM)
Definite Encoding Rules (DER) files
Base64-encoded PEM

Valid values:
<signature-properties mode="keystore"> (default)
<signature-properties mode="key-files">
<signature-properties mode="key-data">

<keystore-file>

Specifies the path to the JKS that contains the client certificate

Conditional; required when <signature-properties mode="keystore">

<key-password>

Specifies the password of the key contained in the JKS

Note

If you do not specify <key-password>, then the value of <keystore-password> is used as the key password.

<keystore-password>

Specifies the password to the JKS

Conditional; required when <signature-properties mode="keystore">

<alias>

Specifies the name of the alias in the JKS that identifies the Public Key Certificate (PKC) that the web server uses to authenticate the client

Note

The value of the <alias> element is verified only when <install-certificate> is set to true and <allow-unsigned-certificate> is set to false.

Conditional; required when <signature-properties mode="keystore">

<private-key-file>

Specifies the file containing the private key that is used to sign the HTTP request

The adapter supports the following formats:

Base64-encoded PEM
DER

Conditional; required when <signature-properties mode="key-files">

<certificate-file>

Specifies the file containing the public key (X509 Certificate).

The adapter supports the following formats:

Base64-encoded PEM
DER

Conditional; required when the signature mode is <signature-properties mode="key-files">

<private-key-data>

Contains an XML file specifying the private key in an Base64-encoded PEM format

For example:
<private-key-data> ---- BEGIN PRIVATE KEY ----
MIICdQIBADANBgkqhkiG9w0
BAQEFAASCAl8wggJbAgEAAo
GBAKomKro6VbW4PeQtUhNz
ZpSH26vbBTBtH1r4EjnIv4vnh
SyyA62ewpROVNn0Spvjo
BFwE88HcX3tXym/zbVgtd
Pke9K+SYHP6CWdiLqn
........
---- END PRIVATE KEY ----</private-key-data>

Conditional; required when <signature-properties mode="key-data">

<certificate-data>

Contains an XML file specifying the public key (X509 Certificate) in an Base64-encoded PEM format

For example:
<certificate-data> ---- BEGIN CERTIFICATE ----
MIICdzCCAeCgAwIBAgIFXseN1xYwDQYJKoZIhvcNAQEFBQ
AwUzELMAkGA1UEBhMCVVMxEzARBgNVBAoTCkFtYXpvbi5jb20x
DDAKBgNVBAsTA0FXUzEhMB8GA1UEAxMY
........
---- END CERTIFICATE ----</certificate-data>

Conditional; required when <signature-properties mode="key-data">

<enable-json-conversion>

Specifies whether the adapter should treat the input data in the request and the data received in the adapter response as a JavaScript Object Notation (JSON) string

If <enable-json-conversion> is set to true, the input data in the request (XML format) is converted to a JSON string after parsing and the response (if a JSON string) is converted to an XML format.

Valid values: true, false (default)

Notes

The JSON string in the response is parsed to XML only if <enable-json-conversion> is set to true and <data-format> is set to XML.
If you specify <enable-json-conversion> in both the adapter configuration and the adapter request, the value in the adapter request overrides the value in the configuration.

Recommendation

The HTTP adapter supports both <httpAdapterRequest> and <http-adapter-request> tags for an adapter request; however, only the <httpAdapterResponse> tag is supported for an adapter response.

BMC recommends that you use the <httpAdapterRequest> root tag for the adapter request.

The following figure shows an XML sample of the HTTP adapter request for <http-connection-properties> element.

XML sample of <http-connection-properties> element

<http-connection-properties>
          <Content-Type>text/html</Content-Type>
          <Accept>Yes</Accept>
          <Blob></Blob>
</http-connection-properties>

XML sample of simple text format

Sample data that will be posted.

XML sample of parent and child format

<parent>
<child>child value</child>
</parent>

The following figure shows an XML sample for the HTTP adapter request when the adapter supports mutual authentication.

XML sample of the HTTP adapter request when the adapter supports mutual authentication

<httpAdapterRequest>
<use-ssl-certificate>true</use-ssl-certificate>
<install-certificate>true</install-certificate>
<signature-properties>
   <keystore-file>server.jks</keystore-file>
   <keystore-password>changeit</keystore-password>
   <alias>1</alias>
</signature-properties>
<action>https://10.128.249.45:8087/</action>
</httpAdapterRequest>

The following figure shows an XML sample for the HTTP adapter request with JSON data support.

XML sample of the HTTP adapter request with JSON data support

<httpAdapterRequest>
     <use-ssl-certificate>false</use-ssl-certificate>
     <install-certificate>true</install-certificate>
     <allow-unsigned-certificate>true</allow-unsigned-certificate>
     <enable-json-conversion>true</enable-json-conversion>
     <data-format>xml</data-format>
     <strip-namespace-from-response>true</strip-namespace-from-response>
     <action>http://10.128.249.29:8089</action>
</httpAdapterRequest>

The following figure shows an XML sample for the HTTP adapter request when the adapter supports uploading files.

XML sample for the HTTP adapter request when the adapter supports uploading files

<httpAdapterRequest>
<action>http://localhost:6080/baorepo/resources</action>
<file-path>C:\bmc-workspace\ao\rel\20.11.03.00-R\adapters\adapter-http\target\aroar\ro-adapter-http_20.11.03.00.aroar</file-path>
<file-content-type>application/java-archive</file-content-type>
<data-format>XML</data-format>
<http-connection-properties>
   <Authorization>Basic YWRtaW46YWRtaW4xMjM=</Authorization>
   <Content-Type>application/java-archive</Content-Type>
   <Resource-Type>ADAPTER</Resource-Type>
   <Slug>ro-adapter-http_20.11.03.00.aroar</Slug>
</http-connection-properties>
</httpAdapterRequest>

The following figure shows an XML sample of the HTTP adapter response with a Put action.

XML sample of the HTTP adapter response with a Put action

<httpAdapterResponse>
<metadata>
   <status>success</status>
</metadata>
<status-line>
   <code>200</code>
   <reason>OK</reason>
</status-line>
<header-lines>
   <Server>Apache-Coyote/1.1</Server>
   <Content-Type>text/plain;charset=ISO-8859-1</Content-Type>
   <Content-Length>386</Content-Length>
   <Date>Mon, 05 Apr 2010 09:29:41 GMT</Date>
</header-lines>
<message-body>
<Html>
<Title>Testing Application for HTTP Adapter</Title>
<Head></Head>
<Title>TestingApplication for HTTP Adapter</Title>
<Head></Head>
<Body>Hi, I am inside the doPut() Method of the EchoServlet,<br><br><br><br> <br><br>
Query String : null<br><br><BR><BR>
XML Text : This is the Test File.
<Center>Copyrights ©, Developed By Test User </Center>
</Body>
</Html>
</message-body>
</httpAdapterResponse>

The following figure shows an XML sample of the HTTP adapter response that contains a JSON string in <message-body> of an HTML response before parsing.

XML sample of the HTTP adapter response with a JSON string in <message-body> before parsing

<httpAdapterResponse>
  <metadata>
    <status>success</status>
  </metadata>
  <status-line>
    <code>200</code>
    <reason>OK</reason>
  </status-line>
  <header-lines>
    <Transfer-encoding>chunked</Transfer-encoding>
    <Content-type>text/html</Content-type>
  </header-lines>
  <message-body>
    <html lang="en-US">
      <head>
        <title>BBDA API</title>
        <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
      </head>
      <body>
         {"job-approval":{"result":"approve","detail":"dsd"}}
        <h1>Accepted request</h1>
      </body>
    </html>
  </message-body>
</httpAdapterResponse>

Note

The JSON string is processed only if it is contained in the <body>, <message-body>, or <non-xml-data-response> elements.

The following figure shows an XML sample of the HTTP adapter response that contains a JSON string in <message-body> of an HTML response after parsing.

XML sample of the HTTP adapter response with a JSON string in <message-body> after parsing

<httpAdapterResponse>
     <metadata>
       <status>success</status>
     </metadata>
     <status-line>
       <code>200</code>
       <reason>OK</reason>
     </status-line>
     <header-lines>
       <Transfer-encoding>chunked</Transfer-encoding>
       <Content-type>text/html</Content-type>
     </header-lines>
     <message-body>
       <html lang="en-US">
         <head>
           <title>BBDA API</title>
           <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
         </head>
         <body>
           <job-approval>
             <detail>dsd</detail>
             <result>approve</result>
           </job-approval>
           <h1>Accepted request</h1>
         </body>
       </html>
     </message-body>
</httpAdapterResponse>

XML sample of the HTTP adapter request when the input is XML data converted to JSON and the output is JSON converted to XML data

<httpadapterRequest>
<enable-json-conversion>true</enable-json-conversion>
<action>http://10.128.249.76:8080/DemoJSONNew/JSONServlet2</action>
<data-format>xml</data-format>
<data>
   <Demo>
     <employees>
   <employee>
     <name>User1</name>
     <age>23</age>
   </employee>
   <employee>
     <name>User2</name>
     <age>22</age>
   </employee>
   <employee>
     <name>User3</name>
     <age>22</age>
   </employee>
   <employee>
     <name>User4</name>
     <age>22</age>
   </employee>
     </employees>
     <testing1>testing 1</testing1>
     <testing2>testing 2</testing2>
     <testing3>testing 3</testing3>
   </Demo>
</data>
</httpadapterRequest>

XML sample of the HTTP adapter response when the input is XML data converted to JSON and the output is JSON converted to XML data

<httpAdapterResponse>
<metadata>
   <status>success</status>
</metadata>
<status-line>
   <code>200</code>
   <reason>OK</reason>
</status-line>
<header-lines>
   <Server>Apache-Coyote/1.1</Server>
   <Content-Type>application/json</Content-Type>
   <Content-Length>128</Content-Length>
   <Date>Tue, 31 Jul 2012 09:53:05 GMT</Date>
</header-lines>
<message-body>
   <employees>
     <e>
       <age>23</age>
       <name>User1</name>
     </e>
     <e>
       <age>22</age>
       <name>User2</name>
     </e>
     <e>
       <age>22</age>
       <name>User3</name>
     </e>
     <e>
       <age>22</age>
       <name>User4</name>
     </e>
   </employees>
</message-body>
</httpAdapterResponse>

HTTP adapter request and response for a Put action

(archive) BMC Atrium Orchestrator Base Adapters 20.12.03

On this page