File Download

Overview

The FileDownloadWorkEntryExecutor downloads rows from a database or a text file that can be in a CSV, Fixed, EBCDIC, or XLSX format. For CSV files, the supported predefined formats are documented here.

Parameters

This executable class accepts the following parameters:

ParameterDescription
filePathPath of the output file. This can include internal, parameter, or ampersand variables to generate file names dynamically. See Common executable features.

The parameter can also include a source column name within {} to split the source into multiple output files. One file will be generated for each distinct column value. For example, filePath=/path/output-{ZIP_CODE}.csv generates a file for each distinct ZIP_CODE selected from the source.

Instead of a column name, you can also use a Groovy method to programmatically determine the file split by appending an empty {}. For example, filePath=/path/output-{}.csv invokes the chooseMultiFileId Groovy method for each row to decide the destination file. For more information, see Download Groovy methods.

Mandatory: Yes
fileOption

Specifies the action for the output file. Possible values are the following:

  • CREATE — A new file will be created. If a file with the same name already exists, an error will occur.
  • APPEND — The file will be appended to an existing file.
  • REPLACE — An existing file is replaced with the new file.

Default: CREATE
Mandatory: No

fileFormat

Specifies the output format for the downloaded data. Possible values are the following:

  • CSV
  • FIXED
  • XML

Default: CSV

Mandatory: No

maxFileCountSpecifies the maximum number of output files that can be created on a multi-file download. This parameter prevents accidental opening and creation of an excessive number of files, which can cause operating system resource problems, such as too many open file handles.

Default: 1
Mandatory: No
textInQuotesOnly applies to CSV file formats.

If set to true, the text fields are placed in quotes.

Default: false
Mandatory: No
textQuoteOnly applies to CSV file formats.

Specifies the character to use as the quote if textInQuotes is set to true.

Default: "
Mandatory: No
sourceIdSpecifies the source ID to select the data to download. The source ID should point to a source definition, which can either be a table or a query.

If omitted, the file download Executable code block should not contain a {source} placeholder.
createHeaderDetermines if a header record should be written to the output file. If the source is set to true, the column names from the source will be used for the header unless the header parameter is specified to override this default.

Default: false
Mandatory: No
headerOnly applies when createHeader parameter is set to true.

Specifies the custom header to override the column names from the source.

You can also include newline characters to create a multiline header. In this case, {header} can be specified to inject the source's columns into an otherwise custom column.
headerOption

Only applies when createHeader parameter is set to true and task's thread is greater than 1.

Determines whether the first or all threads will contain the header. Possible values are the following:

  • FIRST_THREAD — Only the file created for the thread 1 will contain the header.
  • ALL — All files produced by the task’s threads will contain the header.

Default: FIRST_THREAD
Mandatory: No

recordSpecifies the columns to be written to the output. For example, record=CUSTOMER_NUMBER, NAME, ZIP select only the three specified columns for the download.

For CSV file format, the parameter value can include a length indicated in {}. For example, record=NAME{30}.

For FIXED file format, the parameter value can include a position or length in {}. If the start value is omitted, record=COL1{,33}, the position will be the previous field's ending position + 1, or 0 if the specified column is the first field. If only the starting position is specified, record=COL1{12}, it will start from that position, and the length will be taken from the database metadata for the selected column.
delimiter

Defines the character that should be placed between each field in the output file.

The following are the default values for each file format:

  • CSV — ,
  • FIXED — no character
  • XML — the delimiter parameter is ignored.
zeroPadIf set to true, numeric values are padded with zeros as applicable.

For CSV and FIXED formats, decimals will be zero-padded on the right.
filterSpecifies the expression to filter the source selection. For example, filter=zip in (‘60601’,’60602’) selects all rows with the 60601 and 60602 zip codes.

You can also add WHERE expressions to this parameter.
orderSpecifies the order of the source selection. For example, order=customer_number desc orders the selection in descending customer number sequence.

You can also add ORDER BY expressions to this parameter.

There is no default order unless the source is a query and includes an ORDER BY.
trailerDefines a complete SELECT SQL statement to select the data for a trailer record. The statement should only return a single row. If multiple rows are returned, only the first one will be used for the trailer.

For example, trailer=SELECT 'TOTAL', sum(amount) from payments_table writes trailer records to the output file with the word TOTAL followed by the amount value from the payments_table table.

For CSV, the output will be comma-delimited, TOTAL,100.01. For FIXED, it will be spaced, TOTAL 100.01.

The columns can also specify modifiers between {} to override the default size and position. For example, for FIXED, trailer= select 'TOTAL' total {0,10}, sum(amount) amount {20} from payments_table will override the length of the word TOTAL to make it 10, and then change the position of amount to 20.
trailerOption

Only applies when trailer is specified and the task’s thread count is greater 1.

Specifies where a trailer is written to. Possinle values are the following:

  • LAST_THREAD — Writes the trailer only to the file created by the last thread.
  • ALL — Writes the trailer to all files.


Default: LAST_THREAD
Mandatory: No

xmlRootOnly applies for XML file format.

Defines the XML root element to use as the parent element for all the record elements.

Default: <root>
Mandatory: No
xmlRecordTemplateOnly applies for XML file format.

Specifies an XML template to wrap each record's column in. You can also specify the column elements {record} placeholder in this parameter. For example, <record-container>{record}</record-container>.

Default: The table columns are written in a flat structure as direct children of the root element.
Mandatory: No
xmlColumnNamesOnly applies for XML file format.

If set to false, the table column names are converted to camel case for the element names. If set to true, the column names format is retained.
xmlRootOption

Only applies when xmlRoot parameter is specified and task's thread is greater than 1.

Determines whether the first or all threads will contain the XML root element. Possible values are the following:

  • FIRST_THREAD — Only the file created for the thread 1 will contain the XML root element. The file created for the last thread will contain the closing tag.
  • ALL — All files produced by the task’s threads will contain the root element and the closing tag.

Default: FIRST_THREAD
Mandatory: No

skipGroovyCompile

This parameter is only checked when saving a task with a Groovy code in it.

Determines whether a Groovy code will be skipped or compiled.

If set to true, the Groovy will not be compiled and could be saved with compile errors.

If set to false, any Groovy code will be compiled to check the syntax when saving a task.

Default: false
Mandatory: No

File Download Data Blocks

Data blocks on a download task can be used to define multiple downloads in a single task. This allows related downloads to be grouped logically without creating separate tasks and chain steps.

Any parameter can be specified as an actual parameter, or it can be specified in a data block in the form parameterId = value. For example:

filePath = /my-path/my-file-{$currentDateTime}.csv
sourceId = MY_PAYMENT_SOURCE

The parameter ID must start in column 1. A parameter specified in a Task data block overrides any value for the same parameter in the Parameters definition. This means that in a Task, the Parameters section can be used to specify the default values of the parameters and the Data Blocks section to specify supplemental parameters and override specified defaults as needed.

Rules for parameters in the Data Blocks are the same as the rules in File upload data blocks in the FileUploadWorkEntryExecutor.

Data Blocks are also used to code Groovy methods for specific or complex tasks. For more information, see Download Groovy integration.