HTTP adapter request and response for the PATCH action

The PATCH action for the HTTP adapter sends updates to the specified URL.

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

Elements of an HTTP adapter request with a Patch action

Element

Description

Required

<adapter-name>

Specifies the name of the adapter.

Default value: HTTPAdapter

No

<URL>

Specifies the URL for the target page

Yes

<use-ssl-certificate>

Determines whether to establish a secure connection.

Specify true when <action> uses HTTPS. Specify false or leave it blank when <action> uses HTTP.

Valid values: true, false (default)

No

<install-certificate>

Determines whether to install certificates.

If true, the security certificates are installed automatically (a common practice). If false, the user must manually export the security certificate from the specified target server and manually import it to the cacerts file on a local peer.

Valid values: true, false (default)

No

<allow-unsigned-certificate>

Specifies whether to allow unsigned certificates from trusted zones.

If you are using self-signed SSL certificates (a common practice), specify true.

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

<file-path>

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

No

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

<data>

Contains the data to be posted

JSON sample for specifying the <body> element

{
   --- formatted json for patch ---
}

Sample format for specifying <body> for a multi-part data request

[
{
"op": "replace",
"path": "/name",
"value": "David"
}
]

No

<user-name>

Specifies the user name required for basic authentication

No

<password>

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

No

<character-set>

Specifies the supporting CharSet, which 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

<connection-properties>

Specifies an XML document that includes HTTP connection properties, which contains the <user-name> and <password> elements for a 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

<include-expect-header>

Specifies whether to include the expect header in the adapter request

Valid values: true (default), false

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

<signature-mode>

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

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

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

<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

<request-timeout>

Specifies the time (in seconds) to wait when establishing a connection 

Default value: 10 seconds.

No

<krb-login-conf-path>

Specifies the path to the login.conf file

For example, /etc/java.login.conf

No

<krb-conf-path>

Specifies the path to the krb configuration file

For example, /etc/krb5.confa

No

<krb-use-subject-creds>

Specifies whether to use user credentials while obtaining a ticket.

Valid values: true, false (retrieves the ticket from the kinit cache).

No

<ignore-line-break-in-response>

Specifies whether to ignore the line breaks while generating the adapter response.

If true, the line break markups are ignored and the response is returned as a single line. If false, the line break markers (if specified in the adapter response) are retained.

Valid values: true (default), false

No

The following figure shows a sample adapter request.

<request-data>
       <httpAdapterRequest>
           <action>http://Endpoint-URL</action>
           <http-connection-properties>
               <content-type>application/json</content-type>
       <Authorization>New Authentication token</Authorization>
           </http-connection-properties>
           <data>[
    {
        "op": "replace",
        "path": "/address",
        "value": "2.2.2.2"
    },
    {
        "op": "replace",
        "path": "/name",
        "value": "David"
    }
]</data>             
       </httpAdapterRequest>
   </request-data>

The following figure shows a sample adapter response. 

<httpAdapterResponse>
 <metadata>
   <status>success</status>
 </metadata>
 <status-line>
   <code>200</code>
   <reason>OK</reason>
 </status-line>
<header-lines>
   <Cache-Control>no-cache, no-store, must-revalidate</Cache-Control>
   <Pragma>no-cache</Pragma>
   <Content-Type>application/json; charset=utf-8</Content-Type>
   <Expires>-1</Expires>
   <Server>Microsoft-IIS/8.5</Server>
   <Set-Cookie>CAXXXX=; path=/Vault/; HttpOnly</Set-Cookie>
   <Set-Cookie>mobileState=Desktop; path=/Vault/; HttpOnly</Set-Cookie>
   <api-supported-versions>10.8</api-supported-versions>
   <X-UA-Compatible>IE=EmulateIE8</X-UA-Compatible>
   <X-XSS-Protection>1; mode=block</X-XSS-Protection>
   <X-Content-Type-Options>nosniff</X-Content-Type-Options>
   <X-FRAME-Options>SAMEORIGIN</X-FRAME-Options>
   <Access-Control-Expose-Headers>Warning</Access-Control-Expose-Headers>
   <Date>Fri, 21 Aug 2020 07:05:58 GMT</Date>
   <Content-Length>326</Content-Length>
 </header-lines>
<message-body>{
   "id":"37_3",
   "name":"David",
   "address":"2.2.2.2",
   "userName":"userName",
   "platformId":"WinServerLocal",
   "safeName":"TSOsafe",
   "secretType":"password",
   "platformAccountProperties":{
      "LogonDomain":"1.1.1.1"
   },
   "secretManagement":{
      "automaticManagementEnabled":true,
      "lastModifiedTime":1573610221
   },
   "createdTime":1573644221
}</message-body>
</httpAdapterResponse>

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*