Import

The Import form is used to import new records or update existing records in AyaNova from a local import file.

More advanced import or synchronization requirements are supported through the AyaNova developers API.

Authorization Roles required

Many roles can select this object on other records where approriate. Editing or viewing this object in detail is only available to Users with the following roles:

Full access

• Business administration

Read only access

• Business administration - restricted

How to access Import

From the Administration navigation drawer select Import navigation item.

Importing

Checkmarking "Import new records" indicates you want to import unmatched records into AyaNova.

AyaNova will attempt to match the import records to existing records in the AyaNova database by comparing the unique key field identified in each objects import specifications.

Usually the key field will be the Name field but in some cases it may be another field that is the primary unique identifier for that record type.

The key field must match exactly; case and spelling matter.

If no existing record matches the key field then that record will be submitted to the business object type's create handler for validation and saving.

This is the exact same process used when you manually edit and save a form in AyaNova which ensures all business and validation rules are checked.

If no errors are found then the record is saved into the database and a success message is added to the results list displayed in the Import form once import has completed.

If errors are found during validation no save is made and the error message is added to the results list displayed in the Import form once import has completed.

When import has completed the import result list will show any errors or imported records and "Process completed".

Records not imported due to already being present will not show in the import result list.

Import items are automatically tagged

To make it easier to identify and if necessary mass delete imported records (for example if a mistake was found), imported records are automatically tagged with a unique time-stamped import tag. The time stamp is the same for that entire batch imported at once making them easy to identify.

The time stamp is created at the AyaNova server from the server's time zone so it may differ from the local time of the person doing the import if they are in a different time zone than the server.

The Tag format is zz-import-yyyyMMddHHmmss for example zz-import-20220619114532 indicating a record imported June 19th 2022 at 11:45am and 32 seconds.

The zz is prepended so that the import tag displays last in the list of existing tags.

You can easily remove the tag later if desired by using the bulk tagger extension delete tag option.

Updating

Checkmarking "Update existing records" indicates you want to update matched records in AyaNova.

AyaNova will attempt to match the records in the import file to existing records in the AyaNova database by comparing the unique key field identified in each objects import specifications.

Usually the key field will be the Name field but in some cases it may be another field that is the primary unique identifier for that record type.

The key field must match exactly; case and spelling matter.

If an existing record matches the key field then that record will be submitted to the business object type's update handler for updating then validation and saving.

This is the exact same process used when you manually edit and save a form in AyaNova which ensures all business and validation rules are checked.

All the field data provided in the import file will overwrite the matching field's current value in the database.

The key (usually Name) field can not be updated as it's used to match records.

Unlike the import process, updated records are not automatically tagged (the only way to undo an update is to restore from backup) however you can still see which records were updated if necessary by viewing the User history of the User who ran the update.

When update has completed the update result list will show any errors or updated records and "Process completed".

Records not updated due to not matching an existing record will not show in the update result list.

Partial record updates

There is often a need to only partially update existing records in specific fields.

AyaNova supports this by convention: only include fields in the import file that you want updated.

Any fields that should remain untouched must not be included in the import file.

For example if the requirement is to only update email addresses in Customers and leave all other fields unchanged, you would provide only the key field for matching (Name) and the EmailAddress fields in the import file.

All included fields are overwritten, so an empty or null field value in the import file will overwrite (remove) any data in the matching field in the existing record.

Make a backup first

We strongly recommend making a backup before bulk updating records in AyaNova.

Conflict

If a record is updated that is actively being edited by another User, the other user will not be able to save their edits because you have changed the record before they have had a chance to save it triggering a concurrency conflict.

For this reason we recommend co-ordinating with any other Users that may be affected before triggering a bulk update.

Undoing an update

The only way to undo an update is to restore the database from a backup.

Files

File types supported

You can import / update from either JSON or CSV files.

The AyaNova server only supports .json data; a .csv file is converted to json format first by the AyaNova web app before sending it to the AyaNova server for import.

Use .json if possible

If at all possible, we recommend using the .json format over the .csv format as .json can exactly match the structure of the objects in AyaNova and imports in one step and there is less possibility of mis-interpreting the type of data in each field.

CSV files need to be first imported and interpreted then mapped on to the .json format structure before sending to the server for import / update which is an extra step and could result in errors.

Import file format

Each supported object type that can be imported has it's import specification and examples documented individually, click through the objects listed below to see the import file specifications for each type.

Field names in .json or header row names in .csv files must match exactly in case and spelling the field names in each object type's import specification document.

Any other fields included will be removed by AyaNova before sending to the server for import.

CSV files must have a header row as the first row containing the specified field names. It's ok to omit any non-required fields.

The order of the fields in JSON or CSV is not important.

Dates and times

Dates and times in the input files are assumed to be in UTC / GMT time zone.

Tags in CSV files

Tags in a CSV file must be a quoted comma separated string of tags like this: "blue,red,white".

A single tag doesn't require the comma, for example: "blue".

Tags in the import file that do not conform to the AyaNova Tag format specification will be modified to fit within the specification.

CSV Header row

CSV files must have the specified field names in the header row.

CSV Parsing errors

When you select a .csv file to import the AyaNova web app will first attempt to convert it JSON format understood by the AyaNova server. If there are any errors when parsing in the CSV document they will be displayed in the results area of the import form indicating the line number in the csv file, and the error with that line.

To ensure the integrity of the data, import will not be attempted if ther are any csv parsing errors.

CSV parsing errors come from a 3rd party utility and will be displayed in the English language only.

JSON Parsing errors

If there is an issue with parsing the JSON file you may receive a Syntax error with further description:

"Expected double quoted property name" syntax error

This error is due to a trailing comma in the JSON structure, either in an individual record after the last field in that record or in the entire array of objects after the last object:

Correct comma format:

Invalid comma format:

Maximum file size

The actual limit on how many records can be imported / updated at once depends on many different things from individual browser limits, memory available, intermediate networking device and server configuration etc making it impossible to specify a limit.

As a rough guideline we recommend keeping the import file under 300kb in size to be safe.

Can I import an AyaNova export file?

JSON export files created with the Export extension can be imported into AyaNova however not all fields exported are importable, any fields not found in the import specifications will be ignored.

The export extension exports many more object types and includes more fields than the import process supports.

When in doubt about a field format

If you're not sure how to specify a particular field, try exporting a record first using the Export extension, this shows the format that each field should be in (other than Tags in csv files).

Import specifications

The following listed types of AyaNova objects can currently be imported / updated in AyaNova.

Types not listed may be added in future; for needs beyond what is provided with the import feature, you can always import any data now into AyaNova via software written using the AyaNova developers API.

Each object type listed below links to a page showing the specific format required for the import file and special notes about importing that specific object:

• Customers

• Head offices

• Parts

• Part assemblies

• Part inventory

• Part warhouses

• Projects

• Service rates

• Task groups

• Travel rates

• Units

• Unit models

• Vendors

Import order when starting with a new AyaNova database

If you are getting started with AyaNova and importing your own data from other sources, several of the objects require other objects to already be present in the AyaNova database first.

• import Vendors before importing Parts, Unit Models or Units
• import Unit Models before importing Units
• import Part Warehouses before importing Part Inventory Transactions
• import Parts before importing Part Inventory Transactions or Part Assemblies
• import Head Offices before importing Customers

Import form

Type

AyaNova object types that can currently be imported / updated.

Here you select the desired destination object type to be imported or updated.

If a type of object is not on this list it is not importable through this import form however any object that can be created or edited in AyaNova can be imported via the AyaNova developers API.

Other controls on this form are hidden until a type is selected.

File to import

Use this upload control to select a supported file type for import / update. Once a supported file type has been selected the Import button will appear below this control and is used to start the import / update process.

Import new records

Check this option if you want AyaNova to import any records that are not found in the existing AyaNova dabase.

(can be used with update option)

Update existing records

Check this option to tell AyaNova to update existing records that match with the import file.

(can be used with import option)

Results area

The bottom part of this form will display the results of the import / update operation.

Items successfully processed will display with a green check box to their left.

Items that could not be processed will display with a red cross mark to their left and an explanation beneath them.

CSV import file problems will also display in this area.