`http_request`

This building block interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE HTTP authentication mechanisms.

It is not related to artifacts.

To trigger the execution of this building block, you can enter the following code in the deployment method from which the deployment plan is generated. See How to trigger the execution of a building block. The following code is an example.

actions:
    - name: INTERACT WITH HTTP
      short_name: HTTP 
      steps:  
      - name: TEST STEP FOR INTERACT WITH HTTP
        short_name: HTTP_TEST 
        properties:
        - key: template
          value: http_request
        - key: var_http_request
          value: my_var_http_request

is_artifact: False

In this example, the value of the var_http_request property is my_var_http_request, but it can be any other string.

If you do not indicate the var_http_request property in the step of the deployment method, then the default value for this property, http_request_default, will be used.

In both cases, this value (my_var_http_request or http_request_default) must be declared in the environment variables file.For Python, the entire path to this file is indicated in the --envFile argument of The Python deployment command.

To run correctly, this building block requires environment variables. Indicate them in a .yml file. Indicate The generic environment variables for the Ansible and Python building blocks and adapt their values to your target z/OS environment. Indicate also the variables that are specific to this building block.

The Ansible and Python common environment variables

The value of the var_http_request or http_request_default property must contain the following variables, depending on the request that you want to run:

body

String

The body of the HTTP request or response to the web service.

client_cert

Path

PEM formatted certificate chain file to be used for SSL client authentication.

This file can also include the key as well, and if the key is included, client_cert is not required.

client_key

Path

PEM formatted file that contains your private key to be used for SSL client authentication.

If client_cert contains both the certificate and the key, this variable is not required.

delay

Integer

Number of seconds to wait before the request is run.

delegate

Boolean
Default: True

The environment where the HTTP request is to be run.

It is run on the local host if you set the variable to True.

It is run on the z/OS® environment if you set the variable to False.

dest

Path

A path to download the file to (if appropriate). If dest is a directory, the basename of the file on the remote server will be used.

See Return values for more information.

headers

Dictionary

Custom HTTP headers for a request in the format of a YAML hash.

method

String
Default: GET

The HTTP method of the request or response.

The method is not restricted at the module level but it must be a valid method accepted by the service that handles the request.

retries

Integer

Maximum number of execution attempts if the status code is not reached.

return_content

Boolean
Default: False

Whether or not to return the body of the response as a content key in the dictionary result no matter it succeeded or failed.

See Return values for more information.

src

Path

Path to the file to be submitted to the remote server. It cannot be used with body.

status_code

Integer (list or elements)
Default: [200]

A list of valid, numeric, HTTP status codes that signifies success of the request.

timeout

Integer
Default: 30

The socket level timeout in seconds.

url

String
Required

HTTP or HTTPS URL in the form (http|https)://host.domain[:port]/path.

url_password

String

A password for the module to use for Digest, Basic, or WSSE authentication.

url_username

String

A username for the module to use for Digest, Basic, or WSSE authentication.

validate_certs

Boolean
Default: False

If this variable is set to false, SSL certificates will not be validated.

Examples

The following example corresponds to an HTTP request for a get method. It is used to download a file.

my_var_http_request:
   method: "get"
   url: "http://url/myfile"
   dest: "my_destination_folder"
   return_content: False
   url_username: "your_username"
   url_password: "your_password"

The following example corresponds to an HTTP request for a post method. It is used to update CSD in CICS.

http_request_default:
   method: "post"
   url: "http://url"
   body: "<request><create><parameter name='CSD'></parameter><attributes name=MYPGM' csdgroup='MYCSD'></attributes></create></request>"
   headers: "{'Content-Type': 'application/xml'}"
   return_content: True
   url_username: "your_username"
   url_password: "your_password"

Return values

The result of each building block task is displayed in the evidence file, in The results level that is embedded in step_result.

The return values for the request response body are managed as follows:

With the return_content variable.
If this variable is set to True, the response return value in the evidences contains the request response body. If this variable is set to False, the response field in the evidences does not contain the request response body.
With the dest variable.
If this variable is set in the building block, the file or folder that it points to contains the request response body and the response return value contains the path of the dest attribute (even if return_content is set to True).