Data File Upload

Applies to: Kyvos Reporting

Kyvos Reporting allows you to browse and upload files, validate them, and initiate data flow processing to ingest data into tables, queries, cubes, and reports. Data administrators can schedule regular incremental data loads into target tables.

Set Up Upload Templates

Create a folder named after the organizationId at:
Jakarta/webapps/Kyvos Reporting/client/config/
Open the configuration.properties file in the same directory, and set the ReportEnginePath property on the last row.
Use the FileUploadTemplate.json file to define templates in the organization-specific folder:
Jakarta/webapps/Kyvos Reporting/client/config/<organizationId>/
Each template specifies the file format, number of columns, fixed column names, and other validation criteria.
Create an Upload folder inside:
ReportEngine/data/
This folder will store user-uploaded files.

Configure Upload in Kyvos Reporting

Go to Navigate > Design > Data File Upload. You can also access this page from the Home shortcut.
Set up an Upload connection in Kyvos Reporting that points to the Upload folder. This connection must match the one referenced in each template in FileUploadTemplate.json.
Choose a template. The allowed file format appears based on your selection.

Upload and Validate a File

Select the file to upload. Ensure that the file follows the required template and format. A sample template file is available to download using the Download Sample Template button.
If a file with the same name exists, choose to rename or overwrite the existing file.
When you click Upload, the file is validated against criteria defined in the selected template.
On successful validation, the file is copied to the Report Engine data folder.
The uploaded file appears in the list with the status Uploaded, and multiple actions:
- Load Now
- Download
- Delete
These appear when you hover over the uploaded file.
File upload history is stored in:
Jakarta/webapps/Kyvos Reporting/client/output/<organizationId>/UploadHistory.json

Actions on Uploaded Files

Load Now: Opens the corresponding entity (query, report, or job) in a new tab for execution.
Download: Download the file for your reference.
Delete: Prompts for confirmation, then deletes the file from the Upload folder.

After loading, the file list updates with the latest status and actions. You can filter files by status: Loaded, Uploaded, Loading Failed, or Deleted.

Using Placeholder Parameters

If your query, report, or job uses a placeholder parameter, specify the PlaceholderParameterName in the template. This parameter is automatically set to the uploaded file name during execution.

Sample FileUploadTemplate.json

{
  "Template1": {
    "Description": "Validates file structure before loading.",
    "sampleFilePath": "../data/sample/sample.xlsx",
    "afterUploadCopiedPath":"../data/modifiedpath",
    "EntityInfo": {
      "EntityType": "Query",
      "EntityId": "159895434970026ad3a3e7-aeff-4742-8bfa-c7b8ea1a8f12643479",
      "DeleteOnSuccessfulLoading": false,
      "ConnectionName": "DemoFileSource",
      "ConnectionLocation": "../data/demofilesource",
      "PlaceholderParameterName": ""
    },
    "ValidationCriteria": {
      "AllowedExtn": "csv",
      "NoOfColumns": "6",
      "Fix_Columns": ["Salespersonid", "Salesperson", "Storeid", "Month", "Targetsales", "Testcol"],
      "CheckForNonEmptyFile": "No",
      "CheckColumnNamesForMonth": "No",
      "MinFileSize": "0",
      "CheckFirstTenCharactersForDate": "No",
      "CheckColumnsForSubset": "No",
      "skipFirstNRows": "0"
    }
  }
}

Template Key Descriptions

Key	Description

Key	Description
Description	A brief description of the upload template.
"sampleFilePath": "../data/sample/sample.xlsx"	The sample file is available at this path for users to download and use as a reference.
"afterUploadCopiedPath":"../data/modifiedpath"	Backup path where uploaded files can be copied manually. If a file goes missing from the original connection location, users can download it using the Download button on the portal.
EntityInfo	Contains information about the linked query, report, or job.
EntityType	Specifies the type: `Query`, `Report`, or `Job`.
EntityId	Unique identifier or job name.
ConnectionName	The name of the connection pointing to the file location.
ConnectionLocation	Path to the folder where the file is stored.
DeleteOnSuccessfulLoading	If `true`, deletes the file after successful loading.
PlaceholderParameterName	Name of a text parameter used in the entity to reference the uploaded file.
ValidationCriteria	Criteria against which the uploaded file is validated.

Validation Criteria Fields

Property	Description

Property	Description
AllowedExtn	Allowed file extensions (e.g., `.csv`, `.xlsx`, `.txt`).
NoOfColumns	Number of expected columns. Use `"0"` to skip.
Fix_Columns	Array of expected column names in the exact order. Use `[]` to skip.
CheckForNonEmptyFile	Set to `Yes` to ensure file is not empty.
CheckColumnNamesForMonth	Set to `Yes` to ignore columns with month names in validation.
MinFileSize	Minimum file size (used for `.txt` files). Leave blank to skip.
CheckFirstTenCharactersForDate	Checks first 10 characters for a date in `DD.MM` format (only for `.txt`).
CheckColumnsForSubset	Validates if file columns are a subset of `Fix_Columns`.
skipFirstNRows	Number of rows to skip from the top of the file. Must be a non-negative integer.