4.2.19 Web client plug-in
Function
This plug-in generates an HTTP request message from the input properties of the plug-in, and sends the generated HTTP request message. This plug-in also outputs a received HTTP response message as output properties.
You can reference the values of the Web service connection settings and use those values as input for the properties of this plug-in.
The supported protocol version is HTTP/1.1 or HTTPS/1.1.
Also, the TLS version supported by HTTPS is TLSv1.2.
The following table lists the correspondence between HTTP message elements and plug-in properties.
Message element |
Input property |
|
---|---|---|
Request line |
Method |
requestMethod |
URI |
requestUrl |
|
HTTP/version |
-- |
|
Header |
requestHeaders |
|
Body |
requestBody |
- Legend:
-
--: The corresponding property does not exist because the protocol version is fixed to HTTP/1.1 or HTTPS/1.1.
Note that the Web client plug-in does not convert the values specified for input properties. Therefore, for input properties, specify values in the format that requires no conversion.
Message element |
Output property |
|
---|---|---|
Status line |
HTTP/version |
-- |
Status code |
responseStatusCode |
|
Status message |
responseStatusMessage |
|
Header |
responseHeaders |
|
Body |
responseBody# |
- Legend:
-
--: The corresponding property does not exist because the protocol version is fixed to HTTP/1.1 or HTTPS/1.1.
- #
-
Make sure that the size of the body to be output does not exceed 30 MB. The contents of the body are truncated at 30 MB.
Cautionary notes
-
If execution of a task is stopped during plug-in execution, the status of the task becomes Failed or Completed when the processing of the Web client plug-in has finished. The status of steps and tasks after plug-in execution has finished depends on the return code of the step and the condition for executing subsequent steps. You can set Subsequent-step Execution Condition in the Create Step dialog box or the Edit Step dialog box.
-
When you forcibly terminate a task while the plug-in is running, the processing being executed is immediately forcibly terminated and the task enters Failed status. A return code of 80 appears for the step in the Flow area of the Tasks window. The return code output to the task log depends on the timing in which the task was forcibly terminated.
Version
01.01.00
Tag
HTTP
Return codes
Return code |
Description |
---|---|
0 |
Ended normally. |
1 |
The value returned as the status code of the HTTP response message is not 2xx (success). |
70 |
Connection to the Web server or proxy server failed. |
77 |
The host name of the Web server or proxy server could not be resolved. |
80 |
Task execution has stopped. |
86 |
The specified property value is incorrect, or the values specified for the Web service connection could not be found. |
90 |
Data transfer after connection failed. |
91 |
The size of the body of the HTTP response message exceeds 30 MB. |
127 |
An error other than the above occurred. |
Property list
The following table describes the properties.
Property key |
Property name |
Description |
Default value |
I/O type |
Required |
---|---|---|---|---|---|
webServiceConnectionCategory |
Category of the Web service connection |
Specify this property if the values of the Web service connection settings are to be referenced and used as input for the Web client plug-in. Specify the category of the Web service connection. If you specify this property, you must also specify the webServiceConnectionName property. |
-- |
Input |
O |
webServiceConnectionName |
Name of the Web service connection |
Specify this property if the values of the Web service connection settings are to be referenced and used as input for the Web client plug-in. Specify the name of the Web service connection. If you specify this property, you must also specify the webServiceConnectionCategory property. |
-- |
Input |
O |
requestMethod |
Method |
Specify one of the following values as the HTTP method:
|
GET |
Input |
R |
requestUrl |
Request URL |
Specify the URL of the resource that sends an HTTP request, including query parameters. Note that you must specify a URL-encoded value. If status code 3xx (regarding redirection) is returned and the redirection destination URL is already known, we recommend that you specify the redirection destination URL. If you specify values for the webServiceConnectionCategory and webServiceConnectionName properties, when specifying the URL, omit the part up to and including the host name. In other words, specify the slash "/" after the host name, and anything after the slash. |
-- |
Input |
R |
requestHeaders |
Request Headers |
Specify HTTP request headers. Follow the RFC 7230 standard. We recommend that you use the Content-Type header to specify the format of the request body and use the charset parameter of that header to specify the character set. |
-- |
Input |
O |
requestBody |
Request Body |
Write the HTTP request body in the format specified for the Content-Type header. |
-- |
Input |
O |
webAuth |
Server Authentication Scheme |
Specify one of the following values as the server authentication mode:
Specify none for this property if you specify the authentication header for the requestHeaders property. If the value of the webAuth property is not none and the authentication header is specified for the requestHeaders property, a communication error might occur. |
none |
Input |
R |
webUsername |
Server Authentication Username |
Specify the user name to be used for server authentication, by using no more than 256 characters. You do not need to specify this property in the following cases:
|
-- |
Input |
O |
webPassword |
Server Authentication password |
Specify the password to be used for server authentication, by using no more than 256 characters. You do not need to specify this property in the following cases:
|
-- |
Input |
O |
useProxy |
Use Proxy Server |
Specify either of the following values to determine whether to use proxy connection when sending a request:
You do not need to specify this property when values are specified for the webServiceConnectionCategory and webServiceConnectionName properties. |
false |
Input |
R |
proxyHostname |
Proxy Hostname |
Specify the host name or IP address of the proxy, by using no more than 256 characters. You do not need to specify this property in the following cases:
|
-- |
Input |
O |
proxyPort |
Proxy Port Number |
Specify the port number of the proxy, by using a number from 1 to 65,535. You do not need to specify this property in the following cases:
|
8080 |
Input |
O |
proxyAuth |
Proxy Server Authentication Scheme |
Specify one of the following values as the proxy authentication mode. You do not need to specify this property in the following cases:
Specify one of the following values:
Specify none for this property if you specify the authentication header for the requestHeaders property. If the value of the proxyAuth property is not none and the authentication header is specified for the requestHeaders property, a communication error might occur. |
none |
Input |
R |
proxyUsername |
Proxy Username |
Specify the user name to be used for proxy authentication, by using no more than 256 characters. You do not need to specify this property in the following cases:
|
-- |
Input |
O |
proxyPassword |
Proxy Password |
Specify the password to be used for proxy authentication, by using no more than 256 characters. You do not need to specify this property in the following cases:
|
-- |
Input |
O |
responseStatusCode |
Status Code |
The status code of the HTTP response message is output to this property. If status code 3xx (regarding redirection) is returned, the message is automatically redirected. |
-- |
Output |
-- |
responseStatusMessage |
Status Message |
The status message of the HTTP response message is output to this property. |
-- |
Output |
-- |
responseHeaders |
Response Headers |
The header information of the HTTP response message is output to this property. |
-- |
Output |
-- |
responseBody |
Response Body |
The body information of the HTTP response message is output to this property. |
-- |
Output |
-- |
About sending and receiving headers
For the headers listed in the following table, if you do not specify values when sending a request, the default values are set.
Header |
Default value |
---|---|
Accept |
application/json |
Accept-language |
en |
Content-Type# |
application/json |
Cache-Control |
no-cache |
Pragma |
no-cache |
User-Agent |
name-and-version-of-client-software |
Host |
host-name-and-port-number-of-request-destination |
Connection |
keep-alive |
- #
-
The default value is set only if the POST or PUT method is specified.
For the headers listed in the following table, special behavior occurs while sending or receiving.
Header |
Behavior |
---|---|
Content-Type (charset parameter) |
|
Content-Encoding |
If a file is returned in gzip or deflate format, the file is uncompressed. |
About the connection timeout value
If HTTP or HTTPS communication does not end due to a problem with a connection to the Web server or proxy server, you can set the value for a connection timeout as a trigger to detect a failure. You can set the connection timeout value by using the plugin.http.connect.timeout and plugin.http.read.timeout properties in the user-specified properties file (config_user.properties).
Preparation for negotiate authentication with the Web server
Use Kerberos v5 authentication for negotiate authentication with the Web server. To use Kerberos v5 authentication, you must edit configuration files and specify the settings for referencing the files.
The following shows the configuration files used for authentication and their locations:
-
Kerberos configuration file
JP1/AO-installation-folder\conf\plugin\krb5.conf
-
Login configuration file
JP1/AO-installation-folder\conf\plugin\login.conf
The following shows the procedure for using Kerberos v5 authentication:
-
Edit and save the Kerberos configuration file.
-
To reference the configuration files during authentication, add the following entries to the Common-Component-installation-folder\Base64\uCPSB\CC\web\containers\AutomationWebService\usrconf\usrconf.cfg file, and save the file:
add.jvm.arg=-Djava.security.krb5.conf=JP1/AO-installation-folder/conf/plugin/krb5.conf add.jvm.arg=-Djava.security.auth.login.config=JP1/AO-installation-folder/conf/plugin/login.conf add.jvm.arg=-Djavax.security.auth.useSubjectCredsOnly=false
-
Stop the JP1/AO services.
- For a non-cluster system:
-
Execute the hcmds64srv command with the stop option specified.
- For a cluster system:
-
Use the cluster software to bring the services offline.
-
Restart the JP1/AO services.
- For a non-cluster system:
-
Execute the hcmds64srv command with the start option specified.
- For a cluster system:
-
Use the cluster software to bring the services online.
Referencing the Web service connection
You can reference the values of the Web service connection settings and use those values as input for the properties of the Web client plug-in. To do this, specify the category and name of the Web service connection for the webServiceConnectionCategory and webServiceConnectionName properties. If a value is already specified for the corresponding property of the Web client plug-in, the value will be overwritten by the values of the Web service connection settings.
The following table shows the correspondence between the properties of the Web client plug-in and the Web service connection settings.
Property of the Web client plug-in |
Web service connection setting |
---|---|
requestUrl# |
IP address or host name |
Protocol |
|
Port number |
|
webUsername |
User ID |
webPassword |
Password |
useProxy |
Use proxy server |
proxyHostname |
IP address or host name of the proxy server |
proxyPort |
Port number of the proxy server |
proxyAuth |
Authentication method of the proxy server |
proxyUsername |
User ID of the proxy server |
proxyPassword |
Password of the proxy server |
#: A request URL is generated by combining the values of the Web service connection settings and the value of the requestUrl property. Then, the requestUrl property is overwritten with the generated request URL.
Example of linking the Web client plug-in and the JavaScript plug-in
The Web client plug-in uses the property values as is without conversion. Therefore, if the property values need to be converted, we recommend that you link the Web client plug-in with the JavaScript plug-in. The following shows an example of linking the Web client plug-in with the JavaScript plug-in to encode the URL and extract the authentication token to be used for single sign-on from the server response.
|
Related topics
-
User-specified properties file (config_user.properties) in the JP1/AO Configuration Guide