Page History

Import engine allows administrators to collect data from various data sources, and then map this data into relevant tables.

The SimpleOne import engine features the followingsupports:

• different data sources source types are supported.
• different file formats are supported (if you choose "File" as the data source).

You can choose the data source, place the data from it to the temporary table (also can be called "an import set"), and after that, with the transform maps and the field maps, you can map the data from the source with to the target tablestable.

You can find a graphical procedure view of the import process in the diagram below. A more detailed description is provided further in this article.Image Removed

concepts

General import procedure description

1. Prepare raw data.
2. Create an import source.
3. Load raw data into the import set table.
4. Create a transform map.
5. Create field maps.
6. Run a transform.
7. Verify results.

Anchor
Import Sources Import Sources

Import Sources

Creating an import source is necessary to load raw data into the system for Creating an import source is necessary to load raw data into system for further processing and transformation. You can set up an import source able to work with the different data source types and file and file formats.

1. Navigate to Import → Import Sources.
2. Click New and fill in the fields.

3. If the File type is chosen, click on the attachment icon   and attach the file you need.

   Tooltip
   onlyIcon true appendIcon info-filled iconColor blue
   You can attach JSON, XML or Excel files.

   
   

4. Click Save or Save and Exit to apply changes.

Import Source form fields

[
  {
    "property": "value"
  },
  {
    "property": "value"
  }
]

After saving, the following UI actions

appear on the import source form

. They are responsible for further import processing.

Using JSON format

You can use JSON files containing data formatted in JSON as a import source. In this case, make sure that these files follow the criteria below:

1. JSON files should be valid. Use RFC 8259 as a guideline.
2. Data types available to use in JSON structure are listed below. Dot-walking is not supported.

After loading data into the import source, saving the record and calling one of the data loading actions, a new record appears in the Import Sets related list. 

Using JSON format

You can use JSON files containing data formatted in JSON as an import source. In this case, make sure that the files follow the criteria below:

1. JSON files should be valid. Use the RFC 8259 document as a guideline.
2. Data types available to use in JSON structure are listed below. Dot-walking is not supported.

  {
    "top500": 1,
    "name": "More",
    "sector": "Oil and gas"
  }

Result: one element. The table has top500, name, sector fields and contains one record.

[ 

  {
    "top500": 1,
    "name": "More",
    "sector": "Oil and gas"
  },
  {
    "top500": 2,
    "name": "Nevermore",
    "sector": "Oil and gas"
  }
]

Result: an import set with the related table is created. The table has top500, name, sector fields and contains two recordsResult: an import set with related table created (consisting of these fields: top500,name,sector) and containing one element.

[// 
Path {
for Each Row == exportField
{
   "exportField":[
      {
         "top500": 1,
         "name": "More",
         "sector": "Oil and gas"
      },
      {
         "top500": 2,
         "name": "Nevermore",
     "    "sector": "Oil and gas"
      }
]

Result: an import set with related table created (consisting of these fields: top500,name,sector) containing two elements.

// Path for Each Row == exportField
{
   "exportField":[
      {
         "top500":1,
         "name":"More",
         "sector":"Oil and gas"
      },
      {
         "top500":2,
         "name":"Nevermore",
         "sector":"Oil and gas"
      },
	  {
		"top500": 4,
		"name": "Givememore",
		"sector": "Oil and gas",
		"more_info": "https://instance.example.com/company/34"
	  }
   ]
}

Result: an import set with related table created (consisting of these fields: top500,name,sector, more_info) containing three elements.

Generally, an import set should be created automatically based on the raw data uploaded into the import source. Import sets are intended to be a staging area for records imported from the data sources.

Import Set field description

Import set unique number. This field is populated automatically.

This field contains related import source record number. This field is populated automatically.

This field contains related import set record number. This field is populated automatically.

Import set loading state. This field is populated automatically and always read-only.

Possible values are:

• Loading – data loading into the import set is in progress.
• Loaded – data loading into the import set has been finished.
• Processed – the import set transform has been processed.
• Cancelled – data loading has been cancelled.

This field describes the structure of the table created and populated with the data automatically.

Field value example:

Table structure: (top500 | name | sector | more_info | created_at | created_by | record_id)

,
	  {
		"top500": 4,
		"name": "Givememore",
		"sector": "Oil and gas",
		"more_info": "https://instance.example.com/company/34"
	  }
   ]
}

Result: an import set with the related table is created. The table has top500, name, sector fields and contains three records.

Table and column name transformation

When converting data for import, some changes occur to the system names of columns and tables that appear in the Import Set Table Name field of the Import Sources (sys_import) table. Namely, the names are transliterated and converted according to the following rules:

1. The system changes all Cyrillic letters to the Latin ones according to their ordinal number in the list of the Latin symbols. See below how the transliteration is done:
   Cyrillic symbols [
           'а', 'б', 'в', 'г', 'д', 'е', 'ё', 'ж', 'з', 'и', 'й', 'к', 'л', 'м', 'н', 'о', 'п',
           'р', 'с', 'т', 'у', 'ф', 'х', 'ц', 'ч', 'ш', 'щ', 'ъ', 'ы', 'ь', 'э', 'ю', 'я',
           'А', 'Б', 'В', 'Г', 'Д', 'Е', 'Ё', 'Ж', 'З', 'И', 'Й', 'К', 'Л', 'М', 'Н', 'О', 'П',
           'Р', 'С', 'Т', 'У', 'Ф', 'Х', 'Ц', 'Ч', 'Ш', 'Щ', 'Ъ', 'Ы', 'Ь', 'Э', 'Ю', 'Я'
       ];
   Latin symbols [
           'a', 'b', 'v', 'g', 'd', 'e', 'io', 'zh', 'z', 'i', 'j', 'k', 'l', 'm', 'n', 'o', 'p',
           'r', 's', 't', 'u', 'f', 'h', 'ts', 'ch', 'sh', 'shch', '\'', 'y', '\'', 'e', 'yu', 'ya',
           'A', 'B', 'V', 'G', 'D', 'E', 'Io', 'Zh', 'Z', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P',
           'R', 'S', 'T', 'U', 'F', 'h', 'Ts', 'Ch', 'Sh', 'Shch', '\'', 'Y', '\'', 'e', 'Yu', 'Ya'
   ];
   
   
2. All symbols that are relevant to the regular expression /[^A-Za-z0-9_]+/u are substituted with an underscore _  symbol. That is all symbols except capital and lowercase letters, digits, and the underscore are substituted with _ .
3. A system column name is split into parts by an underscore _. Then, the parts are connected with an underscore _ . For example, the name _DOC_____1 is transformed to doc_1 as a result .

4. The current system name of the column is transformed to lowercase.

   
   

   Info
   If a column name is empty, then, when converting, the system sets the following name imp_invalid_column + column number. The column number is determined by its order in the table. The numbering starts from 0. For example, imp_invalid_column0.

   
   

5. The imp prefix is added to the name, for example, imp_client_list.

Anchor
Import Sets Import Sets

Import Sets

Generally, an import set should be created automatically based on the raw data uploaded into the import source. Import sets are intended to be a staging area for records imported from the data sources. 

Import Set form fields

Table structure: (top500 | name | sector)

Import Set records are in the parent-child relationship with the Import Set Rows table.

Anchor
Transform Maps Transform Maps

Transform Maps

Transform map is a set of field maps. In this set of field maps, correlations between fields of an import set table and fields of a target table are specified.

Each import operation requires at least one transform map which specifies the relationship between the import set table and the target table.

After creating the first import set, create a related transform map. To do this, complete the steps below:

1. Click View Transform Map on the import source form you are configuring.
2. In the appeared toast message, follow the link Create Transform Map.
3. Fill in the fields in the appeared form.
4. Click Save or Save and Exit to apply changes.

Transform Map form fields

Transform Scripts

Transform script allows you to customize import operations using JS-scripts with SimpleOne Server-Side API. 

Transform Script form fields

(function runTransformScript(source, map, log, target /*undefined onStart*/) {
  target.email = source.imp_mail; // string
  target.username = source.imp_samaccountname; // string
  
  const parsedPhoneDigits = source.imp_mobile.match(/\d/g);
  target.phone = parsedPhoneDigits ? parsedPhoneDigits.join('') : null;  // phone

  const company = new SimpleRecord('org_company');
  company.addQuery('name', 'like', source.imp_company);
  company.selectAttributes('sys_id');
  company.setLimit(1);
  company.query();
  target.company = company.next() ? company.sys_id : null;  // reference
})(source, map, log, target);

(function runTransformScript(source, map, log, target /*undefined onStart*/) {
  const duplicate = new SimpleRecord('task');
  duplicate.addEncodedQuery(`number=${source.imp_number}^sys_id!=${target.sys_id}`);
  duplicate.selectAttributes('sys_id');
  duplicate.setLimit(1);
  duplicate.query();
  if (duplicate.next()) {
    ignore = true; // skip Import Set Row
    status_message = 'The "Number" [number] field should be an unique.'; // write message to Import Set Row -> Description
  }
})(source, map, log, target);

Anchor
Field Maps Field Maps

Field Maps

Field maps are used to define the correlation between fields of the import set table and fields of the target table. For this, you need to determine the values from the source table that will be added to the target table.

To create a field map, complete the steps below:

1. Navigate to Import → Transform Maps.
2. Open the transform map you want to configure.
3. Click Create field map.
   • The Field Mapping widget appears. See the screenshot in the table below.
4. Configure field mapping within the current transformation process.
5. Click Set to save changes or Cancel to discard changes.

Field Map form fields 

Running a transform

1. Navigate to Import → Import Sets.
2. Open an import set you want to transform. Make sure that the state is Loaded.
3. Click Transform.

As a result, the toast message Import is completed appears. Imported data will be transferred into the target table.

Transform sequence

The scheme below shows the sequence of events triggered by the transformation: 

Image Added

1. The sequence begins with the onStarttransform script. It will be executed at the start of the transformation before any source row is read.
2. The field map script takes the record object of the Import Set Row table as an argument and returns the value to put into the Target Field.
3. The transform map script transforms field values from the source row to the target row.
4. The onBefore transform script is executed before the source row is transformed into the target row. 
5. Between the execution of onBefore and onAfter scripts, the target record is inserted or updated.
6. The onAfter transform script runs when the source row has been transformed into the target row.
7. The onComplete transform script is executed when all source rows are transformed.
   

Transform map is a set of field maps. In this set of field maps, the correlations between fields in an import set table and fields in a target table are specified.

Every import operation requires at least one transform map which specifies the relationships between the import set table and the target table.

To create a transform map, please complete the steps below:

1. Click on the View Transform Map UI action located on the import source form you are configuring.
2. In the info message appeared, follow the link Create Transform Map.
3. Fill in the fields in the form appeared.
4. Click Save or Save and Exit to apply changes.

Transform Maps field description

Select this checkbox to display the Script field, where you can define the transform script.

Transform map script

Transform map script allows you to customize import operations using a JS-scripts written using a SimpleOne Server-Side API. 

Transform Script field description

Specify the script type to occur:

• onComplete – this script runs at the end of the transformation.
• onStart – this script runs at the start of the transformation.
• onAfter – this script runs after the source row is transformed into the target row.
• onBefore – this script runs before the source row is transformed into the target row.

This field specifies the order of transform scripts. Fill in this field with an integer number. Scripts will be sorted in the descending order.

Field maps are used to define correlation between fields in an import set table and fields in the target table by determining the values from the source table to be added to the target table.

To create a field map, please complete the steps below:

1. Navigate to Import → Transform Maps.
2. Open a transform map you want to configure.
3. Click Create Field Maps UI action.
4. The Field Maps widget appears (see screenshot in the table below).
5. Configure field mapping within current transform process.
6. Click Set to save changes or Cancel to discard changes.

Field map fields description

If this option is active within the transform process, then the engine checks for values in the Target table field whether they are equal to the Import set table field value. 

If values are equal, then the record in the Target table is updated; otherwise, a new record is created.

Insert a script to determine a function that takes the record object of the Import Set table as an argument and returns the value to put into the Target Field.

This field appears when the Use Script checkbox is selected.

Running a transform