sc-import-csv

This document is a user guide for the sc-import-csv component version 6.00, released February 12, 2020.

1 Purpose

sc-import-csv places an import csv file field on a form allowing the user to select a csv file and save its rows as documents in the database.

The import csv file field on the form provides:

• A button to browse and select a csv file for importing.
• An area to drag and drop a selected csv file for importing.
• A Results Table to display:
  • Counts at the foot of the Results Table to show:
    • The total number of items (rows) within the selected CSV file.
    • The current page number and total number of pages within the Results Table.
    • The number of selected rows within the Results Table.
  • Each row within the selected csv file together with their import status e.g.
    • "Awaiting Save"
    • "Imported - documentId"
    • "Replaced - documentId"
    • "Updated - documentId"
    • Failed - Error replacing document: Error preprocessing save fields on update: sc-date-time field named date has invalid value "24/15/2015 11:20 a"
• A "SAVE" button to save the rows displayed as "Awaiting Save" in the Results Table as documents in the database by using a pre-defined document template. The fields of the pre-defined document template define how each csv file row field is to be imported as a field of a database document e.g. as a text, check box, check-list, date, drop down, phone or email, etc field.
• A "CLEAR" button to clear the Results Table and cancel the import process.
• Counters above ther Results Table to show "Records Read", "Documents Created" and "Errors".

Section 3 Supported Date, Checkbox and Checklist Formats of this document lists the sc-import-csv supported formats for fields that need to be imported as a date/time, checklist or checkbox field in a database document.

The sc-import-csv definition provides fields for setting the properties of the sc-import-csv field 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

2.2 Required Customizable Fields

2.3 Optional Customizable Fields

3 Supported Date, Checkbox and Checklist Formats

This section lists the sc-import-csv supported formats for fields that need to be imported as a date/time, checkbox or checklist field in a database document.

3.1 Supported Date/Time Fomats

The sc-import-csv supported formats for date/time fields in a csv file are listed in the table below:

3.2 Supported Checkbox Formats

The sc-import-csv supported format for checkbox fields in a csv file is shown in the table below:

3.2 Supported Checklist Formats

The sc-import-csv supported format for check list fields in a csv file is shown in the table below:

4 Typical 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",
            "name": "testScImportCsv",
            "label": "Test sc-import-csv using csv file with & without documentId, checklist & checkbox values",
            "templateId": "759afa00-0f84-11e7-bd5b-0570620003a4",
            "labels": [
                "document ID",
                "First Name",
                "Surname",
                "Email",
                "Phone",
                "Days Available",
                "On Leave",
                "Employee Type",
                "Date Submitted"
            ],
            "columns": [
                "documentId",
                "testImportToParty.firstName",
                "testImportToParty.surname",
                "testImportToEmail",
                "testImportToPhone",
                "testImportToCheckList",
                "testImportToCheckBox",
                "testImportToDropDown",
                "testImportToDateTime"
            ],
            "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

5 Examples

Example 1

sc-import-csv defined with the typically needed fields.

        {
            "componentName": "sc-import-csv",
            "name": "testScImportCsv",
            "label": "Test sc-import-csv using csv file with & without documentId, checklist & checkbox values",
            "templateId": "759afa00-0f84-11e7-bd5b-0570620003a4",
            "labels": [
                "document ID",
                "First Name",
                "Surname",
                "Email",
                "Phone",
                "Days Available",
                "On Leave",
                "Employee Type",
                "Date Submitted"
            ],
            "columns": [
                "documentId",
                "testImportToParty.firstName",
                "testImportToParty.surname",
                "testImportToEmail",
                "testImportToPhone",
                "testImportToCheckList",
                "testImportToCheckBox",
                "testImportToDropDown",
                "testImportToDateTime"
            ],
            "fullWidth": true,
            "disableSave": true
        }

Resulting field on the form:

The templateId field "templateId": "759afa00-0f84-11e7-bd5b-0570620003a4" of this sc-import-csv definition identifies the pre-defined template that sc-import-csv will use to create a document for each successfully imported csv file row. The components section of this pre-defined template is shown below and defines each field listed as a value of the sc-import-csv columns array.

    "components": [
        {
            "componentName": "sc-party",
            "name": "testImportToParty",
            "label": "Contact Name",
            "fullWidth": true
        },
        {
            "componentName": "sc-email",
            "name": "testImportToEmail",
            "label": "Contact Email"
        },
        {
            "componentName": "sc-static-html",
            "fullWidth": true,
            "html": "<br/>"
        },
        {
            "componentName": "sc-phone-number",
            "label": "Contact Phone Number (click to dial)",
            "name": "testImportToPhone"
        },
        {
            "componentName": "sc-static-html",
            "html": "<br/>",
            "fullWidth": true
        },
        {
            "componentName": "sc-check-list",
            "name": "testImportToCheckList",
            "label": "Days Available",
            "list": [
                "Mon",
                "Tue",
                "Wed",
                "Thu",
                "Fri",
                "Sat",
                "Sun"
            ],
            "fullWidth": true
        },
        {
            "componentName": "sc-static-html",
            "fullWidth": true,
            "html": "<br/>"
        },
        {
            "componentName": "sc-check-box",
            "name": "testImportToCheckBox",
            "label": "On Leave"
        },
        {
            "componentName": "sc-static-html",
            "fullWidth": true,
            "html": "<br/>"
        },
        {
            "componentName": "sc-drop-down",
            "label": "Employee Type",
            "name": "testImportToDropDown",
            "dropDownList": [
                "Full Time",
                "Part Time",
                "Casual",
                "Probation"
            ]
        },
        {
            "componentName": "sc-static-html",
            "html": "<br/>",
            "fullWidth": true
        },
        {
            "componentName": "sc-date-time",
            "label": "Date Submitted",
            "name": "testImportToDateTime"
        }
    ]

Resulting form for the pre-defined template:

A csv file to be imported using the above sc-import-csv field:

Each of the six rows of the above csv file has nine data fields containing in order the data items listed below.

Note: Comma delimiters indicate the start or end of a field regardless of the whether the field has value or not e.g. the fifth row of the above csv file has no value for its 1st and 6th fields (i.e. the "documentId" and "Days of the week a person is available" fields).

Field 1: documentId

Field 2: First Name of a person (will be saved in the predefined template's sc-party field)

Field 3: Surname of a person (will be saved in the predefined template's sc-party field)

Field 4: email Address of a person (will be saved in the predefined template's sc-email field)

Field 5: Phone Number of a person (will be saved in the predefined template's sc-phone-number field)

Field 6: Days of the week a person is available (will be saved in the predefined template's sc-check-list field)

Field 7: Indicates if a person is on leave (fwill be saved in the predefined template's sc-check-box field)

Field 8: Employment status of a person (will be saved in the predefined template's sc-drop-down field)

Field 9: Date & Time field (will be saved in the predefined template's sc-date-time field)

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

Clicking the "CLEAR" button will clear the Results Table and cancel the import process.

Clicking the "SAVE" button will save the selected csv file to the database such that one document is created and saved for each row in the csv file.

Resulting field on the form after clicking the "SAVE" button:

To open a created document, click its hyperlink in the Result column.

Clicking the Results Table's 4th row hyperlink opens the document:

Resulting document in the database:

The templateId "759afa00-0f84-11e7-bd5b-0570620003a4" is both used to create, save and display the successfully imported documents.