Imports & Exports

The Import

Why use Imports?

In addition to adding them manually, new templates, devices, private customers, corporate customers and employees can be imported onto your platform by uploading CSV files (CSV = Comma Separated Values). This provides the following advantages:

  • Multiple entities can be added and/or updated at the same time.
  • Existing data from CRM or ERP systems does not have to be re-entered manually.

Possible Use Cases:

  • Migrating existing data from other systems to the platform.
  • Adding large numbers of new entities on a regular basis.
  • Updating multiple entities at the same time.

Import Modes

Depending on the desired result of the import - creation and/or update - you need to select the appropriate import mode. For each mode, there are a few details that you need to keep in mind when preparing your import data.

Choose Import Mode

Create All

  • Only for creating new entities
  • Depending on the type of entity, there are different mandatory fields which require data input (see tables below)
  • For each correctly formatted row in the imported CSV file, a new entity is created
  • Tip: You can create new devices and new codes, which are automatically paired with each other, in just one import by entering _createNew in the objectTag column.

Create & Update

  • For creating new entities and updating existing entities at the same time
  • An identifying field is required to distinguish between new and existing entities
  • A new entity is created for each correctly formatted row in the imported CSV file that does not have an entry in the identifying field
  • Warning: If the same CVS file is used for another import without the IDs of the newly created entities being entered in it, for each row without ID, entities will be created again (picture)!

Update only

  • Only for updating existing entities
  • An identifying field is required to distinguish between new and existing entities
  • Existing entities will be updated, and new ones will be ignored, if the "Skip Errors" option was selected (picture)

Import Settings

Skip Errors
You can set the system to continue the import even if errors are detected. After the import is complete, an import receipt will be downloaded automatically. In the import receipt, problem descriptions will be given next to rows with incorrect content.

Empty Fields (for updates only)
You can have the system remove content from existing entities. To do this, enter the text NULL_TOKEN in the input fields that you want to empty and activate the checkbox (picture)(picture).

Step-by-Step Instructions

  1. Select Templates / Devices / Customers / My Company from the side menu
  2. Click +ADD TEMPLATE / +ADD DEVICE / +ADD CUSTOMER / +ADD EMPLOYEE
  3. Click +IMPORT / +IMPORT CORPORATE CUSTOMER / +IMPORT PRIVATE CUSTOMER / +IMPORT TEAM MAPPINGS
  4. Click UPLOAD CSV and select a CSV file, or drag & drop it into the text field
  5. Review the data to make sure it has been read correctly
  6. Click NEXT
  7. Choose an import mode and the desired import settings
  8. Click +START IMPORT
NOTE

Depending on the number of entities on your list, the import may take up to 10 minutes. After the import is complete, an import receipt will be downloaded automatically. The import receipt contains an overview of the imported data, and if errors were found, problem descriptions are given next to rows that contain incorrect content.
The number of entities that can be created or updated per import is limited to 5000.

CSV File Formatting

It is important that your import files are formatted according to the specifications, otherwise your data cannot be imported. A specific file format is required for each type of entity (Templates, Devices, Corporate Customers, Private Customers, Employees).

TIP

Creation: Download a sample file and adapt it to your needs.
Update: Export a list and make your changes in it.

Templates

Sample file download:

Example (EN+DE):
Input Data in Excel (picture)
Result after Import (picture)(picture)

Column TitleInput Data
Example
Corresponding Input Field
id
Identifying field for updates
ID of the template (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
ID
title.XX
Required for creation
MicrowaveTitle
manufacturer.XX Generic Inc.Manufacturer
model.XX MW 3000Model / Type
description.XX For defrosting and heating foodDescription
additionalData.XX Article No.: 11223344 Additional Information
relatedDepartments.X (X = 0 - ∞)
0 = 1st department
1 = 2nd department
etc.
ID of an existing department (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
Related Departments
serviceProviderName.XXSample Inc.Text next to the logo (picture)
useServiceProviderNameFALSE
(Note: TRUE = Show; FALSE = Hide)
Show / Hide the text next to the logo
useServiceProviderLogoSpacingTRUE
(Note: TRUE = add space; FALSE = no extra space)
Logo Spacing
Add extra space around the logo
serviceProviderColor#e47a3d
HEX color code
Note: Must be 3, 6, or 8 digits long and contain only digits and the letters a–f.
Main Color
serviceProviderTopBarBackgroundColor#ffffff
HEX color code
Note: Must be 3, 6, or 8 digits long and contain only digits and the letters a–f.
Topbar Color
serviceProviderTopBarControlsColor#000000
HEX color code
Note: Must be 3, 6, or 8 digits long and contain only digits and the letters a–f.
Topbar Contrast Color
serviceProviderWelcomeText.XXHi there! I'm your digital Assistant. How may I help you? Main Menu Title
serviceProviderWelcomeTitle.XX---Currently not available

Note: XX = Insert a language tag in BCP47 format

How to update Templates (Suggestion)

1. Use the filters to reduce the list of templates to those you want to update
2. Export the list (select only the columns you need and export the list in machine-readable format) (picture)
Note: "id" is required as identifying field
3. Edit the exported CSV file and enter your changes
4. Import the CSV file

Devices

Sample file download:

Example (EN+DE):
Input Data in Excel (picture)(picture)
Result after Import (picture)

Column TitleInput Data
Example
Corresponding Input Field
id
Identifying field for updates
ID of the device (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
ID
template
Required for creation
ID of an existing template (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
868fddc9-6318-4e5d-a825-33d364f204bd
Template
customerID of an existing customer (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
7f89fa2e-1c40-4951-aed1-332e444344ce

or

Customer-ID of an existing customer (picture)
12345-XYZ
Customer
objectTag
Identifying field for updates
ID of an existing unpaired code (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
59114cb5-15f7-4099-b0fd-95a9ee30e47a

or

Short-ID of an existing unpaired code (picture)
xxxxxxxxxxxxxx (14 digits)
ca469655ded046

or

_createNew to have the system create a new code and pair it with the new device
Code
title.XX
Note: Enter only if different from the template
MicrowaveTitle
manufacturer.XX
Note: Enter only if different from the template
Generic Inc.Manufacturer
model.XX
Note: Enter only if different from the template
MW 3000Model / Type
description.XX
Note: Enter only if different from the template
For defrosting and heating foodDescription
additionalData.XX
Note: Enter only if different from the template
Article No.: 11223344Additional Information
serialNumber
Identifying field for updates
123-SSS-456Serial Number
serviceContract
Identifying field for updates
123-CCC-456Service Contract Number
location.validatedTRUE
(Note: TRUE = on; FALSE = off)
Address Validation on/off
location.latitude48.1186072Latitude
location.longitude11.6010435Longitude
location.countryDE (ISO-Alpha 2 Country Code)Country
location.stateBayernState
location.cityMünchenCity
location.zipCode81541ZIP
location.streetBalanstraßeStreet
location.streetNumber71aStreet Number
location.floor5Floor
location.roomKitchen 1Room
relatedDepartments.X (X = 0 - ∞)
0 = 1st department
1 = 2nd department
etc.
ID of an existing department (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
Related Departments
serviceProviderName.XX
Note: Enter only if different from the template
Sample Inc.Text next to the logo (picture)
useServiceProviderName
Note: Enter only if different from the template
FALSE
(Note: TRUE = on; FALSE = off)
Show / Hide the text next to the logo
useServiceProviderLogoSpacing
Note: Enter only if different from the template
TRUE
(Note: TRUE = add space; FALSE = no extra space)
Logo Spacing
Add extra space around the logo
serviceProviderColor
Note: Enter only if different from the template
#e47a3d
HEX color code
Note: Must be 3, 6, or 8 digits long and contain only digits and the letters a–f.
Main Color
serviceProviderTopBarBackgroundColor
Note: Enter only if different from the template
#ffffff
HEX color code
Note: Must be 3, 6, or 8 digits long and contain only digits and the letters a–f.
Topbar Color
serviceProviderTopBarControlsColor
Note: Enter only if different from the template
#000000
HEX color code
Note: Must be 3, 6, or 8 digits long and contain only digits and the letters a–f.
Topbar Contrast Color
serviceProviderWelcomeText.XX
Note: Enter only if different from the template
Hi there! I'm your digital Assistant. How may I help you? Main Menu Title
serviceProviderWelcomeTitle.XX---Currently not available

Note: XX = Insert a language tag in BCP47 format

NOTE

Enter only device-specific data that deviates from the template.

Remember: As long as there are no device-specific entries, input fields will inherit their data from the template. If an input field has a device-specific entry, it will no longer be synchronized with the template.

How to update Devices (Suggestion)

1. Use the filters to reduce the list of devices to those you want to update
2. Export the list (select only the columns you need and export the list in machine-readable format) (picture)
Note: Use "id", "objectTag", "serialNumber", or "serviceContract" as identifying field
3. Edit the exported CSV file and enter your changes
4. Import the CSV file

Corporate Customers

Sample file download:

Example (EN+DE):
Input Data in Text Editor (picture)
Result after Import (picture)

Column TitleInput Data
Example
Corresponding Input Field
id
Identifying field for updates
ID of the corporate customer (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
ID
organization.name
Required for creation
Identifying field for updates
Fantasy CorporationName
organization.address.validatedTRUE
(Note: TRUE = on; FALSE = off)
Address Validation on/off  
organization.address.streetMarienplatzStreet
organization.address.streetNumber1Street Number
organization.address.floor5Floor
organization.address.room1cRoom
organization.address.zipCode80331ZIP
organization.address.cityMünchenCity
organization.address.stateBayernState
organization.address.countryDE (ISO-Alpha 2 Country Code)Country
organization.address.latitude48.1373952Latitude
organization.address.longitude11.5747712Longitude
organization.phone.XX+4989 4445155Phone Number
organization.email.XXinfo@fantasy-corporation.comEmail Address
organization.website.XXhttps://fantasy-corporation.comWebsite
organization.info.XX"Supplier of fantasy materials, fabrics and colors."Additional Information
customerId
Identifying field for updates
12345-XYZCustomer-ID
info.XXContact person: Mrs. Fantasy (CEO)Notes
relatedDepartments.X (X = 0 - ∞)
0 = 1st department
1 = 2nd department
etc.
ID of an existing department (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
Related Departments

Note: XX = Insert a language tag in BCP47 format

How to update Corporate Customers (Suggestion)

1. Use the filters to reduce the list of customers to those you want to update
Important: Filter out private customers. You cannot update corporate and private customers at once.
2. Export the list (select only the columns you need and export the list in machine-readable format) (picture)
Note: Use "id", "organization.name", or "customerId" as identifying field
3. Edit the exported CSV file and enter your changes
4. Import the CSV file

Corporate Customers (with Departments)

Note:

In order for the system to recognize the connection between the headquarters and departments, the “customerId” of the headquarters must be entered in the “mainCustomer” field of its departments.

Linking HQs to Departments EN

Sample file download:

Example (EN+DE):
Input Data in Excel (picture)
Input Data in Text Editor (picture)
Result after Import (picture)

Column TitleInput Data
Example
Corresponding Input Field
id
Identifying field for updates
ID of the corporate customer (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
ID
organization.name
Required for creation
Identifying field for updates
Fantasy CorporationName
customerId
Required for creation (Headquarters)
Identifying field for updates
12345-XYZCustomer-ID
mainCustomer
Required for each Department for creation
12345-XYZCustomer-ID of the Headquarters
department.name
Required for creation
Department 1Name
department.address.validatedTRUE
(Note: TRUE = on; FALSE = off)
Address Validation on/off
department.address.streetSchloß NymphenburgStreet
department.address.streetNumber1Street Number
department.address.floor1Floor
department.address.room3Room
department.address.zipCode80638ZIP
department.address.cityMünchenCity
department.address.stateBayernState
department.address.countryDE (ISO-Alpha 2 Country Code)Country
department.address.latitude48.15827Latitude
department.address.longitude11.50337Longitude
department.phone.XX+4989 4445155Phone Number
department.email.XXinfo@fantasy-department1.comEmail Address
department.website.XXhttps://fantasy-corporation.comWebsite
department.info.XX"Department 1 of Fantasy Corporation"Additional Information
info.XXContact person: Mr. Experience (Department Manager)Notes
relatedDepartments.X (X = 0 - ∞)
0 = 1st department
1 = 2nd department
etc.
ID of an existing department (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
Related Departments

Note: XX = Insert a language tag in BCP47 format

How to update Corporate Customers (Suggestion)

1. Use the filters to reduce the list of customers to those you want to update
Important: Filter out private customers. You cannot update corporate and private customers at once.
2. Export the list (select only the columns you need and export the list in machine-readable format) (picture)
Note: Use "id", "organization.name", or "customerId" as identifying field
3. Edit the exported CSV file and enter your changes
4. Import the CSV file

Private Customers

Sample file download:

Example (EN+DE):
Input Data in Text Editor (picture)
Result after Import (picture)

Column TitleInput Data
Example
Corresponding Input Field
id
Identifying field for updates
ID of the private customer (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
ID
user.firstName
Required for creation
Identifying field for updates
MaryFirst Name
user.lastName
Required for creation
Identifying field for updates
FantasyLast Name
emailmary.fantasy@customer.comEmail Address
user.phone+1 234 45679Phone Number
user.address.validatedTRUE
(Note: TRUE = on; FALSE = off)
Address Validation on/off
user.address.streetSteiner StreetStreet
user.address.streetNumber710Street Number
user.address.floor1Floor
user.address.room2Room
user.address.zipCode94177ZIP
user.address.citySan FranciscoCity
user.address.stateCaliforniaState
user.address.countryUS (ISO-Alpha 2 Country Code)Country
user.address.latitude37.7760676Latitude
user.address.longitude-122.4327231Longitude
customerId
Identifying field for updates
12345-ABCCustomer-ID
info.XXElderly lady. Please treat particularly friendly.Notes
relatedDepartments.X (X = 0 - ∞)
0 = 1st department
1 = 2nd department
etc.
ID of an existing department (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
Related Departments

Note: XX = Insert a language tag in BCP47 format

How to update Private Customers (Suggestion)

1. Use the filters to reduce the list of customers to those you want to update
Important: Filter out corporate customers. You cannot update corporate and private customers at once.
2. Export the list (select only the columns you need and export the list in machine-readable format) (picture)
Note: Use "id", "user.firstName"+"user.lastName", or "customerId" as identifying field
3. Edit the exported CSV file and enter your changes
4. Import the CSV file

Customer Team Mappings

Sample file download:

Example (EN):
Input Data in Excel (picture)
Result after Import (picture)

Column TitleInput Data
Example
Corresponding Input Field
id
Identifying field for updates
ID of the customer team mapping
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
ID
customer
Required for creation
ID of an existing customer (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)

or

Customer ID of an existing customer (picture)
Note: Has to be unique!
Customer
metaTeam
Required for creation
ID of an existing meta team (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
Meta Team
team
Required for creation
ID of an existing team (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
Team

Employees

Sample file download:

Example (EN+DE):
Input Data in Text Editor (picture)
Result after Import (picture)

Column TitleInput Data
Example
Corresponding Input Field
id
Identifying field for updates
ID of the employee (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
ID
user.firstName
Required for creation
AnnaFirst Name
user.lastName
Required for creation
SchmidtLast Name
organizationRole
Required for creation
MEMBER
(Options: ADMINISTRATOR; MODERATOR; MEMBER)
Role
user.localede-DE (BCP47 format)Language
departments.X
(0 - ∞)
0 = 1st department
1 = 2nd department
etc.
ID of an existing department (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
8b043724-cae1-4d28-84f9-6d48eed51618
Department
address.validatedTRUE
(Note: TRUE = on; FALSE = off)
Address Validation on/off (Work)
address.streetBalanstraßeStreet (Work)
address.streetNumber71aStreet Number (Work)
address.floor5Floor (Work)
address.room1Room (Work)
address.stateBayernState (Work)
address.cityMünchenCity (Work)
address.zipCode81541ZIP (Work)
address.countryDE (ISO-Alpha 2 Country Code)Country (Work)
address.latitude48.1191091Latitude (Work)
address.longitude11.6009295Longitude (Work)
phone+49 123 4567890Phone Number (Work)
emailanna.schmidt@gc-deutschland.deEmail Address (Work)
user.address.validatedFALSE
(Note: TRUE = on; FALSE = off)
Address Validation on/off (Private)
user.address.streetBeispielstraßeStreet (Private)
user.address.streetNumber118Street Number (Private)
user.address.floor2Floor (Private)
user.address.room204Room (Private)
user.address.zipCode81541ZIP (Private)
user.address.cityMünchenCity (Private)
user.address.stateBayernState (Private)
user.address.countryDE (ISO-Alpha 2 Country Code)Country (Private)
user.address.latitude48.1145962Latitude (Private)
user.address.longitude11.6032822Longitude (Private)
user.phone+49 345 6789012Phone Number (Private)
user.dateOfBirth540558000000
UNIX epoch timestamp (in milliseconds)
Tip: Use a converter (external link)
Date of Birth
_inviteTRUE
(Note: TRUE = send invitation; FALSE = do not send invitation)
Invitation
How to update Employees (Suggestion)

1. Use the filters to reduce the list of employees to those you want to update
2. Export the list (select only the columns you need and export the list in machine-readable format) (picture)
Note: "id" is required as identifying field
3. Edit the exported CSV file and enter your changes
4. Import the CSV file

Codes

Sample file download:

Example (EN+DE):
Input Data in Excel (picture)
Result after Import (picture)

Column TitleInput Data
Example
Corresponding Input Field
shortId
Identifying field for updates
Short-ID of an existing code (picture)
xxxxxxxxxxxxxx
Short-ID
disabledFALSE
(Note: TRUE = disabled; FALSE = enabled)
Code Status
pin1234PIN
taggedObjectID of an existing device (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
Device
relatedDepartments.X (X = 0 - ∞)
0 = 1st department
1 = 2nd department
etc.
ID of an existing department (picture)
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (32 digits)
Related Departments
How to update Codes (Suggestion)

1. Use the filters to reduce the list of codes to those you want to update
2. Export the list (select only the columns you need and export the list in machine-readable format)
Note: "shortId" is required as identifying field
3. Edit the exported CSV file and enter your changes
4. Import the CSV file

Notes on Imports

Data Entry

  • Do not leave any spaces between your input and the separator (picture).
  • Do not leave empty rows in your CSV data (picture).
  • Do not put a comma at the end of a row (picture).
  • To add related departments to an entity, always start with relatedDepartments.0 and continue with .1,.2,.3, etc. until all departments are added. The same related departments don't have to be in the same column for each entity.
  • Text entries with commas need to be put in "quotation marks".
  • Websites must start with https:// .
  • If the column headings deviate from the specifications, these columns are ignored and their contents are not imported (picture).
  • The order of the columns is not relevant.

Languages

  • For the system to be able to assign the content correctly, language tags (BCP47 format) must be added to column headings, e.g. ".en-US", ".de-DE", ".es", ".fr".
  • To import content in multiple languages, create one column per language and input field (picture).
  • Tip: To find the correct language tag, log in to the platform, select a template, click EDIT, click one of the globes next to an input field, click on the plus sign to add a new translation, open the drop-down menu next to the input field and select the language you want. The language tag will now be displayed. (video)

Excel

Opening sample files with Microsoft Excel (Example based on Excel Version 16.49) (video):

  • Open a new Excel document ("Blank Workbook")
  • Select "Data" --> "Get Data" --> "From Text"
  • Select the sample file --> "Get Data"
  • In the Text Import Wizard, select "Delimited" and choose "UNICODE (UTF-8)" as the file origin --> "Next"
  • Select "Comma" as the delimiter --> "Next"
  • Highlight all columns in the preview and select "Text" as the data format --> "Finish"

For more information, visit the Microsoft Support website (link).

Saving CSV files:

  • Click on "Save As ..."
  • Choose "CSV UTF-8 (Comma delimited) (.csv)" as the file format.

Import Size

  • You can create or update up to 5000 entities per import.
  • If you want to create or update more than that, just do another import.

Common Mistakes

ProblemPossible CausePossible Solution
Accented characters (e.g., â, é, ö, ü) and other special characters such as "ß" are displayed incorrectly (picture).Import file not formatted correctly (picture).Use UTF-8 format only (picture).
Error messages next to empty input fields (picture).Whitespaces Remove all whitespaces from "empty" input fields.
Leading zeros are missing.
001234 --> 1234
Columns not formatted correctly. Set the column formatting to "Text" (picture).
Functions, e.g., address validation, aren't turned on/off as expected."TRUE"/"FALSE" has been translated into another language.Use "TRUE"/"FALSE" only.

The Export

Why use Exports?

Since the lists can be easily filtered and sorted on the platform, it is obvious that there is a need to be able to use these prepared lists outside the application, e.g. for reports. In addition, exports can be used to generate import files for updates.

  • Any list in the application can be exported via the download button (picture)
  • Exports can include a user-defined selection of columns or all columns (picture)
  • Exports can be created in a human-readable or machine-readable format (for re-import) (picture)

How to use Exports for Updates

  1. Go to the list of entities that you want to update (e.g., Devices)
  2. Filter the list so it will only show the entities you want to update (optional)
  3. Click the download button
  4. Select the columns that you want to update and download them as machine-readable values
  5. Open the CSV file and make your changes
  6. Verify that the list has an identifying field and that all your entities have an entry in it (see tables above)
  7. Verify that all column headers are still formatted correctly
  8. Save the file as a CSV file (UTF-8)
  9. Upload the CSV file to the platform (= Import)
Was this article helpful?
YesNo

Leave a Reply

Your email address will not be published. Required fields are marked *

eight − 8 =