The Download tool retrieves data from a specified URL to be used in downstream processing or to be saved to a file. The Download tool can also download or upload data via FTP and SFTP.
Configure the tool
Use the Basic tab to set the mandatory controls for the Download tool.
- URL Field: Specify the field from the incoming data stream that contains the URL (Uniform Resource Locator - Internet resource) to pull data from (or upload data to). This could simply be a Text Input Tool where the URL is specified as a field value.
- Encode URL Text: When checked, the specified URL will be encoded as needed where unsafe ASCII characters are converted into a format that can be transmitted over the internet. An example of this would be the substitution of %20 for a space.
- Output: Specify how the returned data should be formatted. The data can be returned in a data field or output to a file.
- To a Field: Downloaded content is returned in the data stream as a data field. The downloaded contents will be in a single field called "DownloadData". You will likely have to parse this data using downstream tools such as the Text To Columns Tool, RegEx Tool, or Formula Tool.
- String: Data is returned as a new wide string type field. A wide string supports Unicode® characters.
- Blob: Data is returned as a new blob type field. Blob is also known as Binary large objects. Image files are usually stored in this format. To use the image, configure am Image Tool downstream and specify Image or Blob field.
- To a File
- Temporary File: Data is output to a temporary file and will be located in the user's temporary directory. For more on temp file handling in Alteryx, see Alteryx and Temporary Files.
- Filename from a Field: Data is output to a specific file where the file specification is in an incoming field. Use the dropdown to select the field that contains the file name to output to.
Select one of the Code Pages to use for encoding. Default is UTF-8. For the most consistent results, applications should use Unicode, such as UTF-8 (code page 65001) or UTF-16, instead of a specific code page.
Use the Headers tab to modify the HTTP headers sent with the web request.
- Add from the following constant values: Allows for adding fixed header values.
- And values from these fields: Takes values from the record data and creates header values.
Use the Payload tab to set the HTTP Action you would like to perform and optionally build the Query String or Body for the web request.
- HTTP Action: Select the HTTP Action for the web request. Choices include:
- GET (or FTP): Perform a GET request or download a file from an FTP or SFTP site. This option can be used without entering any other options on this tab and will download the selected URL.
- POST: Performs a POST request to the selected URL. Typically when using this option you would specify a POST body using the below options.
- PUT: Performs a PUT request. This option only allows you to take the query body from a blob field via the Blob Input Tool. Typically used to upload a file to the remote server.
- DELETE: Performs a DELETE request. Typically used to ask the remote server to delete a specified resource.
- HEAD: Performs a HEAD request. This asks the sever to return the header data, but not the body data.
- Custom: Allows you to enter a custom verb in a text box. Everything else about this request behaves the same as a POST. The POST verb is replaced by the custom verb just before the request is made.
These options only work if the remote server that you are sending the requests to supports a particular verb. Check the API documentation of the URL you are using to see what requests are supported.
- Compose Query String/Body:
- From the Following Constant Values: Adds constant name value pairs to the query string/body
- And values from these fields: Takes name value pairs from the incoming data record. The field name is the name used in the Query String/Body
- Content-Type: Controls how the name value pairs are encoded.
- Application/x-www-form-urlencoded: e.g. Name1=Value1&Name2=Value2&Name3=Value3. Unsafe ASCII characters are automatically encoded, so make sure your data is not already encoded.
- Multipart/form-data: Only available when using HTTP Actions POST and Custom.
All text data is UTF-8 encoded before being sent to the remote web server.
Use the Connection tab to set up connection credentials.
- Username: Enter the user name if required by the URL specification above. This is an optional field.
- Password: Enter the password if required by the URL specification above. This is an optional field.
- Maximum Connections: Specify the maximum number of simultaneous transfers for the Download tool to perform. Transfers are only done in parallel when there are multiple input records sent to the Download tool. Multiple Download tools operate independently, but do not typically function at the same time. For new Download tools added to a workflow, the default number of connections is 2 and the maximum number of connections is 32.
- Timeout (seconds): Specify the number of seconds to wait before reporting a timeout due to an unresponsive connection. Select a number from 0 (never timeout) to 10,000.
Increasing the number of connections may reduce the total time taken to complete all transfers, but please use caution not to set the number too high as it could overload the server being used. It is possible the server could quit responding, report errors, or even refuse connections if it believes you are misusing it. This is particularly important when accessing a public site that is not under your control. Most web browsers will do as many as 6 simultaneous transfers, but these would typically be relatively small transfers as a part of a web page. For a server inside your own business where you have more control over how it is configured, using a higher number of connections may be okay.
Additionally, because the Download tool will send records downstream as transfers complete, it will likely result in a change in the order of records as they pass through the tool. If the order matters to your workflow, make sure to sort the results or limit the number of connections to 1. Finally, please note that empty URLs will be processed ahead of those that require an actual transfer.
To avoid connection delays when using the Download tool, ensure that the “Automatically detect settings” option is deselected within your account’s internet properties (Control Panel > Internet Options > Connections > LAN Settings).