Difficulty: expert

Have you read: What are imports and exports in Workplace?? The article below repeats some of the information from that article and goes into further depth.

Basics

The import functionality allows for a quick upload of large datasets into Workplace. By using import connector with import mappings, it is possible to specify in which data table the various data should be stored.

Default imports are available to import masterdata when setting up an environment. This allows for filling the environment with for example: contacts, properties, and areas. By default we use files in csv-format for our imports.

Where to find imports

Default imports are explained in detail in the articles that describe how to set up a new Workplace environment using the Solution Based Rollout Step by step implementation guides (SBR) || UNPUBLISHED. In these SBRs quick link are available. If you want to run an imports, other than in the context of an SBR, imports can be accessed by:

1. Pressing the Import button on the startBoard. Imports can also be accessed via the navigation menu: Configuration > Import.

2. Open the import connector by clicking on the “reference”.
   As it is easiest to understand imports by means of an example, in this article we guide you through the properties import: FMB-F-021. After clicking the reference this page will open:

3. If this import is not yet available in the list click: Generate default imports at the bottom of the import list. This will provide you with some general imports.

Importing data

To import data follow these steps:

1. Generate an import template by clicking “Generate import template”.

   • A file will be provided in the include at the bottom called Template import xxx.

   • To download the file click the download icon.

2. In theory we send out this excel file to the client and ask them to fill it in. But more on this later.

3. After receiving the file back from the client check if the data is complete and filled in correctly.

4. Now data save the file as CSV UTF-8.

   1. Tip for converting your .xlsx to CSV: open in import file in Excel > File > Export > Change file type > select 'CSV '> Save as.

5. Import the file by clicking import file.

6. Select file by clicking Select files.

7. Importing the files will continue in the background. When we click: Ok, we return to the import page.

8. In the right top corner the background task icon will show up, when clicking on it we can see the import status.

   1. Tip: if the background task does not appear refresh the page by clicking the Spacewell logo on the top left of the page (of click F5 to refresh your browser).

      

9. When the import finishes, you can find the results by clicking the document icon in the top right corner.

   

   • On the document page select Advanced Search.

   • In the field Dates: linked from/until fill in today’s date. (If we would search without filtering we would end up finding all documents that have been imported in this import connector)

10. Depending on the connector setting, you might find the following three document:

    1. (csv) file that you uploaded e.g. Files[]-Template import properties. The files are only saved when the import connector setting ‘Save documents = yes’.

    2. Processing log - e.g. FMB-F-021-[Manual upload]-import. This shows what if new record are created or existing record have been updated

    3. Processing errors - e.g. FMB-F-021-[Manual upload]-error. This file contain the errors that occurred.

       1. If the import file is filled in correctly and uploading in the correct format no errors will occur. When an error does occur it can be quite hard to find out that the exact problem of the import file is, below some tips and pointer are given on possible causes

Expand
title Import messages explained
General info The error message will always include the row of the import file on which the error occurred. An error is blocking issue resulting in a record not being created or updated. The whole import might be aborted. Warnings give information on an action that could not be completed. All other items will be imported as usual. Common error massage overview Message Possible cause Example of error message Error Field does not exist File imported in wrong file format, for example .xlsx instead of .csv This can be recognized also because all column of the import file will generate an error line. The import file was altered: a column header changed. For example the header ‘Street’ was changed to 'Streetname'. Only the altered column header will generate an error A column header was deleted from the import file. The deleted column header will generate an error files[]-Template import properties_test.csv: Error Row 1 - Address with Letter : Field does not exist: Street Warning cannot Cannot find referenced object When linking to an object field in an import we often use external references. If Workplace does not have an object with the external reference that was set in the csv file, the object can not be linked, thus generating a non-blocking warning. For example: we want to link a contact with externalReference=4343453 in the ownerContactId field of a property. However, no contact with this external reference exists. files[]-Template import properties_test.csv: Warning Row 3 - FMB Property : Warning cannot find referenced object: ownerContactId={externalReference=4343453} Warning Error the line is not imported Warning Creating or looking up an object for this key combination has failed When using key values Workplace will try to find an object using the key values. If there is no object containing these key values a warning will be shown. Examples Image Modified Image Modified

Import connectors

Connector mappings

The import we discussed in the previous steps seems to be designed to only import properties. This is not the case! Almost all imports that are available consist out of multiple import mappings. In this case we import property objects as well as the address object. So, for every object that we want to import a separate mapping is needed. However, this is not the only reason we use different mappings, we could also use one specific mapping to only set the hierarchy of an object, so for properties this could be the hierarchy within the imported properties.

• We can see this by navigating to the details tab.

  • Tip: if you do not see the details tab. First enable the ‘Addtional admin options’ in the personal setting of the user you are logged in with.

• Scroll to the bottom include: Mappings. Here we can see what mappings are being used within this connector.

Running a mapping instead of the import connector

We are able to run mappings separately, this can be useful when we only need to import one of them, or when we want to see more easily where errors occur. To run a mapping separately:

1. Open the import connector

2. Navigate to the details tab.

3. Select a mapping by clicking on the magnifying glass next to the mapping name.

4. Click import

5. Select your file

The import will then run and show the results on the page.

Connector settings

Only partner users can change these settings. We will go over some important settings in the table below. Hover over a setting in Workplace to see the help text of other settings.

The difference between an error and a warning in imports:

• Error: data could not be imported because an error occurred.

• Warning: data has been imported but there could be columns missing/links might not been found.

How is the import file mapped in Workplace?

When filling in the import files, there are a few things we need to keep in mind.

• Every import file has different fields that have to be filled in. What these fields are depends on the configuration of the mappings that are linked to the import connector.

• By opening a mapping we can see what object it concerns (field ‘Objects’) and what fields are involved ('Mapping' include).

• When looking at the ‘Address’ mapping mapping of the ‘FMB Property’ (open import connector > details tab > at the bottom of the page you can see/ open the mappings.) you will see a screen that looks somewhat like:

Columns in a mapping

See screenshot above.

• Order: determines in what order the mapping is handled.

• Name: the name here corresponds with one of the column header in the import file (xlsx/ csv).

• Type/ Field/ Lookup: these determine in which field in Workplace the imported value should be stored.

  • Example: look at line 80 of the screenshot above. With these setting, the value in the column ‘City’ of the import file will be stored in the field address.city (the object is Address ) in Workplace.

Key values

• The key values of a mapping are found in the column ‘Key’. The value ‘Yes’ means this field is a key value.

• Key values are mandatory fields for an import to work. Meaning, the import will not run properly when Key values are missing.

• Key values are used to determine if a new object needs to be created OR that an existing object is updated. To determine this, Workplace checks if an objects already exists that containing ALL the key values.
  How does this work? In the Address mapping (see screenshot above), the Street, Nr, and PostalCode are the key values. The values in the import file could for example be: Second Street, 55, 1234AB. The mapping will check if an address with these characteristics exist. What happens than:

  • If the the address exists, the the non-key values are updated.

  • If the address does not yet exist, a new address is created where the key and non-key values are stored.

By using key values we make sure we do not import a single address multiple times.

Automating an import or export

• It is also possible to set up imports to be executed periodically from an FTP server.

• Automated export can be set up to export date to: FTP servers and email.

Summary

Search