REST adapter module

The REST adapter module contains the following process.

 GET process

The Get process retrieves the data from a specified URL.

Input elements for the Get process for the REST adapter

Input element

Type

Description

Required

<adapter name>

String

Specifies the name of the adapter

Default name of the adapter is RESTAdapter

No

<url>

String

Specifies the URL for the target page from where you want to obtain information

Yes

<headers>

String

Specifies the header details for the adapter request in a JSON format

Sample header JSON
{
"headers" :
        {
       "authorization" :
            {
        "type" : "basic",
"user-name" : "myUser",
"password" : "myPassword"
}
          }
}

For more information, see Specifying header fields for the REST adapter.

No

<return-data-format>

String

Indicates the data type for the adapter response 

By default, the REST adapter returns data in a JSON format.

No

<use-ssl-certificate>

String

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>

String

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

Valid values: true, false (default)

No

<install-certificate>

String

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 TrueSight Orchestration's local peer's cacerts file (a rare practice). 

Valid values: true, false (default)

No

<passphrase>

String

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

<character-set>

String

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

<user-name>

String

Specifies the user name required for basic or NTLM authentication specified in <header>  

No

<password>

String

Specifies the password corresponding to the user name specified in <header>

No

<ntlm-authentication>

String

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>

String

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

<signature-properties>

String

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

<private-key-file>

String

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>

String

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>

String

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>

String

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

<keystore-file>

String

Specifies the path to the JKS that contains the client certificate

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

<key-password>

String

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>

String

Specifies the password to the JKS

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

<client alias>

String

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

<enable-redirects>

String

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>

String

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

String

Specifies the full path where the attached file must be downloaded 

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

No

<request-timeout>

String

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

Updated in 8.1Default value: 60 seconds

No

<ignore-line-break-in-response>

String

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


 Output elements for the Get process for the REST adapter

Output element

Description

adapter response

Contains the adapter response for the Get process

 

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