Skip to content

Web Request

Calls an HTTP or HTTPS endpoint from the Clarive server and makes the response body available to the rest of the rule. Use it to notify another system of what the job is doing, or to read a value out of an API before deciding what the job does next.

The op is deliberately plain. It sends one request and never retries, and any response outside the 2xx range stops the job. For calls that need scripting, looping or error handling of your own, drive the endpoint from Server CODE instead.

Form Arguments Headers Body query string, whatever the Method ?key=value&key2=value2 request headers request body, sent as UTF-8 endpoint _ws_code _ws_body Those two stash variables are set even when the request fails.

Fields

URL

The endpoint to call, including the scheme. Expands ${var} against the stash.

A query string written here does not survive. The op always rebuilds the query from Form Arguments, so http://host/api?token=abc loses the token, and loses it silently when Form Arguments is empty. Put every query parameter in Form Arguments.

The request goes out from the Clarive server, so the endpoint has to be reachable from there rather than from your browser. Proxy settings in the Clarive server's environment are honoured.

Method

GET, PUT, DELETE or POST. The default is GET. Other verbs are not offered.

The method does not change where Form Arguments end up. They are query parameters on a POST the same as on a GET.

Redirects are followed automatically for GET, up to seven hops. POST, PUT and DELETE are not redirected, so a 301 from an endpoint that moved shows up as a failure.

Encoding

The character set for the request. Defaults to utf-8.

Set it to something else, such as iso-8859-15, and the URL, the form arguments and the headers are converted into that character set before the request is built, names as well as values. The Body is not. It is always sent as UTF-8 whatever this field says, which matters when you are posting accented text to an endpoint that expects a legacy encoding.

Timeout

Seconds to wait for the response. 0, which is the default, means no explicit limit is applied and the request gives up after 180 seconds. The value covers the whole exchange, connection and response together.

A timeout fails the step the same way a bad status code does.

User

The user name for HTTP basic authentication. Left blank, no authentication header is sent, and Password is ignored along with it.

Filling this in also overrides any Authorization header you set in the Headers tab. The basic credentials are attached to the request first and headers are only added where the request has none, so a bearer token in Headers is dropped without warning when User has a value.

Password

The password for basic authentication, masked in the form. Only used when User is filled in.

The value is stored with the rule. Reference a variable here rather than typing a live credential into the rule.

Accept any server certificate

Ticked, the HTTPS certificate presented by the endpoint is not checked, so self-signed and hostname-mismatched certificates are accepted. Unticked, which is the default, a bad certificate fails the step.

Data

A tab panel with the three parts of the request.

Form Arguments

A YAML mapping, one key-value pair per line:

service: bar
title: ${job_name}

These become the query string on the URL, for every method. They are not a request body and they are not a form post, despite the field name. To send a form body, put the encoded pairs in Body and set Content-Type to application/x-www-form-urlencoded.

Both keys and values expand ${var}. The editor validates the YAML on save. Comments are discarded.

Leaving this empty is not neutral: an empty set still replaces whatever query string was in the URL, and the URL goes out with no query string at all.

Headers

Key-value pairs in YAML, same editor and same rules:

Content-Type: application/json
Authorization: Bearer ${api_token}

The headers worth setting by hand are Content-Type, which tells the endpoint how to read your Body, Authorization for token schemes that basic authentication does not cover, Accept to pick a response format, and User-Agent when the endpoint logs callers. Content-Length is worked out for you.

Body

The raw request body, sent as written apart from the UTF-8 encoding mentioned above. Expands ${var}.

${json(myvar)} renders a whole stash variable as JSON, which is the usual way to post a structure you assembled earlier in the rule rather than hand-writing the braces.

Setting Content-Type to multipart/form-data on a POST switches this field into a different mode. Instead of being the body, the text is read as a single name and value split on the first comma, equals sign or colon, and turned into one multipart part. Write no separator at all and the part is named text with your text as its value.

The value is then treated as a path to a file to upload, unless it contains a space or one of : * ? " < > |, in which case it is sent as a literal value. So report, /tmp/foo.txt uploads that file under the name report, while report, some text sends the words. An empty Body produces a multipart request with no parts. Unless you need exactly this, leave Content-Type as something else.

What the step leaves behind

Two stash variables are written on every call, before success or failure is decided:

Variable Holds
_ws_code the HTTP status code as a number
_ws_body the response body as text

Because they are set before the failure check, they are readable from a CATCH statement, which is the only way to see why a call failed without digging through the job log.

Set a Return Key in the op properties panel to keep the result under a name of your own. The value carries content with the response body, so a Return Key of resp gives you ${resp.content}. It also carries response, the whole reply as an object rather than text, which is of little use from the rule tree. The multipart case returns content on its own.

Because the returned value is a map, a Return Key of = merges both keys straight into the stash and gives you ${content} instead.

Nothing is written under the Return Key when the call fails, since the step stops before returning. _ws_code and _ws_body are your only source in that case.

Failure

Any status outside the 2xx range logs the response body as an error entry and stops the job with HTTP request failed, followed by the status line, the URL and the form arguments rendered as JSON. There is no way to tolerate a 404 on this form. Wrap the op in TRY statement and CATCH statement, then inspect _ws_code.

The op does not retry. Put it inside RETRY for flaky endpoints.

A rollback pass runs the op again, with the same method and the same body, unless you untick Run Rollback in the op properties panel. A POST that created something on the far side will create it a second time.

Combining with other ops

Assemble the payload first with SET VAR or EVAL JavaScript, then render it with ${json(myvar)} in the body.

Parse the answer with EVAL JavaScript reading ${_ws_body}, then branch on the result with IF var condition THEN.

For calls to another Clarive instance, see webservices.

Examples

Read a value from an API and keep the body for the next op.

URL             https://api.example.internal/v1/status
Method          GET
Form Arguments  project: ${project}
                env: ${env}
Headers         Accept: application/json
Timeout         30
Return Key      status_call

Post a JSON document built from a stash variable.

URL             https://hooks.example.internal/deploy
Method          POST
Headers         Content-Type: application/json
                Authorization: Bearer ${api_token}
Body            ${json(deploy_payload)}
Timeout         60

Send a SOAP 1.1 call, with the envelope as the body and the action in a header.

URL             http://soap.example.internal/service.asmx
Method          POST
Headers         Content-Type: text/xml; charset=utf-8
                SOAPAction: "http://example.internal/GetQuotation"
Body            <?xml version="1.0"?>
                <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
                  <SOAP-ENV:Body>
                    <m:GetQuotation xmlns:m="http://example.internal/quotations">
                      <m:QuotationsName>${foo_var}</m:QuotationsName>
                    </m:GetQuotation>
                  </SOAP-ENV:Body>
                </SOAP-ENV:Envelope>