Article 1 - General information
Title: Import of Objects - What is it about?
Release notes
This functionality is estimated to be included in a future release of Handyman Office
Short description
Import of Objects is an easy way to create numerous objects - sites and equipment's - in few steps, to an existing customer. It is a functionality for importing basic data with the help of a downloadable excel template file.
When the template is downloaded, you can start copying your data to import into this file.
Imported objects can be seen in Handyman service module after import
Who can import objects?
The functionality is available only for Handyman Office users with user rights to import basic data.
Where is it?
To start an import go the Configuration in the main menu, select Basic Data and then Import menu.
How to to do it step-by-step?
How to do it with words?
- Select Configuration, Basic Data and Import.
-
Then download the template file: 'Import of Assets' template.
-
If the customer does not exist, add as a new customer manually in Handyman Office.
-
Go back, browse your file and upload the completed template and click next in wizard.
-
Then import starts. You get a summary on what to import, "the file contains": counts of customers, sites, equipment and errors. Top ten errors with error messages are shown.
- If there is an error, uploading is not allowed, import button is disabled, proper information (top 10 errors) is given. In this case errors should be corrected and then start the import again.
-
When the import was done, in History tab there is a result summary and the downloadable excel file with the failed record list with error messages. If the import was successful without any errors, of course, no error file is there.
-
Errors need to be corrected.
-
Uploading the corrected file again is a new import.
How many objects can be imported at the same time?
There is a restriction regarding the maximum number of assets, as the excel template deals with 3000 rows. Consider then that, if only some object must be added, the process takes less time.
Uploading many objects can be a longer process.
Article 2 - Import of Objects template file
Title: Import of Objects - The template file
What is it about shortly?
Import of Objects is a functionality for importing basic data (sites and equipments) with the help of a downloadable excel template file.
When the template was downloaded, you can start copying your data to import into this file.
Where is the template file?
The functionality is in Handyman Web. https://hm-qa.gsgroup.io/
To start an import go the Configuration in the main menu, select Basic Data and then Import menu.
How to work with the template?
The template
It is an easy to use excel file with 2 worksheets.
You work with the first one, name as 'Import of objects template' completing data that you want to import. The second one named as 'Help' is a quick help to understand:
- filed names
- type (input) format - e.g. in Installed date field there must be a date written like 2023-01-01
- explanation - help for the field names
Number of columns, name of the fields cannot be changed.
Mandatory fields
Mandatory fields always must be completed. As a help, mandatory and optional fields are marked with a different color. You find help also in 'Help' worksheet in the template file.
-
orange: Mandatory for both sites and equipment.
-
green: Mandatory to sites.
-
blue: Mandatory to equipment.
-
white: Not mandatory, optional.
-
grey: Error message, not to be completed by the user.
Optional fields are not mandatory to complete, but recommended if you have information.
Some fields have a dropdown list. (e.g. Type, Installation origin, Status, Country code)
Sorting me button
'Sorting me' button can help to organize hierarchy levels, as sites must always come first than their equipment. If not, it results an error. If you use 'sorting me' button, please always save a copy of your file before sorting. It can happen that there are too many hierarchies to sort in the file and sorting cannot be handled accurately. There is no possibility to sort back in the template and get back your original file version!
How to enable macros
Find information here: https://support.microsoft.com/en-us/office/enable-or-disable-macros-in-microsoft-365-files-12b036fd-d140-4e74-b45e-16fed1a7e5c6
Field names in the template
| Field | Type/input format | Explanation |
| Customer (number) | Number | Customer number, must exist in Handyman. Only Handyman ID is allowed. |
| Site/equipment | Max of 20 characters | ID on the site/equipment to be imported |
| Name | Max of 255 characters | Name on the site/equipment to be imported |
| Type | Dropdown | Type of object, Site or equipment |
| Category (number) | Number | Id of the site/equipments category type, must exist in Handyman. Only Handyman ID is allowed. |
| Parent | Max of 20 characters | ID on parent site/equipment to which the imported site/equipment should belong. The parent must exist in Handyman. - Sites can be sub-sites to other sites - Sites cannot be a sub-site to an equipment - Equipment must belong to a site - Equipment can be sub-equipment to other equipment |
| Street name | Max of 40 characters | Site address - Name of the street |
| Street number | Max of 10 characters | Site address - Street number |
| Postal code | Max of 10 characters | Site address - Postal code |
| Postal area | Max of 30 characters | Site address - Postal area |
| Installation origin | Dropdown | Origin of the site/equipment |
| Status | Dropdown | - New - Installed - installed from before - Paused - site/equipment is in paused mode - Historical - the site/equipment is not active anymore |
| Installed date | YYYY-MM-DD | Date of the installation |
| Department (number) | Number | ID of the department to which site/equipment belongs. Only Handyman ID is allowed. |
| Responsible (number) | Number | ID of the person who will be responsible on site / equipment. The person must exist in Handyman. Only Handyman ID is allowed. |
| Preferred employee 1 (number) | Number | ID of preferred employee/technician 1 |
| Preferred employee 2 (number) | Number | ID of preferred employee/technician 2 |
| Last service date | YYYY-MM-DD | Date of last service |
| Last repair date | YYYY-MM-DD | Date of last repair |
| Manufacturing date | YYYY-MM-DD | Manufacturing date |
| Warranty start date | YYYY-MM-DD | Warranty start date |
| Warranty period | Number of month | Warranty period in number of months |
| Scanner ID | Max of 255 characters | Scanner ID |
| Travel distance | Number (00.00) | Travel distance, the usual is from the office to the department that may be set up as owner on the site / equipment, in km |
| Estimated traveltime | Number of minutes | Estimated travel time |
| Equipment placed | Max of 8000 characters | Equipment placed |
| Equipment serves | Max of 8000 characters | Equipment serves |
| Manufacturer | Max of 255 characters | Manufacturer |
| Model | Max of 255 characters | Model |
| Serial Number | Max of 255 characters | Serial number |
| Comment | Max characters | Comment |
| AddressName | Max of 60 characters | Site address - Name of the address |
| Latitude | Number | Latitude, WGS84 format (in millionths of degree) in 8 digits format without comma and dot. Eg.: N 47.480074 -> 47480074 |
| Longitude | Number | Longitude, WGS84 format (in millionths of degree) in 8 digits format without comma and dot. Eg.: E 19.02686 -> 19026860 |
| Address 2 | Max of 40 characters | Site address - Address 2 |
| Address 3 | Max of 50 characters | Site address - Address 3 |
| Address 4 | Max of 50 characters | Site address - Address 4 |
| Country | Dropdown | Site address - Country |
| Import message | Not to fill in this field | Error message can be read here after the import was done, errors can be filtered |
Article 3 - Errors in the import
Title: Import of Objects - Errors in the import
Double error check - what are these?
There is a formal check after you uploaded the file and the import was started.
There is a data check, when the real import is happening. At this point all data is in the right format, all mandatory cells are completed.
Formal check
After downloading the completed excel file containing all data that you want to import, there is a formal validation. It is more about checking the file format, not the data in the cells.
The first 10 errors are shown.
If there is an error, uploading is not allowed, import button is disabled, proper information (top 10) is given. So user can understand what was the problem during the formal validation and the error can be corrected.
Error codes can be:
-
There Is No Data: There is no data in mandatory field “x” in line “y”
-
Number Of Columns I s Not The Same As In The Template File: Number of columns is not the same as in the template file
-
Not The Same Columns As In The Template File: Not the same columns as in the template file
-
Not Number": “x” is not a number in line “y”
-
Not Correct Date Format": “x” is not in correct format (YYYY-MM-DD) in line “y”
-
Not Correct Select Value": “x” is not a correct value. Please select from selectlist in line
-
File Format Error: The file format is not .xls or .xlsx
-
Is Completed By The User: “x” is completed by the user. It is a system message, leave it empty in line “y”
-
Is Not A Number Or Written In A Wrong Way: “x” is not a number or it is written in a wrong way. Write it like: 10.55 in line “y”
-
Longer Than: “x” is longer than “y” characters in line “z"
Article 4 - History tab
Title: Import of Objects - History tab and error file
What happens with the import before you have a history log in History tab?
History tab
When the import was done, in History tab you find a result summary and a downloadable excel file with the failed record list with error messages.
If the import was successful without any errors, of course, no error file is there.
Error file
Failed items are marked red in the downloadable error file. Import error message helps you to understand what was the error, what field is missing or was not completed well.
They are to be corrected manually in the error file (accepted file formats: xls, xlsx, xlsm). To finish the process you should reupload the file again.
This functionality can be used to edit, add new data to already existing objects as well.
Result summary
In History tab there is a log on import history with information on:
-
File name: name of the file that was uploaded
-
Status of the import: in progress (pending), finished successfully, finished with errors
-
Date: date of import
-
User name: uploaded by
-
Summary: it is a system log, shows results what was successfully uploaded or failed
-
Errors: downloadable file with errors
Common errors
All items should have an external ID, an ID that is unique.
If mandatory fields are not completed, the item cannot be successfully uploaded.
If there is an error in any of the fields, the item cannot be successfully uploaded.
More errors in a row: only one error message is written in the error file by row. This is always the first one found in the row. In case of more errors by row, the import will fail again. But new error message will be in the error file.
Parent and child hierarchy: all equipment need to have a site. Sites can have sites and equipment can have equipment. In the template upper hierarchical levels should come before lower ones. If the equipment comes before the site in the template, the equipment cannot be uploaded as it does not have a site. So Site must come before its equipment.
Customer, Site with an address, Equipment Type, Equipment Category, Department Responsible Preferred technician must exist in Handyman.
Import stops at the first empty row, check if there is any.
Pictures, attachments
They are not allowed.