INPUT FILE

The INPUT FILE operator allows data to be retrieved from files located in the local file system or in a shared file system (e.g., a network directory). It serves as an input data source for the GRAVITY application.

The operator supports popular data formats such as CSV, XLSX, XML, JSON, as well as binary and text files. Depending on the type and structure of the file, the operator generates the appropriate number of fields (columns) on the output bus, corresponding to the data fields in the file, or a fixed set (containing the file’s metadata and its contents) for Binary or Text files.

The INPUT FILE operator can be linked to a File trigger, which automatically starts processing in GRAVITY when a file appears in the monitored directory.

It is one of the fundamental operators used for system integration through file-based data exchange — both in batch and cyclic scenarios.

Example of a GRAVITY project using the INPUT FILE operator.

The operator supports multiple file types.

The available file types are:

XLSX
CSV
XML
JSON
Binary
Text

Depending on the selected file type, the operator either transfers the file’s contents and metadata to the data bus (Binary file and Text file types) or converts the data contained in the file and builds the data bus based on the converted data (for other file types).

SETTING INPUT FILE PARAMETERS

In the Template File tab, you can configure the necessary parameters to specify the file or the file data template that will be converted into bus bits, as well as the file whose contents will be transferred to the data bus.

You can provide the file template in two ways by setting the Template source switch.

as a file path

Set the Template source option to Template file.
Use the Choose button to select a file on your disk.

Use this option if you plan to always use the same file for data retrieval. In this case, make sure to set the File recognization field to Only template file in the Input file properties tab

as a text-based template

Set the Template source option to Inserted text.
Paste a sample file into the Text template field, or load it from a file by clicking the Load from file button.
Click the Generate tree button to generate the file’s data structure.

This option is available only for file types that can be converted into data bus format (XLSX, CSV, XML, JSON).

SETTING THE DATA FORMAT

After entering the file data, you can set the file data format in the File format tab. The tab displays different information depending on the selected file type.

for the XLSX type:

The File format allows you to define the structure of the XLSX file. You can specify which worksheet to retrieve data from, whether the data includes column headers and which row they are in, as well as how many rows you want to skip.

To view the result, click the Test button.

The selected file is interpreted according to the defined format, and a list displaying the read data will be returned. The column names will serve as the bits of the data bus coming out of this operator.

for the CSV type:

The File format tab allows you to define the structure of the CSV file. You can specify the data separator, indicate whether the first row contains column headers, and define the file encoding.

To view the result, click the Test button.

for the XML type:

The File format tab displays the data structure of the XML file. By clicking a selected node, you mark it to be used as a data bus bit.

Because the file structure can be hierarchical, while the data bus is a flat data stream, the values of elements from higher levels are duplicated on the bus as many times as there are elements at the lowest level of nesting.

To view the result, click the Test button.

The columns above will become the data bus bits. As shown, the file contained one order with two items. For this reason, the order header data was duplicated twice.

for the JSON type:

Identical to the XML type.

for the Binary type:

The File format tab requires you to specify whether you want to download only the file indicated in the Path to a template file field or all files from the directory.

To view the result, click the Test button.

The data bus will contain as many rows as the number of files loaded and will be built from data bits storing the file metadata along with a data field containing the binary file data (encoded in base64).

for the Text type:

Similar to the binary type, except that file data is transferred in text format, and the field containing the text data is called textData.

GENERATING THE DATA BUS

Regardless of the file type you choose, you must generate the data bus. The Columns tab is used both to generate the data bus and to modify the bits that have already been generated.

After generating the data bus bits, you can click a bit to modify its name, description, and data type. The structure of this component’s output data bus will depend on the data you configure here.

If you modify the data bus bits after the operator is already connected to another operator via the bus, it may be necessary to use the Autogenerate columns option on the bus.

WORKING WITH INPUT FILES

The file selection during process execution depends on the configuration of the file properties, which can be set in the Input file properties tab. Each FILE INPUT operator also automatically generates a parameter in the system with a unique name, which can receive the full path to the file, including its name.

Whether and how the operator uses the parameter depends on the FILE RECOGNIZATION, option, which allows the following modes of operation:

ONLY TEMPALTE FILE→ GRAVITY always retrieves the file explicitly specified in the PATH TO TEMPLATE FILE field on the TEMPLATE FILE tab.
USER CAN CHOOSE FILE → The file is retrieved from the operator parameter value. This can be provided manually at runtime or during automatic triggering. In the case of an automatic FILE-type trigger, the path to the new file that triggered the process will be passed to the operator parameter.
OLDEST IN CHOOSEN PATH → GRAVITY automatically selects the oldest file from the location (PATH TO TEMPLATE FILE.)

You can also perform actions on the file processed by the operator. GRAVITY provides the following options:

NO ACTION → the file is retrieved and remains in its original location;
CHANGE FILE NAME → the file remains in its location, but its name is changed;

The new file name can be designed using variables (the range of available variables is shown in the contextual help).

MOVE FILE → the file is moved to another location;
REMOVE FILE → the file is deleted after being retrieved.