2.4.12 Linking with a business system on the web (example of defining a jobnet that uses HTTP connection jobs)

To define a jobnet that links a JP1/AJS3-based business system with a business system on the web, use HTTP connection jobs.

HTTP connection jobs can be used to send requests and receive responses via the HTTP protocol. HTTP connection jobs also allow JP1/AJS3 to call a web API (such as the REST API) that is provided in a cloud environment or on a web server.

Organization of this subsection

(1) Example of defining a jobnet that uses an HTTP connection job
(2) Definition of an HTTP connection job
(3) HTTP headers set by HTTP connection jobs
(4) Security measures for HTTP connection jobs
(5) Information output by HTTP connection jobs
(6) Cautionary notes

(1) Example of defining a jobnet that uses an HTTP connection job

The following figure shows an example of using an HTTP connection job to define a jobnet that obtains business data through a web API provided on the web, and creates a report.

Figure 2‒109: Example of defining a jobnet that uses HTTP connection jobs

To Page Top

(2) Definition of an HTTP connection job

This subsection describes the definition items specific to HTTP connection jobs.

To send HTTP requests by using HTTP connection jobs, define the files that specify the request type and request information. If extended mode is used when the versions of JP1/AJS3 - Manager and JP1/AJS3 - Agent are 12-50 or later, you can send both the URL parameter and message body simultaneously when sending an HTTP request.

The following table describes the definition items that are used to send HTTP requests.

Table 2‒32: Definition items used to send HTTP requests
No.	Definition item	Description
1	Request type	Specify the type of request to be sent to the web API. You can specify one of the following request types: `GET` `POST` (add) `PUT` (update) `DELETE`
2	Connection configuration file name	Specify the name of the connection configuration file that contains the HTTP connection information for calling a web API.
3	Transmission information file name^#1	Specify the name of the transmission information file that contains the HTTP request information for calling a web API.
4	Transmission information file name (URL parameter)^#2	Specify the name of the transmission information file that contains the URL parameter of the HTTP request information for calling the Web API.
5	Transmission information file name (Message body)^#2	Specify the name of the transmission information file that contains the message body of the HTTP request information for calling the Web API.

#1: This is a file to be specified if the versions of JP1/AJS3 - Manager and JP1/AJS3 - Agent are 12-10 or earlier or if extended mode is not used.
#2: This is a file to be specified if the versions of JP1/AJS3 - Manager and JP1/AJS3 - Agent are 12-50 or later when extended mode is used.

To receive HTTP responses by using HTTP connection jobs, define the name of the file to which received data will be written, and how that received data will be stored.

The following table describes the definition items that are used to receive HTTP responses.

Table 2‒33: Definition items used to receive HTTP responses
No.	Definition item	Description
1	Status file name	Specify the name of the status file to which the HTTP status code of receive data obtained from the web API will be written.
2	How to store received data	Specify whether the header and body of the receive data obtained from the web API are to be output to the same file or different files. If you choose to output the header and body to the same file, both the header and body of receive data are stored in the received header file.
3	Received header file name	Specify the name of the received header file to which the header of the receive data obtained from the web API will be written.
4	Received body file name	Specify the name of the received body file to which the body of the receive data obtained from the web API will be written.

When you receive data in chunk format by using an HTTP response, you can store decoded data to a file. To decode data in chunk format, specify y for the TRANSFER_DECODING environment setting parameter. For details about the TRANSFER_DECODING environment setting parameter, see 20.14.2(1) TRANSFER_DECODING in the JP1/Automatic Job Management System 3 Configuration Guide.

For details about the files that are used for HTTP connection jobs, see C. Files Used for HTTP Connection Jobs.

Also, you can specify job return code 0 to 9 for each received HTTP status code value. If you do not specify a return code, the default return code is applied. You can specify multiple HTTP status codes for one job return code. However, you cannot specify one HTTP status code for multiple job return codes. For details about the return code of a job, see 7.10.3 Checking the return code of a job.

To Page Top

(3) HTTP headers set by HTTP connection jobs

All HTTP connection jobs automatically set HTTP headers according to the request type. The following table describes the HTTP headers that can be set automatically.

Table 2‒34: HTTP headers set by HTTP connection jobs
No.	Request type	HTTP header	Description
1	GET	User-Agent	Fixed to `JP1/AJS3` `11-00` `HTTP` `Connection` `Job`
2		Host	The host name and port number of the connection destination are set according to the information specified in the connection configuration file.
3		Accept	Fixed to `/`
4	POST PUT DELETE	User-Agent	Fixed to `JP1/AJS3` `11-00` `HTTP` `Connection` `Job`
5		Host	The host name and port number of the connection destination are set according to the information specified in the connection configuration file.
6		Accept	Fixed to `/`
7		Content-Length	The data size of the HTTP body is calculated and set. If the transmission information file is not specified or is empty, this header is not set.
8		Expect	`100-continue` is set if both of the following conditions exist: The HTTP version specified in the connection configuration file is `1.1`. A transmission information file is specified and request information is written in the file.

In addition to the HTTP headers that are automatically set by HTTP connection jobs, you can set additional headers by specifying Header=additional-header entries in the connection configuration file. For details, see C.1 Connection configuration file.

To Page Top

(4) Security measures for HTTP connection jobs

This subsection describes HTTPS communication and server authentication used for HTTP connection jobs.

(a) HTTPS communication

HTTP connection jobs support HTTPS communication. The following table describes the details of the HTTPS support of HTTP connection jobs.

Table 2‒35: HTTPS support of HTTP connection jobs
No.	Definition	Description
1	Communication protocol	TLS v1.0, TLS v1.1, and TLS v1.2 are supported.
2	Server authentication	Supported.
3	Client authentication	Not supported.
4	Host name verification	Supported. Whether the following names match is checked: Host name specified for the URL entry in the connection configuration file, and the CN (Common Name) or SAN (subject Alt Name) included in the server certificate returned by the server.
5	Checking the certificate revocation list	Supported. Note that to enable this checking, the file name of the certificate revocation list must be specified in the connection configuration file.

For details about the connection configuration file, see C.1 Connection configuration file.

(b) Server authentication

Basic Authentication can be used as a server authentication method.

Other authentication methods can also be used by setting additional headers in the connection configuration file.

For details about the connection configuration file, see C.1 Connection configuration file.

To Page Top

(5) Information output by HTTP connection jobs

When an HTTP connection job terminates, it outputs the following information to the standard output file:

Http-Status-Code=HTTP-status-value^#1
Http-Status-File=Status file name
Http-Response-Header=Received header file name
Http-Response-Body=Received body file name^#2

#1

The type of information output here differs depending on the HTTP status code. If the HTTP status code is 1 or a larger value, the HTTP status is output here. If the HTTP status code is 0 or a smaller value, the maintenance information set by JP1/AJS3 is output.

#2

If you specify that the header and body of the receive data are to be output to the same file as HTTP connection jobs' definition item How to store received data, only the entry name Http-Response-Body= is output. The value (received-body-file-name) is not output.

Supplementary notes

Any information items that have been output to the standard output file can be passed to a succeeding job by using a passing information setting job.
Each HTTP connection job always outputs information to the standard output file in four-line format regardless of the return code. If an HTTP connection job terminates abnormally, the values of entries (values on the right side of the equal sign (=)) might not be output.

To Page Top

(6) Cautionary notes

Only Windows or Linux can be used as the OSs of the manager and agent hosts that can be specified as execution hosts in HTTP connection jobs.
If an HTTP connection job is abnormally terminated (due to a timeout), or forcibly terminated, the job itself terminates but the processes executed via a web API are not terminated. If you also cancel execution of processes that are executed via a web API, do so according to the specifications of that API.
If you include security information (such as a password) in the following files, which are used for HTTP connection jobs, you do so on your own responsibility:
- Connection configuration file
- Transfer information file
- Received header file
- Received body file

To Page Top