HTTP request

HTTP request is a processor that for each incoming job executes an HTTP or HTTPS request. Thus the incoming job is a request trigger and it can be used to define the request specification: URL, authentication data, request parameters, file to upload, etc. The protocol type (HTTP or HTTPS) is automatically detected from the URL: if the URL starts with “https://”, HTTPS is used, otherwise HTTP is used.

The server responds to the request by sending something back: an HTML source, JSON or XML data, or a file that is downloaded. The tool provides properties to manipulate this server response. The server response is always saved as a file and the tool can inject this file into the flow as a new job, attach it as metadata dataset to the incoming job or assemble it into a job folder together with the incoming job.

Keywords

If you enter one of the following keywords in the Search field at the top of the Flow Elements pane, the HTTP request element will be shown in the list:

HTTP
HTTPS
POST
PUT
GET
HEAD
download
upload
request

Connections

HTTP request supports outgoing traffic-light connections:

The 'Data' connections transfer the server response file as well as the input job (depending on the property values specified for the flow element).
The 'Log' connections transfer a generated text log file containing the request URL, the finished status, the status code, the status description, the last error and other relevant information. The log file name is generated from the input job file name by replacing the input job extension with 'log'.
The 'Success out' connections are used in case the request finished status is ‘Ok’ and the HTTP request status code is in the range 100-299.
The 'Error out' connections are used in case the request finished status is not ‘Ok’ or the HTTP request status code is in the range 300-599. The input job may fail in case of some internal tool error or invalid tool settings.

Properties

Property	Description
Name	The name of the flow element displayed in the canvas.
Description	A description of the flow element displayed in the canvas. This description is also shown in the tooltip that appears when moving your cursor over the flow element.
URL	The URL to fetch. The URL string must be URI-encoded (in a URI-encoded string a space is shown as %20). The tool detects the protocol to use for the request automatically from the URL: if the URL starts with 'https://', the tool will use HTTPS, otherwise HTTP will be used. Example 1 (entered using the ‘Single-line text with variables’ editor); assumes the job name can contain only ASCII alphabetic characters and digits: https://api-content.dropbox.com/1/files_put/auto/[Job.Name] Example 2 (entered using the 'Script expression' editor): HTTP.encodeURI( "https://api-content.dropbox.com/1/files_put/auto/" + job.getName() );
Request type	The type of the request. The supported request types are: PUT (used for uploading data) GET (used for downloading data) HEAD (used for retrieving response headers) POST (used for uploading with extra parameters) Note: The value for the "Content-Type" header in the request is generated automatically depending on the request type and other settings like MIME encoding and defined parameters. In the HTTP request tool, it is not possible to define the custom header value. However in some cases it is possible by writing a script that uses the HTTP class from the Switch scripting API. More details about the automatically generated value for the "Content-Type" header and the ways to specify a custom value for it, can be found in Switch scripting reference.
Attached file	This property is available only if Request type is POST or PUT. A file to append to request if the POST or PUT requests are used. The file will be uploaded to the server.
Use MIME encoding	This property is available only if Request type is POST. To use MIME encoding, choose Yes; otherwise choose No (default).
File variable	This property is available only if Request type is POST and Use MIME encoding is Yes. The name of the HTTP form data variable that is used by the receiving HTTP server to identify the correct file part of the uploaded MIME package.
Authentication scheme	The authentication scheme to use when server authorization is required. If the property is set to None (default), no authentication is performed. If this property is set to Basic, the User name and Password properties must be set, and in this case the element will attempt basic authentication. If the authentication scheme is set to Digest, NTLM or Negotiate, digest, NTLM or Negotiate authentication will be attempted instead. If the authentication scheme is set to Proprietary, the authorization token must be supplied through the Authorization property. If the authentication scheme is set to OAuth, the authorization string must be supplied through Authorization property.
User name	This property is available only if Authentication scheme is Basic, Digest, NTLM or Negotiate. A user name if authentication is to be used.
Password	This property is available only if Authentication scheme is Basic, Digest, NTLM or Negotiate. A password if authentication is to be used.
Authorization	This property is available only if Authentication scheme is Proprietary or OAuth. The authorization string to be sent to the server.
Parameters	The parameters to attach to the request. Each parameter should be specified in a separate line by the string 'key=value' (without quotes). The parameters are URI-encoded automatically. For the POST and PUT requests, the parameters are included in the HTTP request after the HTTP headers. For the HEAD and GET requests, the parameters are appended to the URL after the question mark ('?'). Example: root=auto path=[Job.JobState]
Headers	The headers to attach to the request. Each header should be specified on a separate line by the string key:value. Example: Content-Type : text/plain
Response	The response received from the server is always saved to a file. This property defines how to handle this file: Inject as new job: the response is sent to the output data connections as a new job. Attach as dataset: the response is attached to the input job as an opaque dataset with the name 'HTTPResponse' and then the input job is sent to the output data connections. Assemble in jobfolder: the response is assembled into a new jobfolder together with the input job and the jobfolder is sent to the output data connections. The jobfolder name is the same as the name of the input job (without the extension). Discard: the response is discarded. In this case the input job is sent to the output data connections.
File Name	This property is available only if Response is Inject as new job or Assemble in jobfolder. The file name (with an extension) to use for the response file. Automatic: The tool will attempt to determine the file name from the Content-Disposition header of the server response. If the Content-Disposition header is missing or does not contain a valid file name, the tool will use the default file name "Response".
Input job	This property is available only if Response is Inject as new job. Defines what to do with the input job in case the response file is injected as a new job: Send to output: the input job is sent to the output data connections as a separate job. In other words, the input job and the response file are now two separate jobs. Attach as dataset: if the input job is a file, it is attached as an opaque dataset with the name 'HTTPInput' to the new job representing the response file. If the input job is a folder then it is discarded and an error message is logged. Discard: the input job is discarded.
Response headers	This property defines how to handle the response headers: Attach as dataset: the response headers are saved to a text file (each header on a separate line in format 'key:value') and the file is attached to the output job as an opaque dataset with the name 'HTTPResponseHeaders'. Discard: the response headers are discarded.