Create a communication variable such as an HTTP request to interact with a Web service.
For instructions on how to create a complex variable, see here.
HTTP Request
(Available from version 7.0 onwards.)
Create and send an HTTP request to a Web service using an HTTP request variable.
To send an HTTP request to a Web server:
-
Define the HTTP request by creating an HTTP Request variable and then setting the values of its properties.
Not all properties are relevant to all requests. Specify only those required by the relevant Web service.
-
Define additional headers using the Add Header (and Remove Header) methods.
-
Send the request using the Post Request or Post Request Asynchronously method.
-
Read the response written to the XML Response property.
Properties
Show
| Property | Input Type | Description |
|---|---|---|
| Tex |
The media types that are acceptable for the response, for example, application/json, application/xml, text/html (Available from version 7.2) |
|
| Authentication Type | Text |
The authentication mechanism supported by the Web service. Supported values: Basic: Requires a username and password from the user for authentication. Digest: Requires username and password from the user for authentication. Negotiate: Uses the Windows login credentials for authentication. NTML: Uses the Windows login credentials for authentication. (Available from version 7.2) |
| Auto Redirect | Boolean | Specifies if automatic redirection of the Web request is enabled (true) or disabled (false). |
|
Text |
The HTTP request content type, for example, text/xml; charset=utf-8. |
|
|
Text |
The HTTP request inbound character encoding. If not specified, iso-8859-1 is used. |
|
|
Text |
The HTTP request outbound character encoding. If not specified, iso-8859-1 is used. |
|
|
Text |
The HTTP request password. This is used if Windows Authentication is set to False (which it is by default). |
|
|
Text |
The HTTP request proxy password. |
|
|
Test |
The HTTP request proxy port. |
|
|
Text |
The HTTP request proxy server. |
|
|
Text |
The HTTP request proxy username. |
|
|
Text |
The HTTP request method, for example, GET (default) or POST. |
|
| Response Headers | List of Key-Value Pairs |
A list of the response headers as key-value pairs. (Available from version 7.2) |
| Status | Text |
The status of the Web service request. (Available from version 7.2) |
|
Number |
The HTTP request timeout (in milliseconds) that indicates how long to wait until the request is timed out. |
|
|
Text |
The HTTP request URL, for example, https://od-api.oxforddictionaries.com/api/v2/entries/en-us/process. If you need to build the URL dynamically, use the concatenate function. |
|
|
Text |
Identification of the application type, operating system, software vendor, or software version of the requesting software user agent. |
|
|
Text |
The HTTP request user name. This is used if Windows Authentication is set to False (default). |
|
|
Boolean |
Specifies whether or not to use Windows Authentication. If set to True, the Windows Credentials are used to log in to the Web service instead of the User name and Password properties. Default is False. |
|
|
Text |
The HTTP request. The content can be JSON or any other format and is not required to be XML-valid text. |
|
|
Text |
The HTTP response. The content can be JSON or any other format and is not required to be XML-valid text. Use the standard text actions to parse a JSON response and extract the relevant data. If the response is XML, use the XML actions for the parsing. |
Methods
Abort Asynchronous Request
(Available from version 7.3)
Aborts the asynchronous request. This can be used to abort the request that is taking a long time to process.
Parameters
| Parameter | Input | Description |
|---|---|---|
|
Request ID |
Text |
ID of the Web service request. |
Returns
Does not return any value.
Add Header
Adds a header to the HTTP request.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
Header |
Text |
The name of the header. |
|
Value |
Text |
The value of the header. |
Returns
Nothing.
Example
This example adds the header app_id with value 0690342d8 to the HTTP request named GetDefinition.
Get Value of Response Header
(Available from version 7.2)
Returns the value of the specified header of a response.
Parameters
| Parameter | Input | Description |
|---|---|---|
|
Header |
Text |
The header from which you want the response value. |
Returns
Returns the response value of the specified header as text.
Post File with Request
(Available from version 7.4)
Posts the HTTP request to the Web server together with a specified file. Use this method to send the file in a request using form-data structure.
Parameters
| Parameter | Input | Description |
|---|---|---|
|
Key Name |
Text |
The name of the key to which the file must be attached. |
| File Path | Text |
The full path to the file to upload. Example: C:\temp\request.txt |
Returns
Returns True if the request was sent successfully, else returns False.
Post File with Request as Binary Body Data
(Available from version 7.4)
Posts the HTTP request to the Web server together with a specified file. Use this method to send the contents of a file as binary data in the request body.
Parameters
| Parameter | Input | Description |
|---|---|---|
| File Path | Text |
The full path to the file to upload as binary body data, for example, C:\temp\request.txt |
Returns
Returns True if the request was sent successfully, else returns False.
Post Request
Posts the HTTP request to a Web server, together with its properties and headers. The next scheduled action will be delayed either until a response is received or until the request times out. (For an asynchronous equivalent, see Post Request Asynchronously.)
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
none |
|
|
Returns
Returns the HTTP post request status as a Boolean value where TRUE indicates that a response was successfully received.
Example
This example sends the HTTP request named GetDefinition. The response status is stored in the variable RequestSuccess.
When the project is run, the response from the Web server is written to the XML Response property. The variable RequestSuccess is set to TRUE, indicating that the request was successful.
Post Request Asynchronously
Posts a request to a Web Server asynchronously. As is this is an asynchronous method, after this method is run the next scheduled action will be run immediately without waiting until a response is received. (For the synchronous equivalent, see Post Request.)
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
none |
|
|
Returns
Nothing.
Example
This example sends the HTTP request named GetDefinition. Any actions following this one will be run immediately without waiting for a response to be received.
Post Request and Save Response as File
(Available from version 7.4)
Posts the HTTP request to the Web server. The response is saved in the specified file. This method should be used instead of Post Request when expecting a response that is not plain text, for example, a binary file.
Parameters
| Parameter | Input | Description |
|---|---|---|
| Full Path | Text |
The full path to the file in which to save the response. Example: C:\temp\response.txt |
Returns
Returns True if the request was sent successfully, else returns False.
Remove All Headers and Header Values
Removes all the headers and header values from the HTTP request.
Returns
Returns True if all the headers were successfully removed, else returns False.
Remove Header
Removes a header from the HTTP request.
Parameters
|
Parameter |
Input Type |
Description |
|---|---|---|
|
Header |
Text |
The name of the header to remove. |
Returns
Nothing.
Example
This example removes the header named app_id from the HTTP request GetDefinition.
Retrieve All Headers and Header Values
(Available from version 7.3)
Retrieves all the headers and the header values from the HTTP request. This function does not use any parameters.
Returns
Returns all headers and header values as a List of Text.
Set Client Certificate with Password
(Available from version 7.3)
Specifies the path of the certificate to send with the HTTP request for authentication, along with the password for the certificate.
Parameters
| Parameter | Input | Description |
|---|---|---|
|
Path |
Text |
Path of the certificate. |
|
Password |
Text |
Password for the certificate. |
Returns
Does not return any value.
Set Client Certificate with Password from Local Store
(Available from version 7.3)
Specifies the path of the certificate to send with the HTTP request for authentication. The password is fetched automatically from the local machine certificate store.
Parameters
| Parameter | Input | Description |
|---|---|---|
|
Path |
Text |
Path of the certificate. |
Returns
Does not return any value.
Update Header Value
(Available from version 7.3)
Updates the header value in a header of the HTTP request.
Parameters
| Parameter | Input | Description |
|---|---|---|
|
New Value |
Text |
The new value to add to the header. |
|
Header |
Text |
The name of the header to which to add the new value. |
Returns
Returns True if the header value is updated, else returns False.
Events
The events of HTTP Request library are listed below:
| Events | Description |
|---|---|
| Async Callback |
This event is raised when the execution of Post Request Asynchronously is completed. This event has one parameter:
(Available from version 7.2) |
| Exception |
This event is raised when an HTTP request gets an exception, after the request is sent to the server. This event has one parameter:
|
Example
Show
Oxford Dictionaries offers an API for retrieving information about words. See their developer portal for more information. This example shows a project designed to retrieve the definition of the word process.
An HTTP Request communication variable, GetDefinition, is defined.
A Boolean variable RequestSuccess is also defined.
The workflow below works as follows.
-
1 and 2: Specify the app ID and app key for inclusion in the request header. (You will need to apply for your own API to try this out.)
-
3: Set the URL for the request.
-
4: Sets the method to get.
-
5: Sends the request. The success/failure response is written to the Boolean variable RequestSuccess.
After running the workflow, the response from Oxford Dictionaries is written to the XML Response property (partially shown below). Note that in this case the response is in JSON format.
The Boolean RequestSuccess was set to TRUE as a response was successfully received.
