Imports
This section outlines the imports system which enables data to be imported into registers.
Overview
The imports register enables data to be imported into Registers and Assets.
System Administrators can run imports for Register Items and Assets. The System administrator configures the settings including the parsing rules and once the import file has been uploaded and saved, can view the result.
The Import operates using a parser to map the fields to the database and insert them using a Parsing Rule. Each Parsing Rule also has a default method of updating the database.
It is important to select the correct Parsing Rule for the data you wish to import as your import may otherwise fail. It is also important to make sure that the data is in the correct format, including all of the required columns and that the columns are correctly named, otherwise your import may fail. For a guide on field mappings and expected formats, see Field Mappings and File Types.
Import formats
Most (but not all) are imported in Comma Separated Value (CSV) format. Some asset imports also accept ZIP files containing other formats.
If your import data file is in another format, such as Microsoft Excel, you will need to save or convert it to CSV or the specified file type prior to uploading it.
If you're updating or adding to an existing list of items you can also create a CSV file from existing data by exporting register items to a report first using the Export function from the datagrid. Files exported are compatible with the import system.
Clearing Field Data
If column headings or data is not specified in your import file for existing items, the existing data will usually not be removed.
If you wish to remove data for a field of an existing item, set the value "[NULL]" into the field in your import data. If this value is found in your import data, it will clear the existing value. For example if you wish to clear tags for the userId of "bob", simply type "[NULL]" in the Tags column of your data on Bob's record and all existing tags for Bob will be removed.
Access
To access the Imports register you will need to sign in with System Admin & Data Entry position.
You can find the Imports register under System Administration > Imports.
Register Items
Register Items is used to add to or update the respective registers.
Refer to the Register Items import page for more details on this option:
Register ItemsAssets
Assets imports are used to add to or update the Asset database. There are no registers for this, they are stored internally and can only be imported or reimported.
Refer to the Assets import page for more details on this option:
AssetsWorkflow
Imports use a similar workflow process to the Reports module in that they do not run instantly. They are first Queued, then Run before becoming either Finished or Failed.
New
The Import has been created but has not yet been run. You will rarely see this as most imports run automatically when created.
Queued
The report is scheduled to run but is waiting for other processes to run first
Running
The Import is in the process of running
Finished
Your data has been imported successfully.
Failed
Failed to run. Look at the logs to determine the reason/s. Correct and try again.
Cancelled
The import was cancelled while still queued or running.
Viewing Imports
Imports are listed in and searchable via the register Datagrid.
Imports only stay Active while they are being run. Most imports that have already been run will not show up under Active. Use the Totals filter or one of the Workflow filters (such as Finished) to find these.
To view an existing Import:
Navigate to the Imports register datagrid.
Locate the item you wish to view. The register includes additional filters for Workflow Status (New; Queued; Running; Finished; Failed; Cancelled)
Open the item using the ID
To return to the Datagrid use the Back button
Settings
Record Notes
When editing, record notes in the rich text field as you make changes which will appear in the Activity log.
Refer to: Recording Notes
General
Type
These options choose the type of Import. There are currently only two types: Register Items; and Assets.
Parsing Rules
The Parsing Rule setting is used to determine the Register/s the import is being run for and the method for updating the database. Consider this carefully to make sure you're importing your data into the correct register.
The default rule for all imports is Insert new records, update matching records (see below). You can override this method using the Override parser defaults checkbox.
To override the default and choose a rule for how to handle the import, select a Match Rule.
When your rule involves updating existing items, you'll be required to select a Record matching strategy (the exception is when you're not overriding the default rule in which case the system chooses one for you automatically). This can be an External ID, Record ID or Related Asset. This settings helps ensure that the existing items that need updating are properly identified.
The following rules are available depending on which parser you've selected (you can only use one):
Delete data and replace with import data - will delete all data in the register prior to importing data from your import file
Insert new records, update matching records - adds records, but also matches existing ones. To update existing items you must select a matching strategy. You can update existing items that are inactive by ticking the Include active records when matching box. By default these are ignored
Insert Only (do not update matching records) - adds items to your register without either deleting or updating existing items. Only use this if you are adding new items.
Update Only (do not insert non-matching records) - won't add any new records and only matches existing ones. To update existing items you must select a matching strategy. You can update existing items that are inactive by ticking the Include active records when matching box. By default these are ignored.
Categorisation
The Categorisation section gives you the option to associate an event, tag or region to the import.
Event ID
Assets don't link to events, therefore if you have selected Assets, the Event ID option will not be available.
To import your register items into a specific event, put the ID of the event in this field. You can find the ID in the Event register. Note that if you've already got an Event ID in your import file, that will be used instead.
If you want to specify different events for different items and the Import enables it, use the Event or Event ID in the import file. This will override what is specified here.
Tag
Refer to: Tagging items
To tag all the items, type your tag name into this field. This is not a standard tag selection field. If you're using an existing tag, you'll need to match its spelling exactly.
Region
Refer to: Sites and Regions
To associate your import with a specific region, select it from the list. Note that if you've already got a region specified in your import file, that will be used instead.
Advanced
Test Only lets you test your import before actually importing your data. To do this, place a tick in the Test Only checkbox. This will run through the import process and attempt to import each line of the import file but it won't actually save the records. Once the test import is complete it will return a status allowing you to view the details of any errors so you can fix up any issues before performing an actual import of your data.
Rollback on Error will roll back any changes if any errors with your import is detected. This includes any items where a match didn't succeed. Nothing will be inserted, updated or deleted. Do not use this setting unless necessary for testing or it may prevent your import from running.
Check that all columns in the input file match known attributes will analyse the import file and will alert you if there are any issues with your column headings. This option is useful as it will performs two checks:
that all required fields for the import type exist in the import file
if you have any additional fields in your import file that are not specified for this import type. This can be helpful to look at as it is possible that a field can be misspelt or not have the correct spaces or capitalisation required. If you get an error about the additional fields in your spreadsheet, you can either remove these additional fields from your input file or you can untick this option to ignored them.
Create separate audit records for each record will displayed on the Dashboard and audit history log for each item once the import is complete. Leave this field blank if you do not wish to add a comment for audit history. This is a useful option to enable.
Bypass state machine rules ignores restrictions that the system places to prevent updates to records where the status moves to an incompatible state. This option is generally not recommended.
Result
The Result section summarises the results of the import (how many records and the status of the import of each row in the file).
Workflow
Date Started and Date Completed are filled in automatically by the system.
Status registers the current Workflow state. Unlike other register items you cannot change the Status of an import. This is automatically set to New by the import process.
Import Instructions
The Import Instructions section contacts specific instructions.
Import Field Mappings
The Import Field Mappings section includes a table with instructions on the structure and contents of your import file in order for the import to work as expected.
Your import file must match these settings otherwise the import will fail.
The first column contains the field name. It is essential that your import file columns match these headings exactly. You can use the Copy icon 
to add this to your clipboard to paste.
The Description column includes specific instructions for the data expected in each row.
The Required Field indicates which fields must be present in your import file. These fields will say Yes.
Activity
Refer to: Viewing Items: Activity
Editing Imports
Imports can be edited from the datagrid. Editing an import is usually for re-running (resubmitting) it.
Navigate to the Imports register
Locate the Import you wish to edit by using the Edit button
Make the necessary changes to the Settings
Save
Running an Import
To run an Import:
Use the New Item button for New Import
Select a Type and Parsing Rule and use the Add File button to Import File
Make any other configurations changes necessary in the Settings
Use the Save button
This will initiate the workflow process. You can check the datagrid status or the Result section to see whether the import ran successfully.
Note that the imported items may not show up in the register straight away. Depending on the number of records it may take some time for the items to display and for the counters to update. Please be patient once the import has been run.
Last updated
Was this helpful?