CSV Imports

Framework

CSV imports are made within the overall imports framework. An import is defined by an import view, and imports data into a target view.

Imported data

The values of the import data unknown must be text values in comma-separated value (CSV) form, consisting of lines of comma-separate fields.

Each line is imported as a row of the target view. The values of the unknowns of the row of the target view are supplied in the line of the CSV file and the values of the unknowns of the import view. For example, the target view could have unknowns Country and City, the import view could have unknown Country, and the import specification could define a CSV column for City. The import view could then have rows for different countries, and the cities data for each country could be imported independently. The values of import view unknowns can be supplied in the page assignments rather than the rows of the view.

If the target view has a key, and the imported line matches an existing row, then the defining item of the existing row is kept and triples are added and deleted as necessary to give the row the values of the imported fields. If the import view does not have a key, then a new item is created for each imported line, and triples are added to make a row with it as the defining item and with the imported fields as unknown values. The imported fields are interpreted as having the display types of the unknowns to which they are mapped, which can be text, boolean, integer real, date or date and time display types. 

Blank lines after the start line are ignored. If the view has a key, lines that do not have fields for all key unknowns are ignored.

Import Specification

A value of the import specification unknown must be a text value in JSON form. It must contain the following fields.

  • format must be "CSV"
  • view the path (e.g. "home/test/v1") to an item definition view (the import view)
  • source the identification number of the source into which the data is to be imported
  • fields a JSON object whose keys are unknowns of the import view and whose values identify the CSV columns that are to be imported as values of the unknowns. Columns are identified by letter strings "A", . . "Z", "AA", . . "ZZ", "AAA", . . etc.

It may also contain some or all of the following fields:

  • readlevel a string specifying the only-read access level that created items are to have (e.g. "public" or "home:admin"). If this is not supplied, the only-read access level of imported items will be the access level of the requesting user.
  • writelevel a string specifying the read-or-write access level that imported items are to have (e.g. "home:admin"). If this is not supplied, the read-or-write access level of imported items will be the access level of the requesting user.
  • start an integer specifying the line of the CSV file at which import should start. The first line of the CSV file is line 1, and this is assumed to be the start line if no start is specified.
  • delete existing items not in input a boolean value. If the import view has a key, then existing rows that do not have the same key value as an imported line are deleted if this is true, and retained if it is false. If the import view does not have a key, all existing rows are deleted if this is true, and retained if it is false. If the import view has a key, and an existing row has the same key values as an imported line, then the existing row is edited as if the imported fields had been supplied as inputs (existing values for which there are imported fields are replaced, existing values for which the imported fields are blank are not.)
  • date format a string giving the format of values of unknowns with Date display type (e.g. "d/M/yy") 
  • date-time a string giving the format of values of unknowns with Date and Time display type (e.g. "MMMM d, yyyy, h:m a")
  • decimal point character a string containing the character used in the CSV file as the decimal point in currency values. If it is not specified, a value of "." is assumed. All values of Real display type are treated as if they might be currency values.
  • minus in brackets a boolean specifying whether numbers in brackets in the CSV file are to be treated as negative currency values. If it is not specified, it is assumed to be false.