Hitachi

JP1 Version 12 JP1/Automatic Operation Service Template Reference


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.

Table 4‒9: 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.

Table 4‒10: Correspondence between HTTP response message elements and output properties

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

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

  • POST

  • PUT

  • DELETE

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:

  • none

    Specify this to not use server authentication.

  • basic

    Specify this to use basic authentication.

  • digest

    Specify this to use digest authentication.

  • negotiate

    Specify this to use negotiate authentication. Note that negotiate authentication can be used only if the OS of the JP1/AO server is Windows.

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:

  • When values are specified for the webServiceConnectionCategory and webServiceConnectionName properties

  • When none is specified for the webAuth property

--

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:

  • When values are specified for the webServiceConnectionCategory and webServiceConnectionName properties

  • When none is specified for the webAuth property

--

Input

O

useProxy

Use Proxy Server

Specify either of the following values to determine whether to use proxy connection when sending a request:

  • true

    Specify this to use proxy connection when sending a request.

  • false

    Specify this to not 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:

  • When values are specified for the webServiceConnectionCategory and webServiceConnectionName properties

  • When false is specified for the useProxy property

--

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:

  • When values are specified for the webServiceConnectionCategory and webServiceConnectionName properties

  • When false is specified for the useProxy property

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:

  • When values are specified for the webServiceConnectionCategory and webServiceConnectionName properties

  • When false is specified for the useProxy property

Specify one of the following values:

  • none

    Specify this to not use proxy authentication.

  • basic

    Specify this to use basic authentication.

  • digest

    Specify this to use digest authentication.

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:

  • When values are specified for the webServiceConnectionCategory and webServiceConnectionName properties

  • When false is specified for the useProxy property

  • When none is specified for the proxyAuth property

--

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:

  • When values are specified for the webServiceConnectionCategory and webServiceConnectionName properties

  • When false is specified for the useProxy property

  • When none is specified for the proxyAuth property

--

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.

Table 4‒11: Headers for which default values can be 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.

Table 4‒12: Headers causing special behavior

Header

Behavior

Content-Type (charset parameter)

When the request is sent

The character set of the body is converted based on the value specified for the charset parameter. If no value is specified, the body is encoded in UTF-8.

When the response is received

The character set of the body is interpreted based on the returned charset parameter. If the charset parameter is not returned, the character set is interpreted as UTF-8.

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:

The following shows the procedure for using Kerberos v5 authentication:

  1. Edit and save the Kerberos configuration file.

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

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

Table 4‒13: 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.

Figure 4‒13: Example of linking the Web client plug-in with the JavaScript plug-in

[Figure]

Related topics