• Spaces
  • Collections
  • Help
    • ×
     
     
    •  
    (archive) BMC Atrium Orchestrator Base Adapters 20.12.04

    Page tree

    The HTTP adapter can retrieve data from a specified URL by using a Get action. You must enter the Get action in the Action field of the Properties tab for the Call Adapter activity. When you use a context item as an input for an adapter request, you must enclose the adapter request in the <request-data> elements. However, when you create a static request, <request-data> is not required and the adapter request starts with the <adapterName-adapter-request> element.

    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 table describes the adapter request elements for the HTTP adapter with a Get action.

    Elements for an HTTP adapter request with a Get action

    Element

    Description

    Required

    <action>

    Specifies the URL for the target page

    Yes

    <use-ssl-certificate>

    Determines 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)

    No

    <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)

    No

    <install-certificate>

    Determines 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)

    No

    <passphrase>

    Specifies the Java Standard Trust Keystore passphrase

    Default value: changeit

    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

    No

    <data-format>

    Indicates the data type for the adapter response

    The JSON string in the response is parsed to XML only if <Content-Type> is set to application/json and <data-format> is set to XML.

    Valid values: XML (default), HTML

    No

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

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

    No

    <user-name>

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

    No

    <password>

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

    No

    <ntlm-authentication>

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

    NTLM authentication is an application protocol used in various Microsoft network protocol implementations and is used throughout Microsoft systems as an integrated single sign-on mechanism.

    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.

    No

    <Content-Type>

    Specifies the type of data format for HTTP content

    The JSON string in the response is parsed to XML only if <Content-Type> is set to application/json and <data-format> is set to XML.

    No

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

    No

    <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">

    No

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

    No

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

    Valid values: true, false (default)

    Notes:

    • If you specify <enable-json-conversion> in the adapter configuration and the adapter request, the value in the adapter request overrides the value in the configuration.
    • The response maintains the order in which the fields are specified in the request.

    No

    <enable-redirects>

    Specifies whether the adapter should redirect a URL request to the changed URL location

    Valid values: true (default), false

    Note: If you specify <enable-redirects> in the adapter configuration and an adapter request, the values in the request override the values in the configuration.

    No

    <download-attachment>

    Specifies whether the adapter should display the content of the attached file in the adapter response or save the content in a file

    Valid values: true, false (default)

    If <download-attachment>=true, the adapter checks the <content-disposition> field in the response header. If <content-disposition> conatins attachment; file-name="abc.doc", the adapter saves the attached file.

    If the adapter response header does not contain the content-disposition field, the adapter checks the <content-type> field in the response header. If <content-type> conatins an image or attachment, the adapter saves the attached file.

    If <download-attachment>=false, the content of the attached file is displayed in the adapter response.

    No

    <download-directory>

    Specifies the full path where the attached file must be downloaded

    Default value: Temporary directory of the Java virtual machine of the peer

    No

    Note

    The HTTP adapter request is the request generated by the HTTP adapter; the HTTP request is the request sent to the HTTP server.

    The HTTP adapter generates a response to the HTTP request (URL) defined in the adapter request.

    The following table describes the elements of the response to an HTTP adapter request with a Get action, when <data-format> is HTML for any <Content-Type> of HTTP server response.

    Elements of an HTTP adapter response to a request with a Get action when <data-format> is HTML for any <Content-Type> of HTTP response

    Element

    Description

    <status>

    Specifies the status of the adapter request

    Valid values: success, error

    <metadata>

    Contains the <status> element

    <status-line>

    Contains the <code> and <reason> elements

    <code>

    Specifies the numeric status code for the response

    The <code> response element returns 10000 for a connection and read timeout or when the web service is down.

    <reason>

    Specifies the reason associated with the status code

    <header-lines>

    Contains the <field-name> element

    <field-name>

    Specifies the field name returned from the adapter request in the HTTP header data

    This element is variable and depends on the field returned. This element is a child of the <header-lines> tag and is shown in the response as follows:
    <header-lines> <!-- header of the http response -->
    <field-name></field-name>
    </header-lines>

    The response can return multiple fields, as shown in the following example:
    <Server>Apache-Coyote/1.1</Server>
    <Content-Type>text/plain;charset=ISO-8859-1</Content-Type>
    <Content-Length>391</Content-Length>
    <Date>Mon, 05 Apr 2010 09:32:22 GMT</Date>

    <message-body>

    Contains the message body of the HTTP response in text format

    Elements of an HTTP adapter response to a request with a Get action when <data-format> is XHTML or XML and <Content-Type> is a well-formed text, HTML, or XML

    Element

    Description

    <status-line>

    Contains the <code> and <reason> elements

    <code>

    Specifies the numeric status code of a response

    <reason>

    Specifies the reason associated with the status code

    <header-lines>

    Contains the <field-name> element

    <field-name>

    Specifies the field name returned from the adapter request

    The element name is variable and depends on the field returned.

    <message-body>

    Contains the message body of the HTTP response in XML format or uncorrected HTML format, not in character data (CDATA) format

    Note

    If the output is not in the specified format, the output is enclosed in the <non-xmldata-response> element.

    		 

    <httpAdapterRequest>
  <action></action>
  <data-format></data-format>
  <character-set></character-set>
  <http-connection-properties>
    <user-name>test</user-name>
    <password>this</password>
    </http-connection-properties>
</httpAdapterRequest>


    <httpAdapterResponse>
  <metadata>
    <status>success</status>
  </metadata>
   <status-line> <!-- status of http response -->
   <code>10000</code>
   <reason></reason>
   </status-line>
   <header-lines> <!-- header of the http response -->
   <[field-name]></[field-name]>
   ...
   </header-lines>
    <message-body> <!-- message body of the http response in HTML/XHTML/XML...>
   </message-body>
</httpAdapterResponse>

    Note

    <script> and <style> elements are deleted from the HTTP server response for XHTML data format.

    <httpAdapterResponse>
  <metadata>
    <status>success</status>
  </metadata>
  <status-line>
    <code>200</code>
    <reason>OK</reason>
  </status-line>
  <header-lines>
    <[field-name]></[field-name]>
  </header-lines>
  <message-body>
<!-- message body of the http response in well formed XML/HTML -->
  </message-body>
</httpAdapterResponse>

    Note

    If the output is not in the format that you want, it is enclosed in <non-xmldata-response> tags.

    <httpAdapterResponse>
  <metadata>
    <status>success</status>
  </metadata>
  <status-line>
    <code>200</code>
    <reason>OK</reason>
  </status-line>
  <header-lines>
    <[field-name]></[field-name]>
...
</header-lines>
  <message-body>
    <non-xml-data-response>
<!-- message body of the http response in not well formed XML/HTML -->
</non-xml-data-response>
  </message-body>
</httpAdapterResponse>


    <httpAdapterRequest>
  <action>http://someHost/_vti_bin/UserGroup.asmx</action>
  <use-ssl-certificate></use-ssl-certificate>
  <install-certificate></install-certificate>
  <allow-unsigned-certificate></allow-unsigned-certificate>
  <passphrase></passphrase>
  <data-format>XHTML</data-format>
  <character-set>shift_jis</character-set>
  <http-connection-properties>
    <user-name>USERDOMAIN\user123</user-name>
    <password>password</password>
    <ntlm-authentication>true</ntlm-authentication>
    <Content-Type>text/html</Content-Type>
  </http-connection-properties>
</httpAdapterRequest>


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


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


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

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


    <http-adapter-request>
    <action>http://www.gmail.com</action>
   <use-ssl-certificate>false</use-ssl-certificate>
   <allow-unsigned-certificate>false</allow-unsigned-certificate>
   <data-format>html</data-format>
</http-adapter-request>



    <http-adapter-request>
    <http-connection-properties />
    <action>http://mail.google.com/mail/</action>
    <use-ssl-certificate>false</use-ssl-certificate>
    <install-certificate>false</install-certificate>
    <allow-unsigned-certificate>false</allow-unsigned-certificate>
    <passphrase>changeit</passphrase>
    <data-format>html</data-format>
    <enable-redirects>false</enable-redirects>
  </http-adapter-request>


    <httpAdapterResponse>
  <metadata>
    <status>success</status>
  </metadata>
  <status-line>
    <code>302</code>
    <reason>Moved Temporarily</reason>
  </status-line>
  <header-lines>
    <Content-Type>text/html; charset=UTF-8</Content-Type>
    <Cache-Control>no-cache, no-store, max-age=0, must-revalidate</Cache-Control>
    <Pragma>no-cache</Pragma>
    <Expires>Fri, 01 Jan 1990 00:00:00 GMT</Expires>
    <Date>Mon, 25 Jul 2011 10:59:22 GMT</Date>
    <Location>https://www.google.com/accounts/ServiceLogin?service=mail&passive=true&rm=false&continue=http%3A%2F%2Fmail.google.com%2Fmail%2F%3Fui%3Dhtml%26zy%3Dl&bsv=llya694le36z&scc=1&ltmpl=default&ltmplcache=2&from=login</Location>
    <X-Content-Type-Options>nosniff</X-Content-Type-Options>
    <X-Frame-Options>SAMEORIGIN</X-Frame-Options>
    <X-XSS-Protection>1; mode=block</X-XSS-Protection>
    <Server>GSE</Server>
    <Content-Length>423</Content-Length>
    <Connection>Keep-Alive</Connection>
  </header-lines>
  <message-body><HTML><HEAD><TITLE>Moved Temporarily</TITLE></HEAD><BODY BGCOLOR="#FFFFFF" TEXT="#000000"><H1>Moved Temporarily</H1>The document has moved <A HREF="https://www.google.com/accounts/ServiceLogin?service=mail&amp;passive=true&amp;rm=false&amp;continue=http%3A%2F%2Fmail.google.com%2Fmail%2F%3Fui%3Dhtml%26zy%3Dl&amp;bsv=llya694le36z&amp;scc=1&amp;ltmpl=default&amp;ltmplcache=2&amp;from=login">here</A>.</BODY></HTML></message-body>
</httpAdapterResponse>


    <httpAdapterRequest>
    <download-attachment>true</download-attachment>
    <download-directory>c:\test</download-directory>
    <action>http://www.samplesite.com/sample.pdf</action>
</httpAdapterRequest>


    <httpAdapterResponse>
  <metadata>
    <status>success</status>
  </metadata>
  <status-line>
    <code>200</code>
    <reason>OK</reason>
  </status-line>
  <header-lines>
    <Content-Type>text/html; charset=UTF-8</Content-Type>
    <Set-Cookie>GAPS=1:sVXtSO34KWlupqAGylx_5b-LBzMeGA:8yrRmbqgnSV0wRXV;Path=/accounts;Expires=Wed, 24-Jul-2013 10:52:44 GMT;Secure;HttpOnly</Set-Cookie>
    <Set-Cookie>GALX=446w2a9s9bI;Path=/accounts;Secure</Set-Cookie>
    <Cache-control>no-cache, no-store</Cache-control>
    <Pragma>no-cache</Pragma>
    <Expires>Mon, 01-Jan-1990 00:00:00 GMT</Expires>
    <X-Frame-Options>Deny</X-Frame-Options>
    <X-Auto-Login>realm=com.google&args=service%3Dmail%26continue%3Dhttp%253A%252F%252Fmail.google.com%252Fmail%252F%253Fui%253Dhtml%2526zy%253Dl</X-Auto-Login>
    <Date>Mon, 25 Jul 2011 10:52:44 GMT</Date>
    <X-Content-Type-Options>nosniff</X-Content-Type-Options>
    <X-XSS-Protection>1; mode=block</X-XSS-Protection>
    <Content-Length>18700</Content-Length>
    <Server>GSE</Server>
  </header-lines>
  <message-body><html lang="en" dir="ltr"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="description" content="7+ GB of storage, less spam, and mobile access. Gmail is email that's intuitive, efficient, and useful. .... </html></message-body>
</httpAdapterResponse>


    <httpAdapterResponse>
  <metadata>
    <status>success</status>
  </metadata>
  <status-line>
    <code>200</code>
    <reason>OK</reason>
  </status-line>
  <header-lines>
    <Date>Thu, 01 Sep 2011 11:29:35 GMT</Date>
    <Server>Apache</Server>
    <Last-Modified>Sat, 09 Oct 2010 14:30:17 GMT</Last-Modified>
    <ETag>"a010afff-35702-4cb07c79"</ETag>
    <Accept-Ranges>bytes</Accept-Ranges>
    <Content-Type>application/pdf</Content-Type>
    <Content-Length>218882</Content-Length>
    <Connection>Keep-Alive</Connection>
    <Age>89423</Age>
  </header-lines>
  <download-directory>c:\test\</download-directory>
  <name>sample.pdf</name>
</httpAdapterResponse>


    <httpadapterRequest>
<action>[http://10.128.249.76:8080/DemoJSONNew/JSONServlet2]</action>
</httpadapterRequest>


    <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>109</Content-Length>
<Date>Tue, 31 Jul 2012 10:04:56 GMT</Date>
</header-lines>
<message-body>["GET-MEHODE","SERVLET 2","MCA","Amit Kumar","19-12-1986",24,"Scored","demo To chk Order","Demo chk 2",66.67|"GET-MEHODE","SERVLET 2","MCA","Amit Kumar","19-12-1986",24,"Scored","demo To chk Order","Demo chk 2",66.67]</message-body>
</httpAdapterResponse>

    <httpadapterRequest>
<enable-json-conversion>false</enable-json-conversion>
<action>[http://10.128.249.76:8080/DemoJSONNew/JSONServlet2]</action>
<data-format>xml</data-format>
</httpadapterRequest>


    <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>109</Content-Length>
<Date>Tue, 31 Jul 2012 10:06:59 GMT</Date>
</header-lines>
<message-body>
<e>GET-MEHODE</e>
<e>SERVLET 2</e>
<e>MCA</e>
<e>Amit Kumar</e>
<e>19-12-1986</e>
<e>24</e>
<e>Scored</e>
<e>demo To chk Order</e>
<e>Demo chk 2</e>
<e>66.67</e>
</message-body>
</httpAdapterResponse>

    © Copyright 2005-2024 BMC Software, Inc. Use of this site signifies your acceptance of BMC’s Terms of Use . BMC, the BMC logo, and other BMC marks are assets of BMC Software, Inc. These trademarks are registered and may be registered in the U.S. and in other countries.