The OUTPUT FILE operator allows you to write data from the data bus to a file in the selected format and location. It operates on the input data stream — each record and its columns (bits) are converted into the file content according to the operator’s configuration.
This makes it possible to:
- export data to standard file formats such as CSV, XLSX, JSON, XML, and others,
- save processing results to the file system — a local or shared directory — with support for dynamically generated file names (e.g., based on date, bit values, or project parameters),
- build file-based integrations, where the result of a GRAVITY application’s operation is a physical file that can be downloaded, transferred, or further processed.
The operator also allows you to configure the file structure (e.g., headers, separators, data types) and format the data according to the recipient’s requirements.
The operator’s mode of operation depends on the selected format:
- For standard file formats (CSV, JSON, XLSX, XML, etc.), the operator works on the entire bus data set, generating a single, consistent file.
- For binary file formats or text file formats, the operator works at the level of individual records, meaning that each record can generate a separate file or file content — for example, when saving binary document data or text data prepared earlier, such as data created using the
CONVERT BITS TO FORMAT operator.
The OUTPUT FILE operator is commonly used in reporting processes, data export, invoice generation, backup creation, and building file-based data exchange interfaces.
Example of a GRAVITY project using the OUTPUT FILE operator:
OUTPUT FILE TYPES
The GRAVITY software allows you to save the data stream from the bus to selected file formats.
The available file types are:
- XLSX
- CSV
- XML
- JSON
- Binary
- Text
Depending on the file type, you have to fill out the specific information required for converting the data bus to the selected file type in the File format tab.
SETTING OUTPUT FILE PARAMETERS
In the OUTPUT FILE PROPERTIES you can configure the necessary parameters for the file generated by the operator.
In the Target file recognization parameter, specify how the new file should be created:
- Choosen file → The file will always be saved to the location specified in the Path parameter. If a file with the same name already exists in that location, it will be overwritten with new data.
- New file → The system will create a new file with the specified name. The save path will be taken from the Path field. Both the file name and the Path field can be parameterized.
- File path from busbar → The file path and name are taken from a bit in the data bus.
The PATH field defines either the file path only or both the path and file name, depending on the selected save method. The field can be parameterized using system variables, project parameters, and data bus bits. To insert a parameter, place the cursor at the position where you want to add it, then click the parameters button (marked in red in the screenshot below).
In the parameters window, select the parameter and click the Insert button.
In the Action after processing failure option, select what should happen if the processing fails.
By default, processing creates a new file or overwrites the existing one if a file with the same name is found in the current location.
You can specify one of the following actions:
- NO ACTION → processing does not generate a new file,
- CREATE OR OVERWRITE EMPTY FILE → the generated file will be empty,
- REMOVE OLD FILE → if a file with the same name exists in the specified location, it will be deleted,
- REVERT → if a file existed in the location and was overwritten, it will be restored.
OUTPUT FILE FORMAT CONFIGURATION Depending on the selected output file format, you need to configure various parameters for the generated file (in the File format tab).
- XLSX → requires specifying the sheet name.
- CSV → requires defining details of the CSV file format, such as the data separator, whether the first row contains column names, and the file encoding.
- XML → requires modeling the XML file structure based on the bus bits using the XML Format Editor.
- JSON → requires modeling the JSON file structure based on the bus bits using the JSON Format Editor.
- Binary → allows you to save files containing binary data. The binary data must be transported in the data bus as a bit of type Blob. Configuration consists of selecting the bus bit that represents the binary data. This type will generate as many files as there are records in the bus.
- Text → allows you to save files containing text data. Configuration consists of selecting the bus bit that represents the text data and defining the encoding in which the file will be saved. This type generates one file per record on the bus.
