Import from CSV action

The import from CSV action allows the end user to select and upload a CSV file containing records that should be imported in the application's database.

It can be enabled in grids with base transactions that can be used as a Business Component. To enable the action in those cases, use the "Import from CSV enabled" property in the Modes (WorkWith) or Grid node node.

How this action works in runtime

When the action is enabled, the user is presented with a new option in the Downloads Section: Import from CSV.

ImportFromCSVAction
Import from CSV action

When the user clicks on that option, a popup screen is shown. In that popup screen, the user can open a file picker to upload the CSV file, or drag and drop the file from its desktop.

ImportFromCSVPopup
Import from CSV popup screen

After the file is uploaded, the information contained in it is read and presented in a grid, so that the user can see the data prior to importing it.

ImportFromCSVPreview
Import from CSV preview

The user also has a button to validate the data. This will simulate the import process without doing any changes to the database, and report all problems to the end user.

ImportFromCSVValidate
Import from CSV validate

To import the data, the user must click on the "Import" button in the popup screen.

CSV file structure

The file structure expected by the import action is equal to the structure generated by the CSV export action. This means that:

  1. Columns are expected in the same order as they are defined in the grid.
  2. Columns with "Use in CSV Import/Export" set to False are ignored.

If the file contains attributes that are inferred in the transaction (attributes in other base tables and formulas), the values in those columns are ignored.

Error management policy

When importing data from a CSV file it may be possible that some of the rows in the file cannot be imported, due to various errors. For example:

  1. Missing data in a required column.
  2. Invalid foreign key values.
  3. Data with an invalid type in column.

When this happens, the developer can choose how the action will treat valid rows: should those be inserted anyway, or should those changes be rollbacked?

This can be controlled using the "Error management policy" property. This property has to possible values:

  • Stop on error: When an error is found, the process is cancelled and no changes are made.
  • Continue on error: When an error is found, the process continues processing remaining rows. After processing all rows, the ones that could be inserted are commited, and the user is informed of which rows failed.

Customization

The action can be configured globally in the KB using the K2BEntityServices Settings object, in the Standard actions -> Import from CSV node. In that object, the developer can configure:

  1. Where the action is located in the web panel and how it looks.
  2. Default names for generated objects.
  3. The "Error management policy"

The popup screen used in the action can be customized using the Import from CSV layout object.

Using this layout object, the developer may:

  1. Change the visual appearance of the popup screen and the distribution of components inside it.
  2. Give the end user the possibility to change import parameters using the ImportOptions variable (based on the K2BT_CSVImportParameters SDT), such as:
    1. The field delimiter.
    2. The string delimiter.
    3. The file's encoding.
    4. The date/datetime format.
    5. The date/time delimiters.

The layout object used in the generation is the one referenced in the "CSV Import Preview Layout" property present in the Basic Layout object used to generate the grid.