Skip to content

sc-import-csv

1 Purpose

sc-import-csv places an import csv file field on a form allowing the user to select a csv file and import and save its rows as documents into the database. A Results grid on the form displays each row of the csv file and its import status (e.g. "Awaiting Save"). Using a pre-defined template, a document is created in the database for each successfully imported csv file row.

The csv-import-csv definition provides fields for setting the properties of the sc-import-csv control and is fully described below.

2 Definition

sc-import-csv is defined by a set of name/value pair fields consisting of:

  • Required system fields
  • Required customizable fields
  • Optional customizable fields

Note:

  1. Default values for fields described in the tables below are shown in bold text.

2.1 Required System Fields

Field Valid Values Description
componentName sc-import-csv The component name.
Example: "componentName": "sc-import-csv"

2.2 Required Customizable Fields

Field Valid Values Description
columns Array of field names An ordered array of field names belonging to the template whose id is defined by the templateId field.
On saving, the template is used to create documents, the template fields in the array being set in order, to the imported csv file column values.
A document is created for each row in the csv file.
Example: See Example 1 below.
name Any value written in camel case. Defines the name of the csv import field in the document and database.
Example: "name": "testScImportCsv"
templateId A template id The id of the template used to create a document for each successfully imported row of the csv file.
Example: "templateId": "7a359860-3cec-11e6-bd1a-f78cdb4c4f6f"

2.3 Optional Customizable Fields

Field Valid Values Description
directImporting true The imported csv file rows are immediately added to the database as documents and the results displayed in the results grid.
The results grid will need to be cleared before an additional file can be imported.
Example: "directImporting": true
false Defaults to false.
The imported csv file rows are not immediately added to the database as documents.
The sc-import-csv field's dedicated Save button must be clicked to save the results displayed in the results grid.
disableSave true Ticking the check box field does not trigger the Save icon to flash.
Exiting the form without saving the ticked check box does not trigger a warning message to display.
Note: As sc-import-csv provides a dedicated "Save" button, recommend defining sc-import-csv with "disableSave": true.
Example: "disableSave": true
false Default value. Ticking the check box field does trigger the Save icon to flash.
Exiting the form without saving the ticked check box does trigger a warning message to display.
disableSaving true The sc-import-csv field's dedicated Save button is hidden.
Example: "disableSaving": true
false Defaults to false.
The sc-import-csv field's dedicated Save button is visible.
Clicking the Save button will save the imported csv file to the database.
One document is created and saved for each row in the csv file.
documentIdMatch Enables the user to supply existing database documentId's for updates.
The system first checks if the documentId exists in the database and if found completes the document changes in accordance with the values defined below i.e. replace or merge.
replace If the documentId is found, creates a new version of the document by (1) deleting the document contents, and (2) adding just the fields in the csv file to the document.
If the replace is successful, the Results column of the Results grid displays: Replaced - documentId
If there is an error in the csv file data, the Results column of the Results grid displays a meaningful error message, e.g.:
Failed - Error replacing document: Error preprocessing save fields on update: ft-date-time field named date has invalid value "24/15/2015 11:20 a"
Example: "documentIdMatch": replace
merge Defaults to merge.
If the documentId is found, creates a new version of the document by (1) updating the document fields that are in both the csv file and the document, and (2) adding document fields that are in the csv file but not in the document.
If the merge is successful, the Results column of the Results grid displays: Updated - documentId
If there is an error in the csv file data, the Results column of the Results grid displays a meaningful error message, e.g.:
Failed - Error updating document: Error preprocessing save fields on update: ft-date-time field named date has invalid value "24/15/2015 11:20 a"
documentIdNoMatch Enables the user to supply new documentId's for insertion in the database.
The system first checks if the documentId exists in the database and if not found completes the document changes in accordance with the values defined below i.e. error or add.
error If the documentId is not found, then (1) a document is not added to the database, and (2) the error count is incremented by one, and (3) the Results column of the Results grid displays a meaningful error message, e.g.:
documentId 7e148110-2600-11e6-8e7f-257d738feec4 is not in database and adding is not enabled
If the csv file documentId field is empty, a document is not added to the database and the Results column of the Results grid displays a meaningful error message.
Example: "documentIdNoMatch": error
add Defaults to add.
If the documentId is not found, a new document is added to the database with that documentId and with fields corresponding to the fields in the csv file.
If the csv file documentId field is empty, then (1) a new document is added to the database with a generated documentID; (2) the Results grid > Results column displays "Imported - documentId value".
enabled false The sc-import-csv control buttons and Results Grid are greyed out, cannot be clicked and a Stop icon appears on mouseover.
A csv file cannot be selected for import.
Example: "enabled": false
true Defaults to true.
The sc-import-csv control buttons and Results Grid are not greyed out, can be clicked and a Stop icon does not appear on mouseover.
A csv file can be selected and imported.
fullWidth true The import csv control displays full width on the form.
Note: As sc-import-csv contains multiple gui elements including a grid, recommend defining sc-import-csv with `fullWidth": true.
Example: "fullWidth": true
false Defaults to false.
The import csv control does not display full width on the form.
label Any value Defines the name of the csv import control on the form i.e. the field label.
Example: "label": "est sc-import-csv"
"name" field value Defaults to the value defined for the 'name' field, with the first letter displayed in upper case and any upper case letters displayed in lower case prefixed with an underscore.
Example: "Test_sc_import_csv" is the default value if the "name" field value was "testScImportCsv".
labels Array of any values An ordered array of values to be used as column headings for the results grid.
Example:
"labels": [
         "First Name",
         "Surname",
         "Email",
         "Phone"
]
Defaults to the array of field names defined by the above columns field.
mandatory true The import csv control displays as mandatory (i.e. label in red text with an asterisk).
Saving without importing a csv file, a message prompts the user to import a csv file.
Example: mandatory": true
false Defaults to false.
The import csv control displays as optional (i.e. field label in black text).
Saving without importing a csv file, a message does not prompt the user to import a csv file.
visible false The import csv control is not visible on the form.
Example: "visible": false
true Defaults to true.
The import csv control is visible on the form.

3 Typical sc-import-csv Definition

Below is a typical sc-import-csv definition, defined with its required fields plus any optional field whose value is typically other than its default value.

{
    "componentName": "sc-import-csv",
    "label": "Test sc-import-csv",
    "name": "testScImportCsv",
    "columns": [
        "contact.firstName",
        "contact.surname",
        "contactEmail",
        "contactPhone",
        "daysAvailable",
        "dateSubmitted"
    ],
    "templateId": "759afa00-0f84-11e7-bd5b-0570620003a4",
    "labels": [
        "First Name",
        "Surname",
        "Email",
        "Phone",
        "Days Available",
        "Date Submitted"
    ],
    "fullWidth": true,
    "disableSave": true
}

One or more of the optional fields shown below can be included in the above definition should a value other than their default value be required.

    "directImporting":true,
    "disableSaving":true,
    "documentIdMatch":"replace",
    "documentIdNoMatch":"error",
    "enabled":false,
    "visible":false

4 Examples

Example 1

sc-import-csv with only its required system fields and required customizable fields defined.

        {
            "componentName": "sc-import-csv",
            "label": "Test sc-import-csv",
            "name": "testScImportCsv",,
            "templateId": "7a359860-3cec-11e6-bd1a-f78cdb4c4f6f"
            "columns": [
                "contact.firstName",
                "contact.surname",
                "contactEmail",
                "contactPhone"
            ]
        }

Resulting field on the form:

alt text

Resulting field on the form after selecting a csv file to import:

alt text

Example 2

sc-import-csv with its required fields and three optional fields ("disableSave", "fullWidth", "labels") defined.

Note: The optional fields "disableSave" and "fullWidth" have been defined with their recommended values i.e. true

        {
            "componentName": "sc-import-csv",
            "label": "Test sc-import-csv",
            "name": "testScImportCsv",
            "columns": [
                "contact.firstName",
                "contact.surname",
                "contactEmail",
                "contactPhone",
                "daysAvailable",
                "dateSubmitted"
            ],
            "templateId": "759afa00-0f84-11e7-bd5b-0570620003a4",
            "labels": [
                "First Name",
                "Surname",
                "Email",
                "Phone",
                "Days Available",
                "Date Submitted"
            ],
            "fullWidth": true,
            "disableSave": true
        }

Resulting field on the form:

alt text