1. General

Importing data means bringing information from an external source, like a file or another system, into Workplace Management. The process includes preparing the data to match the applications needs, uploading it, checking for mistakes, and saving it in the system. Once imported, the data can be used for tasks like processes, reporting or analysis. It’s a way to make sure all your information is in one place and ready to use.

2. Technical background information

In Workplace Management their are default imports available for all relevant (master) data objects. An import (or the objects technical term ‘FtpConnector’) can be used to import and export data (periodically) in bulk. This article focuses on manually importing (master) data for the customer via default available imports. Other options like importing data periodically from a SFTP location is not described in this article.

An import consists of one or more mappings. A mapping (or the objects technical term 'FieldMap') consist of the object to be imported and the mapping between the import files column headers and the corresponding field in Workplace Management. Each mapping is related to only one object.

For example:

The following objects are currently relevant for the ‘own employees and users’ import:

Object Person: Personal information like first- and last name
Object Contact: Contact information like phone number and email address
Object SystemUser: System user information like the username
Object SystemGroupContact: Authorization information like the specific access rights the system user should have

So according to the above, the default import 'own employees and users' will have 4 mappings.

Depending on the import, there could be 1 mapping or 10 mappings linked to the import. Each mapping imports a part of the applicable object(s).

More information about the settings of the import and linked mappings will be applicable when customizing, see: /wiki/spaces/KB/pages/958562341.

3. Available default imports

In Workplace Management, the default available imports can be used to import (master) data in bulk. This data can be used in all relevant modules, used by the customer. For example, the building and area data is used in the modules ‘Reservations’ and ‘Requests’.

Depending on which modules the customer uses, the corresponding imports become automatically available. Via the module activation of the desired module, all relevant default imports are directly shown within the module activation. All (generated) default imports can also be found via the administrators startboard.

From the 'Default imports' menu on the administrators startboard all activated default imports can be found. From this overview, the imports can be deleted and regenerated. When regenerating a default import, it will always fetch the latest version of the import.

Regenerating a default import does only work, if the relevant (old) import is deleted first.

Regenerating an import will copy the latest version of the import template and mappings from the baseline to the customers environment. This way the template will always correspond with the import on the customer environment and any changes done on the baseline will not “break“ the import for the customer.

Imports can only be deleted by partner users.

Via the 'Email import templates for selected items' the applicable template files can be send to the user. More on the templates explained below.

When opening an import, more information is directly shown on the ‘General’ page. The ‘Details' tab is only visible for level 3 administrators. On this tab, more details of the import and more technical settings are visible. The 'Log’ tab shows when the import has been executed.

4. Templates

Via the button 'Download template', the applicable template is directly downloaded to your computer. This file is an Excel file with multiple sheets. The import template includes a sheet with instructions, one or more sheets to fill in the data to be imported and possibly more sheets to enter client specific details like for example. custom area categories.

Via the 'Default imports' overview on the administrators startboard, it is possible to directly email the import templates of the selected imports to yourself. This email can then be forwarded to the customer, if desired.

More information on how to fil in the template, see: How to use the import templates.

An import template or various mappings can be updated after a Workplace Management release. Make sure to regenerate the imports after a release, before sending it to the customer, to prevent sending an old import template, which might miss new mappings.

5. Importing data

The import templates are .XLSX files, which are send to the customer to fill in all relevant (master) data. Once the customer is done filling in the import file(s), the customer sends back the files to the implementation consultant to import the data.

Before the data can be imported, the implementation consultant:

opens the file(s) and confirmed all required data filled in (e.g. name of the building)
opens the file(s) and confirmed all data filled in is according to the instructions (e.g. selected the correct option from a drop-down list)
verifies that no relevant columns have been deleted
saves the sheet with data to be imported as a .CSV file (for all sheets that contain data to be imported)
verifies the field delimiter in the CSV file corresponds with the field delimiter of the user importing the data

If the import template file is filled in incorrectly, the implementation consultant needs to reach out to the customer to discuss the incorrect filled in data.

If the file is filled in correctly by the customer, the process can continue. Via the 'Upload import file' button, the import can be executed.

More information about the file to be uploaded, is shown on the top of the screen:

The .CSV file to be imported, can be dragged and dropped in the dedicated location (grey block), or the file can be searched via the 'Selected files' option.

As soon as the file is dropped, the message is shown that the import is executed in the background. A background task is executed (as it states) in the background, while the user can continue with other things in the meantime.

Via the icon next to the username in the top right corner of the screen, any yet to start, ongoing and finished imports (background tasks) can be found:

Once the import is finished, the log files are generated and shown in the include 'Generated import documents (last 24 hours)'. This include shows log files which show the correctly imported data and possibly errors that might occurred. More information about these log files in the next chapter.

6. Log files for validation and debugging

By default the imports log files, generated after importing data, are shown via the include 'Generated import documents (last 24 hours)'. As described, the documents shown here are not older than 24 hours.

Documents generated in the last 24 hours are shown by default. Older objects can still be found via the document search option found as an icon on the top right corner of the screen.

After the import is completed, one or more log files are shown:

The file which was uploaded
A log file which indicates per line what has been imported
A log file with all errors

If only the first 2 files are shown, that means that no errors occurred and the data was imported correctly, or there was nothing to update in already imported data.

If the error file is also shown, then the import was (partly) unsuccessful. With this file, the debugging process can begin to see what is the reason the errors occurred. Below an overview of the most common error/warning messages.

6.1 Most common error messages

Message

Possible cause

Solution

Field does not exist

Imported an incorrect file (XLSX instead of CSV). The error is shown for every column in the import file.
The header of the column in the import file does not correspond with the name in the import. For example, in the import file the header of the column is ‘Streetname', but the import expects the header 'Street’
A column in the import file is deleted, but the import expects the header of the column to be present

Import the correct file type (CSV)
Make sure the column header in the import file corresponds with the import
“Undelete“ the column or remove it from the import in Workplace Management

Warning cannot find referenced object

An (already existing) object, which needs to be linked to the imported object, cannot be found.

When importing a building, the building owner (contact) can be linked via a unique identifier. If the unique identifier entered in the import file does not correspond to any (contact) object, the (contact) object cannot be found. This is considered a non-blocking warning.

Enter the correct identifier of the object to be linked in the import file
If the object to be linked does not exist yet, import this object first
Manually link the correct object

Creating or looking up an object for this key combination has failed

An (already existing) object, which needs to be linked to the imported object, cannot be found and is also part of the unique key of the object to import.

When importing an area in a building, the area name/number and the building would be the unique key to import the area. If the building does not exist yet or cannot be found, the object cannot be created because a part of the key is missing.

Make sure the object which is part of the key is imported prior to the import, where the object is part of the key

Example error log 1:

There is no language with the identifier 'ent', so it could not be linked to the imported organization
There is no address with the combined identifier address: Groningensingel, nr: 11, addressLetter: C, postalReference: 6836 EA, so it could not be linked to the imported organization
There is no organization with the identifier ‘ORGANIZATION-7’ to be linked as the parent organization of the imported department

The above errors are considered warnings. The object itself is imported, but specific fields (e.g. language, address and parent organization) could not be set.

Example error log 2:

The area import is executed before the building import. When importing the areas, the corresponding building (which is part of the key to import areas) cannot be found.

This is considered an error, which results in the areas not being imported.