Skip to content

sc-import-json

go-to-typical-definition

sc-import-json-field-Example-1-Image-3

1 Purpose

This document is a user guide for the Formbird sc-import-json component version 5.1.

sc-import-json places field on a form allowing the user to select a json file and save the documents within the file as documents in the database.

The import json file field on the form provides:

  • A button to browse and select a json file for importing.
  • An area to drag and drop a json file for importing.
  • A Results table to display each document within the selected json file and their import status (e.g. "Awaiting Save").
  • A "CLEAR" button to clear the Results table and cancel the import process.
  • A "SAVE" button to save the documents within the json file as documents in the database by using a pre-defined template.
  • Counters for "Records Read", "Documents Created" and "Errors".

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

2 Definition

sc-import-json 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-json The component name.

Example:
"componentName": "sc-import-json"

2.2 Required Customizable Fields

Field Valid Values Description
columns Array of field names An ordered array of field names where each field is a field in:
  • Each document within the imported json file.
  • The template definition whose documentId is the templateId field value.
    • On saving, the template is used to:
      • Create a document in the database for each document within the imported json file. Each created document has the array field names in array field name order and set to their corresponding json file field values.
      • Display each created document.

        • Example:
          See Example 1 below in Section 4 Examples
      name Any value written in camel case. Defines the name of the sc-import-json field in the document and database.

      Example:
      "name": "testScImportJson"
      templateId A template id The id of the template used to create a document for each successfully imported document in the json file.

      Example:
      "templateId": "7a359860-3cec-11e6-bd1a-f78cdb4c4f6f"

      2.3 Optional Customizable Fields

      Field Valid Values Description
      directImporting true The imported json file documents are immediately added to the database as documents and the results displayed in the Results table.
      The Results table will need to be cleared before an additional file can be imported.

      Example:
      "directImporting": true
      false Defaults to false.
      The imported json file documents are not immediately added to the database as documents.
      The sc-import-json field's dedicated "SAVE" button must be clicked to save the results displayed in the Results table.
      disableSave true Selecting a json file does not trigger the Save icon to flash.
      Exiting the form without saving the selected json file does not trigger a warning message to display.
      Note: As sc-import-json provides a dedicated "Save" button, recommend defining sc-import-json with "disableSave": true.

      Example:
      "disableSave": true
      false Default value. Selecting a file does trigger the Save icon to flash.
      Exiting the form without saving the selected file does trigger a warning message to display.
      disableSaving true The sc-import-json field's dedicated Save button is hidden.

      Example:
      "disableSaving": true
      false Defaults to false.
      The sc-import-json field's dedicated Save button is visible.
      Clicking the Save button will save the imported json file to the database.
      One document is created and saved for each document in the json file.
      documentIdMatch Enable the user to update an existing database document by supplying its documentId in the json file.
      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 deleting the document contents, and adding just the fields in the json file to the document. If the replace is successful, the Results column of the Results table displays:
      Replaced -6f8a0520-5a5f-11e9-991a-1faf1584063b

      If there is an error in the json file data, the error count is incremented by one and the Results column of the Results table displays a meaningful error message, e.g.:
      Failed - Error replacing document: Error preprocessing save fields on update: sc-date-time field named date_stamp 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 updating the document fields that are in both the json file and the document and adding document fields that are in the json file but not in the document. If the merge is successful, the Results column of the Results table displays:
      Updated - 6f8a0520-5a5f-11e9-991a-1faf1584063b

      If there is an error in the json file data, the error count is incremented by one and the Results column of the Results table displays a meaningful error message, e.g.:
      Failed - Error updating document: Error preprocessing save fields on update: sc-date-time field named date_stamp has invalid value "24/15/2015 11:20 a"
      documentIdNoMatch Enable the user to insert a new database document by supplying its documentId in the json file.
      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 found, then a document is not added to the database, the error count is incremented by one and the Results column of the Results table displays a meaningful error message, e.g.:
      documentId 6f8a0520-5a5f-11e9-991a-1faf1584063b is in database and adding is not enabled

      If the json file documentId field is empty, the error count is incremented by one and the Results column of the Results table 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 json file.

      If the document is found, the error count is incremented by one and the Results column of the Results table displays a meaningful error message e.g.
      Failed: - Error inserting document: Document exists: 94682f20-5b5e-11e9-8d0b-fb1a625205ff

      If the json file documentId field is empty, then a new document is added to the database with a generated documentId and the Results table Results column displays:
      Imported - 94682f20-5b5e-11e9-8d0b-fb1a625205ff<*".
      enabled false The sc-import-json control buttons and Results table are greyed out, cannot be clicked and a Stop icon appears on mouseover.
      A json file cannot be selected for import.

      Example:
      "enabled": false
      true Defaults to true.
      The sc-import-json control buttons and Results table are not greyed out, can be clicked and a Stop icon does not appear on mouseover.
      A json file can be selected and imported.
      fullWidth true The import json file field displays full width on the form.
      Note: As sc-import-json contains multiple gui elements including a grid, recommend defining sc-import-json to display full width on the form.

      Example:
      "fullWidth": true
      false Defaults to false.
      The import json file field does not display full width on the form.
      label Any value Defines the name of the import json file field on the form i.e. the field label.

      Example:
      "label": "Test sc-import-json"
      Defaults to no field label is displayed.
      labels Array of any values An ordered array of values to be used as column headings for the Results table.

      Example:
      See Example 1 below in Section 4 Examples.
      Defaults to the array of field names defined by the "columns" field.
      mandatory true The import json file field displays as mandatory (i.e. label in red text with an asterisk).
      Saving without importing a json file, a message prompts the user to import a json file.

      Example:
      mandatory": true
      false Defaults to false.
      The import json file field displays as optional (i.e. field label in black text).
      Saving without importing a json file, a message does not prompt the user to import a json file.
      visible false The import json file field is not visible on the form.

      Example:
      "visible": false
      true Defaults to true.
      The import json file field is visible on the form.

      3 Typical Definition

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

              {
                  "componentName": "sc-import-json",
                  "name": "testScImportJson",
                  "columns": [
                      "documentId",
                      "date_stamp",
                      "zone_id",
                      "zone_name",
                      "operational_state",
                      "wat_category",
                      "zoneGeo"
                  ],
                  "labels": [
                      "Document ID",
                      "Date Stamp",
                      "Zone ID",
                      "Zone Name",
                      "Operational State",
                      "Water Category",
                      "Zone Geometry"
                  ],
                  "label": "Test sc-import-json",
                  "fullWidth": true,
                  "templateId": "44524840-55dc-11e9-be36-2f29df521630",
                  "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-json defined with the typically needed fields.

              {
                  "componentName": "sc-import-json",
                  "name": "testScImportJson",
                  "columns": [
                      "documentId",
                      "date_stamp",
                      "zone_id",
                      "zone_name",
                      "operational_state",
                      "wat_category",
                      "zoneGeo"
                  ],
                  "labels": [
                      "Document ID",
                      "Date Stamp",
                      "Zone ID",
                      "Zone Name",
                      "Operational State",
                      "Water Category",
                      "Zone Geometry"
                  ],
                  "label": "Test sc-import-json",
                  "fullWidth": true,
                  "templateId": "44524840-55dc-11e9-be36-2f29df521630",
                  "disableSave": true
              }
      

      Resulting field on the form:

      sc-import-json-field-Example-1-Image-1

      Below is a sample json file that could be imported using the above sc-import-json field:

      sc-import-json-field-Example-1-Image-2

      The above json file contains 3 documents each having the following 7 fields:

      • "documentId": The value of this field:
      • Will display in the Results table "Document ID" column.
      • Will be saved in the template's "documentId" field.

      • "date_stamp": The value of this field:

        • Will display in the Results table "Date Stamp" column.
        • Will be saved in the template's "date_stamp" field.
      • "zone_id": The value of this field:

        • Will display in the Results table "Zone ID" column.
        • Will be saved in the template's "zone_id" field.
      • "zone_name": The value of this field:

        • Will display in the Results table "Zone Name" column.
        • Will be saved in the template's "zone_name" field.
      • "operational_state": The value of this field:

        • Will display in the Results table "Operational State" column.
        • Will be saved in the template's "operational_state" field.
      • "wat_category": The value of this field:

        • Will display in the Results table "Water Category" column.
        • Will be saved in the template's "wat_category" field.
      • "zoneGeo": The value of this field:

        • Will display in the Results table "Zone Geometry" column.
        • Will be saved in the template's "zoneGeo" field.
        • Defines the geometry of a polygon allowing it to be displayed on a map.

      Resulting field on the form after selecting the above json file:

      sc-import-json-field-Example-1-Image-3

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

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

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

      sc-import-json-field-Example-1-Image-4

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

      Clicking the 1st hyperlink in the Results table opens the document created for the 1st document within the json file:

      sc-import-json-field-Example-1-Image-5

      Notes:

      1. The above document was created and is being displayed using the predefined template whose documentId is the templateId field value in the sc-import-json definition.
      2. The fields of the above document were saved in the database as:
          "documentId": "6f839c80-5a5f-11e9-991a-1faf1584063b",
          "date_stamp": "2018-08-20T02:35:00.000Z",
          "zone_id": "1",
          "zone_name": "Hansen Reserve",
          "operational_state": "ACTIVE",
          "wat_category": "POTABLE",
          "zoneGeo": {
              "type": "FeatureCollection",
              "features": [
                  {
                      "type": "Feature",
                      "geometry": {
                          "type": "Polygon",
                          "coordinates": [
                              [
                                  [
                                      144.87159004211424,
                                      -37.8016954692588
                                  ],
                                  [
                                      144.87596740722654,
                                      -37.80223801120207
                                  ],
                                  [
                                      144.87545242309568,
                                      -37.80474721584969
                                  ],
                                  [
                                      144.87442245483396,
                                      -37.80461158534551
                                  ],
                                  [
                                      144.87429370880125,
                                      -37.80600178620508
                                  ],
                                  [
                                      144.87086048126218,
                                      -37.80562880805537
                                  ],
                                  [
                                      144.87159004211424,
                                      -37.8016954692588
                                  ]
                              ]
                          ]
                      },
                      "properties": {}
                  }
              ]
          }
      
      1. The fields in the database document have the same name as the corresponding fields in the json file.
      2. The order of the fields in the database document matches the order of the fields in the sc-import-json definition columns array.
      3. If the predefined template used to create the above document did not have a field name exactly matching a field name in the imported json file, the document would still be created but the field would not display on the form until the predefined template was updated with a matching field name.