# Imports ## Overview The imports register enables data to be imported into Registers and Assets. System Administrators can [run](https://docs.cw.crisisworks.com/system-administration/reporting/running-reports) imports for [Register Items](#register-items) and [Assets](#assets). The System administrator configures the [settings](#imports-settings) including the [parsing rules](#parsing-rules) and once the import file has been uploaded and saved, can view the [result](#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. {% hint style="info" %} 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](https://docs.cw.crisisworks.com/system-administration/configuring-the-system/imports/register-items/contacts-import). {% endhint %} #### Import formats Most (but not all) are imported in Comma Separated Value (CSV) format. Some asset imports also accept ZIP files containing other formats. {% hint style="info" %} 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. {% endhint %} 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](https://docs.cw.crisisworks.com/system-administration/configuring-the-system/..#system-administration-positions). You can find the *Imports* register under **System Administration** **> Imports**. ### Register Items Register Items is used to add to or update the respective [registers](https://docs.cw.crisisworks.com/concepts-and-fundamentals/on-a-computer/using-the-datagrid). Refer to the Register Items import page for more details on this option: {% content-ref url="imports/register-items" %} [register-items](https://docs.cw.crisisworks.com/system-administration/configuring-the-system/imports/register-items) {% endcontent-ref %} ### Assets Assets imports are used to add to or update the [Asset database](https://docs.cw.crisisworks.com/concepts-and-fundamentals/concepts-and-fundamentals#register-assets-and-resources). 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: {% content-ref url="imports/assets" %} [assets](https://docs.cw.crisisworks.com/system-administration/configuring-the-system/imports/assets) {% endcontent-ref %} ### Workflow 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. | Status | Icon | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | 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](https://docs.cw.crisisworks.com/concepts-and-fundamentals/on-a-computer/using-the-datagrid#data-grid-view). {% hint style="info" %} 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. {% endhint %} To view an existing Import: 1. Navigate to the Imports register datagrid. 2. Locate the item you wish to view. The register includes additional filters for Workflow Status (New; Queued; Running; Finished; Failed; Cancelled) 3. Open the item using the ID 4. To return to the Datagrid use the Back button

View of sample Imports register including the status of imports (finished or failed)

## Settings | Left Column | Right Column | | --------------------------------- | ------------------------------------------- | | [Record Notes](#record-notes) | [Workflow](#workflow-1) | | [General](#general) | [Import Instructions](#import-instructions) | | [Categorisation](#categorisation) | [Activity](#activity) | | [Advanced](#advanced) | | | [Result](#result) | | ### Record Notes When editing, record notes in the [rich text field](https://docs.cw.crisisworks.com/concepts-and-fundamentals/on-a-computer/using-the-datagrid/editing-items#rich-text-fields) as you make changes which will appear in the Activity log. Refer to: [Recording Notes](https://docs.cw.crisisworks.com/concepts-and-fundamentals/on-a-computer/using-the-datagrid/editing-items#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.

Match rule field

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.

Selecting a Record matching strategy to update existing items

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\ ![](https://3923904090-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNy7IznbrPLUq6GJDDQDk%2Fuploads%2FUy6oa3GhVPFaW1HPRcM9%2Fimage.png?alt=media\&token=52e34a74-d50f-4e0b-805b-635ae595b06a) * **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.

Categorisation section options

#### Event ID {% hint style="info" %} Assets don't link to events, therefore if you have selected Assets, the Event ID option will not be available. {% endhint %} 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](https://docs.cw.crisisworks.com/system-administration/managing-events). 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](https://docs.cw.crisisworks.com/concepts-and-fundamentals/on-a-computer/using-the-datagrid/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](https://docs.cw.crisisworks.com/concepts-and-fundamentals/concepts-and-fundamentals#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: 1. that all required fields for the import type exist in the import file 2. 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.

Advanced section

### 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.

Workflow section in Edit mode

**Status** registers the current [Workflow](#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.

Import Instructions section and Import Field Mappings

### Activity Refer to: [Viewing Items: Activity](https://docs.cw.crisisworks.com/concepts-and-fundamentals/on-a-computer/using-the-datagrid/viewing-items#activity) ## Editing Imports Imports can be edited from the datagrid. Editing an import is usually for re-running (resubmitting) it. 1. Navigate to the Imports register 2. Locate the Import you wish to edit by using the Edit button 3. Make the necessary changes to the [Settings](#imports-settings) 4. Save ## Running an Import To run an Import: 1. Use the [New Item button](https://docs.cw.crisisworks.com/concepts-and-fundamentals/on-a-computer/using-the-datagrid/adding-items) for New Import 2. Select a **Type** and **Parsing Rule** and use the Add File button to **Import File** 3. Make any other configurations changes necessary in the [Settings](#imports-settings) 4. 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. {% hint style="warning" %} 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. {% endhint %}