The Web Client Plug-in sends and receives HTTP request and response messages. When requested, it accesses the server by using a proxy and completes server and proxy authentication.
Function
This plug-in sends and receives HTTP request and response messages and consists of the following functions:
- Supports HTTP/HTTPS 1.1.
- Generates an HTTP request message based on the input properties and receives HTTP response messages as output properties.
The following table shows the relationships between HTTP request messages and their corresponding input properties.
| Element | Input Property | |
|---|---|---|
| Request line | Method | requestMethod |
| URI | requestUrl | |
| HTTP/version | - | |
| Header | requestHeaders | |
| Body | requestBody | |
The following table shows the relationships between HTTP response messages and their corresponding output properties.
| Element | Output Property | |
|---|---|---|
| Status line | HTTP/version | - |
| Status code | responseStatusCode | |
| Status message | responseStatusMessage | |
| Header | responseHeaders | |
| Body | responseBody | |
Prerequisites
- To use HTTPS communication, import the destination server certificate or a root certificate that authenticates the server certificate in JRE truststore on the client (Ops Center Automator installation server).
Return codes
The Web Client Plug-in generates the following return codes:
| Return Code | Description |
|---|---|
| 0 | Ended normally. |
| 1 | A status code other than Success is returned for an HTTP response message. |
| 70 | Failed to connect to the remote host. |
| 77 | Failed to resolve the host name for the remote host. |
| 80 | Task execution has stopped. |
| 86 | An incorrect property value has been specified. |
| 90 | A data transmission failure occurred after the connection was established. |
| 91 | The size of the HTTP response message exceeds the upper limit value of the system. |
| 127 | Another unspecified type of error has occurred. |
Property list
The properties available for the Web Client Plug-in. See details in Table 1
| Property key | Property name | Description | I/O type |
|---|---|---|---|
| webServiceConnectionCategory | Web Service Connection Category | When referring to the information of Web Service Connection and using it as an input value of Web Client Plug-in, specify the category of Web Service Connection. | Input |
| webServiceConnectionName | Web Service Connection Name | When referring to the information of Web Service Connection and using it as an input value of Web Client Plug-in, specify the name of Web Service Connection. | Input |
| requestMethod R | Method | Specify the HTTP method as follows:
The default value is GET. |
Input |
| requestUrl R | Request URL | Specify the resource URL to which the HTTP request is sent, and a query parameter. The URL-encoded value specified as the input property value is used as is. See Table 1 for more details. | Input |
| requestHeaders | Request Headers | Specify the HTTP request header in raw format. Use the Content-Type header and the charset parameter to specify the request body format and character set. | Input |
| requestBody | Request Body | Specify the HTTP request body in the raw format. Use the format specified in the Content-Type header. | Input |
| webAuth R | Server Authentication Scheme | Specify the server authentication type:
|
Input |
| webUsername | Server Authentication Username | Specify the user name used for server authentication, using a maximum of 256 characters. Not valid when the webAuth property key is set to none. See Table 1 for more details. | Input |
| webPassword | Server Authentication Password | Specify the password used for server authentication, using a maximum of 256 characters. Not valid when the webAuth property key is set to none. See Table 1 for more details. | Input |
| useProxy R | Use Proxy Server | Set this to true when a proxy connection is required. See Table 1 for more details. The default value is false. |
Input |
| proxyHostname | Proxy Hostname | Specify the proxy host name or IP address, using a maximum of 256 characters. Not valid when the useProxy property key is set to false. See Table 1 for more details. | Input |
| proxyPort | Proxy Port Number | Specify the proxy port number, using 1-65535. Not valid when the useProxy property key is set to false. See Table 1 for more details. The default value is 8080. |
Input |
| proxyAuth R | Proxy Server Authentication Scheme | Specifies the proxy authentication type. The following authentication functions are supported:
Specify "none" for the authentication header in requestHeaders. See Table 1 for more details.The default value is none. |
Input |
| proxyUsername | Proxy Username | Specify the user name used for proxy authentication, using a maximum of 256 characters. Not valid when the useProxy property key is set to false or the proxyAuth property key is set to none. See Table 1 for more details. | Input |
| proxyPassword | Proxy Password | Specify the password used for proxy authentication, using a maximum of 256 characters. Not valid when the useProxy property key is set to false or the proxyAuth property key is set to none. See Table 1 for more details. | Input |
| responseStatusCode | Status Code | Outputs the status code of the HTTP response message. When "3xx Redirect" is returned, automatic tracking is activated. | Output |
| responseStatusMessage | Status Message | Outputs the status message of the HTTP response message. | Output |
| responseHeaders | Response Headers | Outputs the header information of the HTTP response message. | Output |
| responseBody | Response Body | Outputs the body information of the HTTP response message. Make sure that the size of responseBody does not exceed 30 MB. If the size of responseBody exceeds 30 MB, the value is truncated. | Output |
| R: Required | |||
The setting value of Web Service Connection can be referred to as a value of the input property of the Web Client Plug-in. In this case, the corresponding input property is overwritten by the setting value of the Web Service Connection.
Whether to refer to the setting value of Web Service Connection is determined by the input value of webServiceConnectionCategory and webServiceConnectionName.
| Input Value of webServiceConnectionCategory | Input Value of webServiceConnectionName | Behavior of Web Client Plug-in |
|---|---|---|
| Exist | Exist | See the value of Web Service Connection. If no matching Web Service Connection is found, it becomes a run-time error. |
| Exist | Not exist | Error (tried to refer to Web Service Connection, but did not find the matching one). |
| Not exist | Exist | Error (tried to refer to Web Service Connection, but did not find the matching one). |
| Not exist | Not exist | Do not refer to the value of Web Service Connection. |
When referring to the setting value of WebServiceConnection, the URL (property name: requestUrl) is assembled dynamically at the run time. As the input value of the property, you must specify the part after "/" after the host name. The part before "/" is assembled from the setting value of Web Service Connection. In the case of the string, where the value specified in requestUrl does not begin with "/", it generates a run-time error.
| Item of the Web Service Connection | Input Property of Web Client Plug-in | Remark |
|---|---|---|
| IP Address/Host Name | Part of requestUrl | host part of "http://host:port/Folder/" |
| Protocol | Part of requestUrl | http part of "http://host:port/Folder/" |
| Port | Part of requestUrl | port part of "http://host:port/Folder/" |
| User ID | webUsername | Output the message to the task logs that overwriting the input value if it was set. |
| Password | webPassword | Output the message to the task log that overwriting the input value if it was set. |
| Use Proxy Server | useProxy | - |
| IP Address/Host Name in Use Proxy Server | proxyHostname | Output the message to the task log that overwriting the input value if it was set. |
| Port in Use Proxy Server | proxyPort | Output the message to the task log that overwriting the input value if it was set. |
| Authentication Type in Use Proxy Server | proxyAuth | - |
| User ID in Use Proxy Server | proxyUsername | Output the message to the task log that overwriting the input value if it was set. |
| Password in Use Proxy Server | proxyPassword | Output the message to the task log that overwriting the input value if it was set. |
Supported Headers
Headers are transmitted and received in their raw format. The following default headers are supported:
| Header | Value |
|---|---|
| Accept | application/json |
| Accept-Language | en |
| Content-Type (Only when POST or PUT is specified as the method.) | application/json |
| Cache-Control | no-cache |
| Pragma | no-cache |
| User-Agent | client-software-name, version |
| Host | destination-host-name, port-number |
| Connection | keep-alive |
The following headers have a special behavior:
| Header | Behavior |
|---|---|
| Charset parameter in the Content-Type header | Request: The body character set is converted by using the value specified in the Charset parameter of the Content-Type header. When no value is specified, it is converted to UTF-8. |
| Response: The body character set is interpreted according to the value specified in the Charset parameter of the Content-Type header. When a charset parameter is not returned, it is interpreted as UTF-8. | |
| Content-Encoding | When the Content-Encoding header is returned, the body is extended. The following encoding formats are supported:
|
Connection timeout value settings
When dealing with any HTTP/HTTPS communication problems that might occur when connecting to the destination, you should configure the connection timeout key value (plugin.http.connect.timeout) so it is obvious when a problem occurs with the connection. The connection timeout value is specified through the key name (config_user.properties) in the properties file under automation-software-installation-folder\conf.
Linkage with the JavaScript Plug-in
Because the Web Client Plug-in does not rewrite input and output property values, linkage with the JavaScript Plug-in is effective when values must be rewritten. Following is an example of linkage with the JavaScript Plug-in to extract the URL encoding and the SSO authentication token from the server response.
The following table shows the flow linkage with the JavaScript Plug-in.
| Plug-in | Flow | Description |
|---|---|---|
| JavaScript Plug-in 1 | Input | URL entered by the user.
Script that runs URL encoding. |
| Execute | Runs URL encoding. | |
| Output | URL-encoded URL. | |
| Web Client Plug-in 1 | Input | URL-encoded URL.
Other information entered by the user (such as the header). |
| Execute | Generates and sends the HTTP request. Receives and analyzes the HTTP response. |
|
| Output | Outputs the HTTP response elements (such as the header). | |
| JavaScript Plug-in 2 | Input | URL-encoded URL.
Reconfigured header. Other information entered by the user. |
| Execute | Generates and sends the HTTP request. Receives and analyzes the HTTP response. |
|
| Output | Outputs the HTTP response elements. |
Prerequisites for using Negotiate authentication
Negotiate authentication uses Kerberos v5 authentication, which needs the following configuration files:
| File Name | Description | Edited by user |
|---|---|---|
|
Kerberos configuration file (krb5.conf) |
Kerberos configuration in the user environment. | Required |
|
Login configuration file (login.conf) |
Specifies the authentication technology to be used. | Not required |
The following code shows that the Kerberos configuration file is in automation-software-installation-folder\conf\plugin. Edit the code, especially the italicized characters, as needed for the user environment.
[libdefaults] // Default value for Kerberos authentication
default_realm = EXAMPLE.COM // Default realm for Kerberos authentication
udp_preference_limit = 1
[realms] // KDC setting for each Kerberos realm (you can define settings for multiple realms)
EXAMPLE.COM = {
kdc = kdc.example.com // KDC host name
}
[domain_realm] // Maps the Active Directory domain to the Kerberos realm
.example.com = EXAMPLE.COM
example.com = EXAMPLE.COM
Login Configuration File
The following login configuration file is in automation-software-installation-folder\conf\plugin.
com.sun.security.jgss.krb5.initiate {
com.sun.security.auth.module.Krb5LoginModule required useTicketCache=true doNotPrompt=false refreshKrb5Config=true; // Specifies the authentication
technology and options to be used
};
Enter the following in Common-Component-installation-folder\uCPSB11\CC\web\containers\AutomationWebService\usrconf\usrconf.cfg so that the Kerberos configuration file and the login configuration file are referenced.
add.jvm.arg=-Djava.security.krb5.conf=Automation/conf/plugin/krb5.conf add.jvm.arg=-Djava.security.auth.login.config=Automation/conf/plugin/login.conf add.jvm.arg=-Djavax.security.auth.useSubjectCredsOnly=false