(a) Setting location

HTTP request is set in the following locations for each HTTP request configuration element:

• Request line
  
  • Request message (header)
  • HTTP-adapter runtime-environment property file
  • HTTP-adapter runtime-environment common property file
• Request header
  
  • Request message (header)
  • HTTP-adapter runtime-environment property file
  • HTTP-adapter runtime-environment common property file
• Request body
  
  • Request message (body)
  • Files in the working folder and common folder

Set the request line and request header by using any location from the above 3 setting locations (You can use single locations and multiple location combinations also). Set the request body by using the request message (body) or the files in the working folder and common folder.

Figure 2-83 Example of setting HTTP request

(b) Request line and request header setting method

Set the request line and request header in 3 locations, namely request message (header), HTTP-adapter runtime-environment property file, and HTTP-adapter runtime-environment common property file. If they are set in multiple locations, HTTP adapter is used as high priority setting and processed.

The following table describes the priority of each setting location:

Table 2-31 Request line and request header setting locations and priorities

HTTP request setting is enabled in parameter units in each property file in the request message (header) and each property file (each element in the request message (header) and individual properties in the property file).

Each setting location contains the following features. Reduction in development efforts and easy operations are planned by matching system requirements and combining suitably.

Table 2-32 Setting locations and features of request line and request header

Setting example

The method of setting HTTP request by using basic usage examples is described here.

• Pattern 1 (issuing HTTP request that is always fixed)
  The simplest setting method to issue HTTP request that is always fixed from HTTP adapter is to set the request according to the runtime-environment property file. In this method, HTTP adapter reads the runtime-environment property file with the same name as its own service when adapter starts and issues HTTP request on the basis of the contents of the runtime-environment property file every time there is a request for request issue.
  

  Figure 2-84 Example of setting HTTP request (issuing HTTP request that is always fixed)

  

• Pattern 2 (sharing some settings between multiple HTTP adapters)
  While sharing some settings between multiple HTTP adapters as common system parameters, setting by truncating common system parameters in the runtime-environment common property file is enabled. The following figure contains authentication information of WWW authentication for service 1 as the common parameter of adapter 1 and adapter 2 and this is defined in the runtime-environment common property file:
  

  Figure 2-85 Example of setting HTTP request (sharing some settings between multiple HTTP adapters)

  

  You can reduce development efforts by such setting methods because common parameters need not be defined in duplicate. Also, setting confirmation and change operations (in this example, setting change operation of HTTP adapter according to update of authentication information in service 1) become easy, since common parameters are uniformly managed in 1 property file.
  
• Pattern 3 (dynamically setting HTTP request contents)
  If HTTP request contents are to be set dynamically while issuing a request (if request contents are to be changed according to processing status of the business process), use the request message (header) and set HTTP request. In the following figure, query information is defined in the request message (header) passed from the business process to adapter 2 and query information of the request line is generated dynamically when HTTP request is issued.
  Settings dynamically change HTTP request contents when the adapter is executed only when the request message (header) is used.
  

  Figure 2-86 Example of setting HTTP request (dynamically setting HTTP request contents)

  

  Reference note

  You can replace values in parameters defined in setting locations having low priority with setting locations having high priority (overwriting). For example, in the above figure, all adapter log output destinations are set as "E:\log" by using the runtime-environment common property file. However, for only adapter 3, the log output destination is changed to "F:\log" by using adapter-specific runtime-environment property file. You can also use such setting methods if only some HTTP adapters require exceptional settings or if operations are to be changed only for temporarily specified HTTP adapters.

Specific setting items and setting methods

For specific setting items and setting methods of request lines and request headers, see "(2) Request line" and "(3) HTTP request header".

For details on the elements you can set in the request message (header), see "3.3.13 Defining HTTP adapters" in "Service Platform Reception and Adapter Definition Guide" .

For details on properties you can set in HTTP-adapter runtime-environment property file and HTTP-adapter runtime-environment common property file, see "HTTP-adapter runtime-environment property file" in "Service Platform Reference Guide" .

For the corresponding relation between request message (header) and HTTP adapter-runtime environment (common) property file, see "2.14.13 Corresponding relation between request message (header) and HTTP-adapter runtime-environment (common) property file".

Notes

• Runtime-environment (common) property file
  If runtime-environment property file and HTTP-adapter runtime-environment common property file are not deployed in the prescribed location when HTTP adapter starts, HTTP adapter operates without using the property file.
  If both runtime-environment property file and runtime-environment common property file are not deployed, HTTP adapter operates assuming that all default values for these property files are specified. Set a request if required in the request message (header) while executing adapter, since a property that does not have default value is in undefined status.
  
• Request message (header)
  If specification of the header allocation variable for the request message is omitted while developing HTTP adapter, HTTP adapter operates without using the request message (header).
  If multiple header allocation variables are specified for the request message while developing HTTP adapter, the header allocation variable containing the name space of HTTP adapter request message (header) is used.
  If multiple header allocation variables containing the name space of HTTP adapter request message (header) are specified while developing HTTP adapter, there is uncertainty as to which header allocation variable is used during execution.
  
• Overall other
  You can streamline system development and operations by using multiple setting locations. However, if settings are hierarchical and complicated due to requirements, it is difficult to understand which setting location parameters are used during execution. Analyze system configuration and operation service in the beginning and then design and develop so as to acquire suitable results.
  

(c) Request body setting method

Specify the request body in pairs of data stored in the request body and data sending types (data storage method). Set each in the following locations:

• Stored data
  Files in request message (body) or working folder and common folder
  
• Data sending type
  Request message (header) and HTTP adapter-runtime environment (common) property file
  

Files in request message (body) or working folder and common folder are transformed to a suitable form according to the data sending type, stored in the request body and then issued as requests. The following figure shows setting image when a request body is issued:

For specific setting items and setting methods, see "(4) HTTP request body".

For details on elements you can set in the request message (body), see "3.3.13 Defining HTTP adapters" in "Service Platform Reception and Adapter Definition Guide" .

The request line described in the first line of HTTP request is sent in the following format:

 
HTTP methodAURIAProtocol#
 

Legend:

A: Single-byte space.

Note#

Protocol is fixed as "HTTP/1.1".

HTTP methods and URI specification methods are described here.

(a) HTTP method

Specify HTTP method of the request line in the request message (header), HTTP-adapter runtime-environment property file and HTTP-adapter runtime-environment common property file.

The following table describes the specification locations of HTTP methods:

Table 2-33 Specification locations of HTTP methods

Note

You cannot specify HTTP request body for the following methods:

• GET
• DELETE
• HEAD
• OPTIONS

If you use these methods, always select data type as "No data". For data types of HTTP request body, see "(4)(a) Data types".

If you cannot specify HTTP method in the request message (header), HTTP-adapter runtime-environment property file or HTTP-adapter runtime-environment common property file, an error occurs.

(b) URI

Partition the request line URI into scheme authority, path, and query and then specify these in the request message (header), HTTP-adapter runtime-environment property file and HTTP-adapter runtime-environment common property file.

The following table describes specification locations of URI:

Table 2-34 Specification locations of URI

If scheme authority and path are not specified in the request message (header), HTTP-adapter runtime-environment property file or HTTP-adapter runtime-environment common property file, an error occurs.

If you specify "https" in the scheme part of the scheme authority, use HTTPS to communicate. However, setting is required to use HTTPS. For details, see "Appendix I Security settings required security in the HTTP adapter" in "Service Platform Reception and Adapter Definition Guide" .

An example of URI specification is as follows. The generated URI in both cases is "http://localhost:80/test/selectdata?name=sample&id=001".

• If specified in the request message (header)
  

  <http-header-request> <uri-scheme-authority>http://localhost:80</uri-scheme-authority> <uri-path>/test/selectdata</uri-path> <uri-query> <name>sample</name> <id>001</id> </uri-query> </http-header-request>

• If specified in HTTP-adapter runtime-environment property file
  

  adphttp.request.uri-scheme-authority=http://localhost:80 adphttp.request.uri-path=/test/selectdata adphttp.request.uri-query.1=name=sample adphttp.request.uri-query.2=id=001

  Reference note

  You can specify scheme authority, path or query in isolation. You can also dynamically change HTTP request destination by specifying scheme authority in HTTP-adapter runtime-environment property file and by specifying path and query in the request message (header).

  Note

  Set suitable values in scheme authority, path and query. If scheme authority and query are specified in path, and an unsuitable value is specified, operation is not guaranteed.

(c) Query

For URI query, you can customize the detailed message format for query included in the request message (header) and then specify.

An example of specification of query is as follows:

• Example of customization of detailed message format for query
  (Original)
  

  <xsd:complexType name="uri-query-type"> <xsd:sequence> <xsd:any namespace="##any" processContents="skip" minOccurs="0" maxOccurs="1024" /> </xsd:sequence> </xsd:complexType>

  (Changed)
  

  <xsd:complexType name="uri-query-type"> <xsd:sequence> <xsd:element name="parameter1" type="xsd:string" minOccurs="0"/> <xsd:element name="parameter2" type="xsd:string" minOccurs="0"/> </xsd:sequence> </xsd:complexType>

  In this example, xsd:any type element is changed to xsd:string type element that makes query name a locale name. Moreover, it is optional to the user whether to specify the number of appearances.
  
• Example of specification of request message (header)
  

  <http-header-request> <uri-scheme-authority>http://localhost:80</uri-scheme-authority> <uri-path>/test/selectdata</uri-path> <uri-query> <parameter1>value1</parameter1> <parameter2>value2</parameter2> </uri-query> </http-header-request>

• Generated query
  

  http://localhost:80/test/selectdata?parameter1=value1&parameter2=value2

  Note

  • Only the value specified under uri-query element is valid and attributes are ignored even if specified.
  • If an element containing hierarchical structure is specified, the value of the query generated by the element is not guaranteed.
  • Appearance order is not guaranteed when multiple identical key names are defined.
  • Even if URI contains basic authentication account information as in "http://user:password@example.jp:80/httprcp1/op1", it is not used as basic authentication information.
  • If a query is specified in the request message (header), you cannot use an invalid character in the query key name as NCName.

You can specify any extension header for HTTP request header according to http-header element (any type) of the request message (header) and adphttp.request.header.userdef.<Additional number> property of HTTP-adapter runtime-environment property file (or HTTP-adapter runtime-environment common property file).

You can specify any name space, since only locale name is used for element name.

If separate headers are specified in the request message (header) and HTTP-adapter runtime-environment property file (or HTTP-adapter runtime-environment common property file), only the specification in the request message (header) is valid. The header specified in HTTP-adapter runtime-environment property file is not added in the specification in the request message (header).

(a) Example of specification of HTTP header

An example of specification of HTTP header is as follows:

• Example of specification of request message (header)
  

  <http-header-request> <http-header> <X-PRIORITY>HIGH</X-PRIORITY> <X-DOCUMENT-ID>12345-67890</X-DOCUMENT-ID> </http-header> </http-header-request>

• Example of specification of HTTP-adapter runtime-environment property file
  

  adphttp.request.header.userdef.1=X-PRIORITY:HIGH adphttp.request.header.userdef.2=X-DOCUMENT-ID:12345-67890

• Generated HTTP request header
  

  X-PRIORITY:HIGH X-DOCUMENT-ID:12345-67890

(b) Special HTTP header specification

HTTP header described in the following table is ignored even if specification is in http-header element of the request message (header) and adphttp.request.header.userdef.<Additional number> property of HTTP-adapter runtime-environment property file (or HTTP-adapter runtime-environment common property file).

Table 2-35 Example of specification in special HTTP header

(c) Points to be considered

Points to be considered when HTTP header is specified are as follows:

• For the value specified in http-header element, only the value under http-header element is valid and attributes are ignored even if specified.
• If an element containing hierarchical structure is specified in http-header element, value of the header generated by the element is not guaranteed.
• You can specify up to 1,024 request headers under http-header element. If 1,025 or more elements are specified, operation is not guaranteed.
• If HTTP header is specified in http-header element, you cannot use an invalid character in header field name as NCName.
• Description order of HTTP header in HTTP adapter is not guaranteed. If there are multiple header fields with identical names, they are set in HTTP request in the same state.
• If HTTP header and Content-Type header are not specified in the request message (header), HTTP-adapter runtime-environment property file or HTTP-adapter runtime-environment common property file, Content-Type header may be automatically provided depending on the sent contents.
• If a header field name other than extension header is specified, operation is not guaranteed. If a header field name other than extension header is specified, guarantee the operation sufficiently and then use.

(a) Data types

You can select the data type to be sent in HTTP request body from the following details:

• Form data (normal mode)
  Transform data specified in a request message (body) to form data and set this data in HTTP request body.
  
• Request message (body) (pass-through mode)
  Set data specified in a request message (body) as is in HTTP request body.
  
• File data
  File contents are set in HTTP request body.
  
• No data
  HTTP request body is not set. Select GET method, if HTTP request body is not to be sent.
  

You can specify HTTP request body data type in the binding element of the request message (header) and adphttp.request.part.message.binding property of HTTP-adapter runtime-environment property file (or HTTP-adapter runtime-environment common property file).

However, if files element exists in the request message (header), it will be handled as file data even if the above element (or property) is specified. Similarly, if adphttp.request.part.file.<Additional number>.input-folder-name property of HTTP-adapter runtime-environment property file (or HTTP-adapter runtime-environment common property file) exists, it will be handled as file data even if adphttp.request.part.message.binding property is specified.

(b) Form data (normal mode)

To send form data by normal mode, customize and then specify the message format for form data provided by the service platform.

An example of specification of form data is as follows:

• Example of customization of message format for form data
  (Original)
  

  <xsd:complexType name="http-body-form-data-type"> <xsd:sequence> <xsd:any namespace="##any" processContents="skip" minOccurs="0" maxOccurs="unbounded" /> </xsd:sequence> </xsd:complexType>

  (Changed)
  

  <xsd:complexType name="http-body-form-data-type"> <xsd:sequence> <xsd:element name="parameter1" type="xsd:string" minOccurs="0"/> <xsd:element name="parameter2" type="xsd:string" minOccurs="0"/> </xsd:sequence> </xsd:complexType>

• Example of specification of request message (header)
  

  <http-body-formdata> <parameter1>value1<parameter1> <parameter2>value2<parameter2> </http-body-formdata>

• Generated HTTP request header and request body
  

  Content-Type: application/x-www-form-urlencoded parameter1=value1&parameter2=value2

URL encoding occurs for the specified form data. Default character code is UTF-8.

Note

• For the value specified in http-body-formdata element, only the value under http-body-formdata element is valid and attributes are ignored even if specified.
• If an element containing hierarchical structure is specified in http-body-formdata element, form data value generated by the element is not guaranteed.
• Appearance order of form data is not guaranteed in HTTP adapter. Appearance order of form data need not always match the order specified in the request message (body).
• For the value specified in http-body-formdata element, URL encoding occurs in the character code specified in charset attribute of Content-Type header. Always specify in the format before URL encoding.
• If you specify form data in http-body-form data element, you cannot use an invalid character as NCName in key name of form data.

(c) Request message (body) (pass-through mode)

If data specified in the request message (body) in pass-through mode is set as is in HTTP request body, create a message format of the request message (body) that matches HTTP request body format to be sent.

(d) File data

In HTTP adapter, you can send the files in the working folder or common folder to the target server.

Working folder is a temporary folder created on HCSC server for each request by HTTP reception or FTP reception. You can only see the working folder from the business process invoked by the created reception.

Common folder is any folder created by the user during system setup. You can store files shared and used by multiple business processes.

To send file data, specify information related to file data in the request message (header) and HTTP-adapter runtime-environment property file (or HTTP-adapter runtime-environment common property file). You can only use common folders to specify in the property files.

The following table describes the specification locations of file data:

Table 2-36 Specification methods of file data

Legend:

-: There is no applicable specification location.

The following figure shows an example of file sending using HTTP adapter:

Figure 2-87 Example of file sending using HTTP adapter (while using common folder)

The value of the request message (body) passed to HTTP adapter is ignored while sending file data. Use message format for file data to store blank body data in the message format of the specified request message (body).

Note

• If only file element is specified in the request message (header) and no lower file element is specified, HTTP request is sent when HTTP request body is in blank status.
• If multiple file elements are specified, the value of the element appearing first is used.
• While sending file data, if the folder in which the file to be read or the file is not specified or if the specified folder and file do not exist, an error occurs.