Skip to main content

Creating a new import

  1. Navigate to Settings > Import settings > Supporting Files imports > imports.

  2. On the overview page, click on the New import button.

  3. In the Import wizard, you start with step 1 'Target'.

    Select the Card type you want to import.

    Optionally, you can add a brief description.

  4. Move to step 2 'Source' and select the source type you want to import from.

    Available import sources

    remark

    We recommend using the CSV/XLSX import. To allow importing from a database you require extensive knowledge to secure the SQL server.

    If you don’t have a source file yet, use Download xlsx template to obtain an empty, pre-formatted file to fill.

    After connecting your import to a source, indicate the time zone of any date fields in the source file.

    note

    Import source files have a size limit of 35 MB.

    Optionally, you can filter on source data to only import the relevant part of the source.

  5. Move to step 3 'Field mapping' to map the listed source fields to their counterpart in TOPdesk. We explain the field mapping below.

  6. Move to step 4 'Import settings' .

    In the drop-down list Unique key, select which TOPdesk field you want to use as the unique key.

    remark

    The values of the field should be unique both in the source file and in TOPdesk, so that the source data can be linked to the correct TOPdesk card.

    If you don't have a field with unique values, you can combine two fields. Tick the Use a composite unique identifier checkbox and select which TOPdesk fields should be combined.

    Select if you want to enable the import to create new cards and/or update already existing cards.

    You also have the option to unarchive and update existing archived cards (deselecting it means the import will skip all archived cards).

    Additionally, choose how existing cards that aren't included in the source are processed. Should they be ignored or archived by the import?

    tip

    If you are importing separate batches of cards with a CSV or Excel file, it can be useful to make TOPdesk leading. You then do not have to include all cards of the relevant type in your source.

  7. Move to step 5 'Scheduling' , to indicate whether you want to run the import manually or automate it.

    Automated imports are based on automated file uploading, and will run each time a file with the set name is uploaded again. You find more information in the chapter Setting up the automated file upload.

  8. Move to step 6 'Preview', to find out, how many assets will be created and updated, and to assess any possible errors.

    remark

    What can you expect from the preview? Read more in The import preview explained.

  9. Click Save and run to import manually, or Save and activate to activate an automated import.

    warning

    Make sure you have created a backup before you run an import.

Field mapping explained

Map your source fields (on the right) to the corresponding fields in TOPdesk (displayed on the left) and determine how you want the import to fill these fields.

  • In the Mapping drop-down list you see the respective TOPdesk field.

    Select how you want the field to be filled:

    • Use a field from my source: In the drop-down list below, select the source field to import the value from.

      Furthermore, define which type of data the source field contains.

    • Define a fixed value: In the drop-down list below, select the value to insert into the TOPdesk field.

    • Transform values from source fields: Configure the settings below to convert your source data or combine values before importing into TOPdesk.

      The chapter Value transformations explains the setup.

note

All fields marked with an asterisk * need to be mapped before you can proceed to the next step. Make sure no fields with an asterisk under Select a TOPdesk field are left unmapped.

Optional settings

In the Optional settings of a mapped field (found by clicking on a mapped field), depending on the card and field type, various extra cases can be determined:

  • What to do with empty values in the source? Determine what happens to empty values in the source. You can let TOPdesk fill a default value, keep the field empty, or keep the value as it is in TOPdesk.

  • What to do with values that are missing in TOPdesk? When you import values for a drop-down list, you can determine what to do with unrecognised values. Available options are to skip the record, clear the field on the relevant card, or use a fallback value.

    For some fields, extra options are available to create new cards based on the source, and keep the values already filled in TOPdesk. For example, in the Supporting Files import, in case the country value doesn't exist in TOPdesk yet, the import either creates it or retrieves it from the archive.

  • What to do with values that are longer than # characters? Most text and number fields in TOPdesk have a maximum input length. If the source contains more characters, you can let TOPdesk skip the record, keep the values already in TOPdesk, or import only the first # characters.

  • Only import values for this field if it is empty in TOPdesk: Depending on the field you select, this checkbox, located at the bottom of the Optional Settings, allows you to specify that values in TOPdesk won't be overwritten by the import.

The import preview explained

After you completed the import configuration in the wizard, TOPdesk creates a preview of the import (step 6, 'Preview').

Cards to be created: TOPdesk didn't find an already existing card with the same unique key to match your import source. The card will be created by the import. [3]

Cards to be updated: TOPdesk found an already existing card with the same unique key to match your import source and detects it as an potential update.[3]

remark

Please note that TOPdesk creates the overview based on the data detected in your source. If the values in your source didn't change, they show as Cards to be updated even though they won't be actually be updated.

You can review the actual result after running the import.

Cards to be archived: TOPdesk didn't find a previously matched card in your import source. The card will be archived by the import.

remark

Cards that will be retrieved from the archive based on the import source are listed under Cards to be updated.

[3]

Errors: In some cases, TOPdesk can detect potential errors, such as issues with the unique key and source fields with incorrect values.

Available import targets in TOPdesk

The first step in the import wizard is defining the target in TOPdesk. In general, we use the term Card type to refer to the available targets, even though some are search lists, such as Budget holder:

  • Person

  • Person group

  • Operator

  • Operator group

  • Branch

  • Location

  • Department

  • Budget holder

Examples

Setting up SCIM provisioning with Microsoft Entra ID

SCIM (System for Cross-domain Identity Management)

SCIM lets you automate operator account management in TOPdesk. TOPdesk's SCIM implementation meets all mandatory requirements of the SCIM protocol, so it works with any compliant identity provider, such as Microsoft Entra ID. A SCIM integration can automatically create, update, and deactivate operator accounts based on changes in your identity provider. This helps keep user information up to date and reduces manual account administration.

Read SCIM for more information about SCIM in TOPdesk.

note

This topic walks you through an example configuration using Microsoft Entra ID, the identity provider most commonly used with TOPdesk. The steps for connecting a different SCIM-compliant identity provider will differ on the identity provider's side, but the SCIM source configuration in the TOPdesk import wizard stays the same.

Configuring Microsoft Entra ID

  1. Log into the Microsoft Entra admin center (external) and register a new application.

    step1-entra.jpg

  2. After clicking New application, click Create your own application.

  3. Enter a name and select Integrate any other application you don't find in the gallery (Non-gallery).

  4. Click Create.

  5. In the newly-created application, navigate to Manage > Provisioning.

  6. In the top menu, click New configuration, or in the Get started menu, click Connect your application.

  7. Next, fill in the Provisioning details (step 2 'Source' in the Import wizard of the SCIM import):

    • Authentication method;

    • Tenant URL;

    • Token endpoint;

    • Client identifier;

    • Client secret;

  8. Click Test connection, followed by Create.

  9. Navigate to Manage > Attribute mapping.

  10. Click and review the default attribute mappings under Provision Microsoft Entra ID Groups, then under Provision Microsoft Entra ID Users.

    Add, edit, or remove mappings as needed. In most cases, the default mappings are sufficient and can be further refined in TOPdesk.

    To import the manager relationship, make the following changes:

    1. Find the externalId mapping and click Edit.

    2. Replace the Source attribute mailNickName with objectId, then click OK. This stores the Entra user's objectId in the SCIM user's externalId field.

    3. Select Show advanced options, then click Edit attribute list for customappsso.

    4. Find the urn:ietf:params:scim:schemas:extension:enterprise:2.0:User attribute, change its type from Reference to String, and click Save.

      This stores the manager's objectId in the SCIM user's manager field instead of the SCIM ID of the manager.

  11. Navigate to Manage > Users and groups, then add the users and groups you want to provision.

  12. Under Provisioning, set Provisioning Status to On, and click Save.

    This starts the automatic provisioning.

    The first provisioning cycle may take some time to start and complete. After that, provisioning runs every 40 minutes.

    To import the manager relationship, configure the following field mappings in TOPdesk:

    1. Map the External ID (Import) target field to the External ID (externalId) source field.

    2. Map the Manager target field to the Manager (enterprise.manager.value) source field. For Which type of data does the source field 'manager' contain?, select External ID (Import).

Importing group membership of SCIM users

  1. Navigate to step 3 'Field mapping'.

  2. In the Select a TOPdesk field column, pick Person group (for person imports) or Operator group (for operator imports).

  3. For Which source value should be imported into 'Person group'/'Operator group'?, select the source field Groups (groups).

  4. For Which type of data does the source field contain?, select Name.

  5. Optionally, configure how the import should handle empty source fields and values missing in TOPdesk.

    tip

    To create missing person or operator groups in TOPdesk, select Create new linked cards in the optional settings

  6. Click Apply and proceed with the field mapping.

remark

The Groups (groups) field contains a newline-separated, alphabetically ordered list of the group names the SCIM user is a member of. If the user isn't a member of any group, the field is empty.

Microsoft Entra ID as Supporting Files import source

To let TOPdesk import data from Entra ID, register TOPdesk as an application in Entra ID, and enter the application data in TOPdesk.

Configuring Microsoft Entra ID

  1. In Microsoft's Application Registration Portal (external), register a new application for TOPdesk in Microsoft Entra.

    step1-entra.jpg

  2. Copy the Application (client) ID and the Directory (tenant) ID, and save them to paste into the respective fields in TOPdesk later.

    step2-entra.jpg

  3. In API permissions, click Add a permission.

    note

    If you are using Role-Based Access Control (RBAC) (external), you can skip the permission step and continue with the step: Step 7.

    step3-entra.jpg

  4. Select Microsoft Graph API and click Application permissions.

    step4-entra.png

  5. Select the GroupMember.Read.All and User.Read.All permissions and click Add permissions.

    step5-entra.jpg

  6. Grant admin consent to the newly added permission.

    step6-entra.jpg

  7. Navigate to Certificates & secrets and click New client secret.

    step7-entra.jpg

  8. Fill in a description and an expire date for the secret. Click Add and save the secret along with the client value and tenant ID.

    important

    When you copy the secret, use the value, not the secret ID. Please be aware that it can only be obtained once.

    step8-entra.jpg

  9. If you wish to authenticate with a client certificate , click Certificates and upload your certificate.

Connecting to your TOPdesk

  1. Log in to TOPdesk, and navigate to Settings > Import settings > Supporting Files imports > Imports.

  2. Create a new import or edit an existing one.

  3. In the import wizard, move to step 2 'Source' and select the source type Entra ID.

    A pop-up window opens where you enter your Entra ID credentials.

    tip

    Use the credentials you previously saved. Choose a relevant name for the connection and enter it in the Name field. Enter the Application (client) ID, the Directory (tenant) ID, and the Client secret in the designated fields.

    Next to using a client secret, TOPdesk also supports authentication with a client certificate. To use a client certificate, click Client certificate and select the desired certificate from the drop-down list. If your certificate is not listed, upload it first via Functional Settings > Certificates.

  4. Click Apply.

    TOPdesk confirms when you have successfully connected Microsoft Entra ID as an import source.

  5. After you successfully establish the connection to Microsoft Entra ID, continue with the field mapping (step 3).

Using directory extensions

If you use directory extensions to manage specific data with Entra ID, the supporting files import feature allows you to easily map this data to your TOPdesk fields.

  1. In the Field mapping, click on the TOPdesk field you wish to import your data to.

  2. Next, select the extension field from your source that contains the value for your TOPdesk field.

  3. Proceed with setting up the import configuration as usual.

remark

Furthermore, you can include directory extensions in your source data filters (step 2 'Source').

Read more about extensions in the Microsoft documentation (external).

Importing group membership of Entra users

  1. In the field mapping, click on the TOPdesk field Person group.

  2. Under Which source value should be imported into 'Person group'?, select the source field memberOfGroupsand configure the rest of the mapping.

    If the person group field is mapped, TOPdesk can automatically create missing person groups based on their names.

  3. Proceed with setting up the import configuration as usual.

remark

TOPdesk only imports groups in which users are direct members. Transitive memberships (i.e., membership through parent groups) are not included.

Setting up your local Active Directory as the Supporting Files import source

Follow these steps to synchronize your TOPdesk users with your local Active Directory.

preparation

TOPdesk needs to trust the certificate used by your AD server for secure LDAPS connections. The certificate must:

  • be currently valid;

  • be issued by a trusted Certificate Authority (CA), with the complete chain (including intermediates) trusted;

  • list the hostname used in the connection as a Alternative Name (SAN);

    wildcard certificates are allowed;

  • be presented by your AD server on TCP port 636;

Export the certificate from your AD server and upload the AD server's public certificate, or the CA certificate that issued it, via Functional Settings > Certificates.

  1. After selecting your target card type, navigate to step 2 'Source'.

  2. Select Active Directory as Source type.

  3. Click New Microsoft Active Directory connection.

  4. Enter a Name for the connection, the Hostname, a Port (if applicable) and the Username and Password.

    remark

    By default, TOPdesk uses the standard port 636. If this matches your set up, you don't need to change it.

  5. Click Save.

    tip

    TOPdesk securely stores your connection credentials under the name you chose and enables you to reuse the credentials for other imports.

  6. Apply filters to specify the Organisational Unit(s) or Group from which you wish to import users.

  7. Optionally, add filter rules on the source data.

  8. Save your progress and proceed to follow the remaining steps in the wizard.

Importing branches

In this topic, we cover the configuration of a Supporting Files import that manages your branch hierarchy in TOPdesk. The source in this case is CSV/XLSX.

remark

Depending on your settings, branches can have a customised name. Please note that this also affects the TOPdesk fields and the card type.

Preparing your source to import the branch hierarchy

  • The XLSX template contains the columns branchType and headBranch.

    For the branchType column, the fixed values Head branch, Independent branch and Has a head branch are available.

    In the headBranch column, the import expects the name of the head branch.

Setting up the branch import

  1. After selecting Branch as the target card type and successfully uploading a CSV/XLSX file, navigate to step 3 'Field mapping'.

  2. In the Select a TOPdesk field column, pick Branch Type.

  3. For Which source value should be imported into 'Branch type'?, select the source field that contains the branch type data.

    tip

    According to the preparation of the source file, this is the branchType field.

  4. For Which source value should be imported into 'Head branch'?, select the source field that contains the name of the head branch.

    tip

    This is only necessary, if this branch has a head branch. According to the preparation of the source file, this is the headBranch field.

  5. For ‘Which type of data does the source field contain?’, select Name.

    The import identifies the type of branch and assigns all branches with the branch type 'Has a head branch' to the branch name in the 'headBranch' field.

  6. Optionally, configure how the import should handle empty source fields and values missing in TOPdesk.

  7. In step 4 'Import settings', select the unique key and configure the remaining settings.

  8. Save the progress and run the import.

Assigning a list of operator groups to your operators

Preparing the import to assign a list of operator groups to your operators

Are the operator groups already existing and active in TOPdesk?

If so, in this case you can skip the first part of the preparation and move to step 2 'Preparing and importing a source file to assign a list of operator groups to your operators'.

  1. Preparing the source file to import the list of operator groups:

    1. The XLSX template for operator groups contains the column groupName. Fill in at least the name of the operator groups.

      Optionally, you can already link the groups to branches (branch), locations (location), budget holders (budgetHolder), etc.

    2. Navigate to the Import wizard.

    3. After selecting Operator group as the target card type and successfully uploading a CSV/XLSX file, navigate to step 3 'Field mapping'.

    4. In the Select a TOPdesk field column, pick Group Name.

    5. For Which source value should be imported into 'Group Name'?, select the corresponding source field (groupName).

    6. Optionally, continue with the field mapping and configure how the import should handle empty source fields and values missing in TOPdesk.

    7. In step 4 'Import settings', select the unique key (this should be Group Name) and configure the remaining settings.

    8. Save the progress and run the import.

  2. Preparing and importing a source file to assign a list of operator groups to your operators:

    1. If you don't have an existing source file, download the XLSX template for operators.

    2. Fill in the fields for the unique identifier of the operator card and the operator group(s) you wish to assign to the operator.

      In general, lastName and branch are mandatory.

      tip

      In Excel, add multiple values to the operatorgroup field by using ALT+ENTER to add rows in a cell.

      In a CSV file, use Enter to separate the values from each other.

    3. You can also import new operators and assign operator groups in one go.

      As usual, you need a unique identifier, such as employeeNumber.

    4. Verify that the columns in your source contain all the information you wish to import into TOPdesk and the operator groups are listed in the operatorgroup column for each operator.

    5. Navigate to the Import wizard.

    6. After selecting Operator as the target card type and successfully uploading a CSV/XLSX file, navigate to step 3 'Field mapping'.

    7. In the Select a TOPdesk field column, pick Operator Group.

    8. For Which source value should be imported into 'Operator Group'?, select the corresponding source field (operatorgroup).

    9. For Which type of data does the source field 'operatorgroup' contain?. This can be the group ID, name or email address.

    10. Optionally, continue with the field mapping and configure how the import should handle empty source fields and values missing in TOPdesk.

    11. In step 4 'Import settings', select the unique key (this could be Employee Number) and configure the remaining settings.

    12. Save the progress and run the import.

Assigning a list of person groups to your persons

Preparing the import to assign a list of person groups to your persons

Are the person groups already existing and active in TOPdesk?

If so, in this case you can skip the first part of the preparation and move to step 2 'Preparing and importing a source file to assign a list of person groups to your persons'.

  1. Preparing a source file to import the list of person groups:

    1. The XLSX template for person groups contains the column name. Fill in at least the name of the person groups.

      Optionally, you can already link the groups to branches (branch), locations (location), budget holders (budgetHolder), etc.

    2. Navigate to the Import wizard.

    3. After selecting Person group as the target card type and successfully uploading a CSV/XLSX file, navigate to step 3 'Field mapping'.

    4. In the Select a TOPdesk field column, pick Name.

    5. For Which source value should be imported into 'Name'?, select the corresponding source field (name).

    6. Optionally, continue with the field mapping and configure how the import should handle empty source fields and values missing in TOPdesk.

    7. In step 4 'Import settings', select the unique key (this should be Name) and configure the remaining settings.

    8. Save the progress and run the import.

  2. Preparing and importing a source file to assign a list of person groups to your persons:

    1. If you don't have an existing source file, download the XLSX template for persons.

    2. Fill in the fields for the unique identifier of the person card and the person group(s) you wish to assign to the person.

      In general, lastName and branch are mandatory.

      tip

      In Excel, add multiple values to the persongroup field by using ALT+ENTER to add rows in a cell.

      In a CSV file, use Enter to separate the values from each other.

    3. You can also import new persons and assign person groups in one go.

    4. Verify that the columns in your source contain all the information you wish to import into TOPdesk and the person groups are listed in the persongroup column for each person.

    5. Navigate to the Import wizard.

    6. After selecting Person as the target card type and successfully uploading a CSV/XLSX file, navigate to step 3 'Field mapping'.

    7. In the Select a TOPdesk field column, pick Person Group.

    8. For Which source value should be imported into 'Person Group'?, select the corresponding source field (personGroup).

    9. For Which type of data does the source field 'personGroup' contain?, you can have the group ID, name or email address.

    10. Optionally, continue with the field mapping and configure how the import should handle empty source fields and values missing in TOPdesk.

    11. In step 4 'Import settings', select the unique key (this could be Employee Number) and configure the remaining settings.

    12. Save the progress and run the import.

Importing persons with person groups with Entra ID

To import group memberships from Entra ID, follow the steps below while creating a new person import or adjusting an existing one:

  1. Navigate to step 3 'Field mapping'.

  2. In the Select a TOPdesk field column, pick Person group.

  3. For Which source value should be imported into 'Person group'?, select memberOfGroups.

  4. Proceed with selecting the data type and configuring the optional settings.

    tip

    To create missing person groups in TOPdesk, select Create new linked cards in the optional settings.

  5. Click Apply and proceed with the field mapping.

    TOPdesk automatically assigns all person groups to the respective person during the import.

Importing managers with Entra ID

The process for importing manager information requires some extra attention. When importing person cards with Entra ID as source:

  1. After successfully connecting to Entra ID as your import source, navigate to step 3 'Field mapping'.

  2. In the Select a TOPdesk field column, pick Manager.

  3. For Which source value should be imported into 'Manager'?, select a source field that contains unique data.

    tip

    We recommend manager employeeId, manager mail or manager userPrincipalName, as these tend to be unique.

  4. For ‘Which type of data does the source field contain?’, select the TOPdesk field that contains the information that you chose in the previous step.

    As an example: if you chose manager employeeId, picking Employee Number is generally the TOPdesk field that contains this information.

TOPdesk automatically recognizes which persons are managers and updates these card accordingly.

note

There are a variety of other data types you can choose from to uniquely identify the managers.

Importing images for Operators and Persons with Entra ID

Add images to your Operator and Person cards via Entra ID.

Follow the steps below while creating a new import or adjusting an existing import:

  1. Navigate to step 3 'Field mapping'.

  2. In the Select a TOPdesk field column, pick Image.

    Confirm that Image is selected in the mapping drop-down list, to import the profile image from Microsoft Entra ID.

    Tip

    Images are imported from the source in original size.

  3. Click Apply to continue.

    The image field is mapped to profile image in Entra ID.

Value transformations

Sometimes you might need to change the formatting of your source data before you can import it into TOPdesk.

With value transformations, you can easily change your data format to fit the import requirements within the import wizard.

Using value transformations

note

The FreeMarker documentation, especially the section on built-in strings, can help you with this.

  1. Navigate to Settings > Import settings > Supporting Files / Asset Management imports.

  2. Create a New import, or open an existing import by selecting it and clicking Edit.

    note

    Value transformations are a component of the Field mapping (step 3). You can configure each field mapping individually.

  3. In the Field mapping step, click on the desired TOPdesk field and select Transform values from source fields.

  4. The Transformation settings appear.

    1. In the field FreeMarker template, enter the expression for the transformation.

      Check out an example of a FreeMarker expression below.

    2. Click on Insert source value to see which source fields are available for your expression.

    3. To validate your FreeMarker expression, click on Preview.

      If the FreeMarker expression is correct, you see the first five transformed values.

      Otherwise, an error message guides you on how to fix it.

  5. Proceed with the further steps in the Import Wizard.

Remark

For some common use cases, you don't need to use value transformations. Instead, you can rely on the standard field mapping options.

tip

Use the standard field mapping options when possible, to ensure the best performance for your import.

Here are examples for use cases that don't require value transformation. You can configure most of these in the Optional settings.

  • Removal of whitespace characters before and after the source value. This is a standard functionality.

  • Inserting a fixed value into a TOPdesk field.

  • Using a fallback value in case of an empty source field.

  • Truncating the source value to the maximum number of characters allowed for the TOPdesk field.

A FreeMarker example for value transformations

TOPdesk uses the ISO 8601 date-time format: 2021-09-15T15:05:00Z

Your source uses a different date-time format: Wed Sep 15 2021 03:05:00 PM

This FreeMarker expression converts the date-time format:

<#-- Manually parse the date -->

<#assign parsedDate = _source["sourcefield name"]?datetime("EEE MMM dd yyyy hh:mm:ss a")>

<#-- Format the parsed date to ISO 8601 -->

<#assign isoDate = parsedDate?iso_utc>

<#-- Output the result -->

${isoDate}

In this example, we parsed the date manually. This isn't necessary for commonly used date-time formats.

tip

Check out the FreeMarker documentation for advice on how to use the ?datetime reference.

Other useful methods

  • ${_base64(“your-string-to-encode")}: Encodes a string into Base64

  • ${_base64Decode("the string you want to decode")}: Decodes the specified string from Base64

  • ${_random(N)}: Returns a random number between 0 and N

  • ${_randomUUID()}: Generates a random unique identifier

Failure notifications for Supporting Files and Asset Management imports

Receive email notifications if an import failed.

The email notification contains failure information and a link to the import configuration for troubleshooting purposes.

In the General mail settings block, under Settings > Functional settings > Email module , you can enter the Default email of sender.

Creating and managing failure notifications

  1. Navigate to Settings > Import settings > Supporting Files / Asset Management imports.

  2. Click on Imports to open the Import overview.

  3. On the top-right of the overview page, click the Failure notifications button.

  4. Click New failure notification , enter a name and one or more recipients.

  5. Alternatively, you can

    Edit existing notifications,

    Delete existing notifications,

    Set or Remove existing notifications as default.

tip

To exclude a specific supporting files / asset management import from the default settings, configure the desired failure notification in the settings. See Using failure notifications in an import below.

caution

If No notification is the default, TOPdesk won't send any notification unless this has been configured in the mail import settings.

Supporting files and asset management imports use separate failure notifications. Configure notifications for each import type, especially if you wish to use the same notifications for both.

Using failure notifications in an import

  1. Navigate to Settings > Import settings > Supporting Files / Asset Management imports.

  2. Click on Imports to open the Import overview.

  3. In the overview, mark the desired import and click Edit to make changes to its configuration.

  4. In the import wizard, navigate to Import settings (step 4).

  5. In the block Failure notifications, select the failure notification that should be used for this import.

    tip

    Select No notification to avoid receiving any failure notifications or Default failure notification to receive the default notification.

  6. Save your settings.

Additional options for failure notifications

TOPdesk sends failure notifications for imports every time the execution of an import fails.

This can have several reasons, for instance:

  • The connection to the import source can't be established.

  • The field mapping includes a field that has been removed from the source.

Additionally, you can set up failure notifications for imports which completed with errors:

  1. In the import overview, select the import for which you want to set up the failure notification and click Edit.

  2. In the Import wizard, navigate to Import settings (step 4).

  3. In the block Failure notifications, select the desired notification.

    caution

    You need to select a notification for the checkbox Also notify when one of the records fail to be imported to appear.

  4. If not yet active, activate the checkbox Also notify when one of the records fail to be imported.

  5. Save your settings.

Setting up the automated file upload

In this chapter, we guide you through setting up the automated file upload, which is required if you prefer to schedule your CSV/Excel imports automatically.

Prerequisites:

  • You created a new Supporting files / Asset Management import.

  • Your source file meets all conditions needed for the scheduled import.

  • You have an API account authorized to upload source files into TOPdesk.

  • You have a script which transfers the sources file from your server to your TOPdesk.

  • You configured a task scheduler to upload the script at specific times.

Configuring the import

In the import wizard, step 6 'Scheduling', select Automated as the type of scheduling.

Preparing the source file

  • The header isn't empty. That's the first row in the file, which is used to name the fields shown in the import wizard in step 3 'Field mapping'. Each column that contains values needs a header name.

  • All relevant data is stored on the first sheet of your Excel file.

  • The file has one of the supported extensions: CSV, XLS, or XLSX.

Character Encoding

TOPdesk supports UTF-8 encoded source files. It can convert all character encodings that are natively supported by Java (version 21) into UTF-8.

We recommend the following:

  • If possible, save your file as UTF-8.

    If your CSV file can't be converted to UTF-8 please see Uploading a file automatically from a third party system below.

  • If you are using Microsoft Excel or another Windows application, your file may be saved in Windows-1252 encoding (also known as ANSI) by default.

    Make sure your Excel files only contain characters supported by UTF-8. Otherwise, try saving your data as a CSV file instead.

How to check or set the encoding:

  • CSV files: When saving from Excel, use Save As and choose CSV UTF-8 (Comma delimited) (.csv) if available. If only CSV (Comma delimited) (.csv) is available, your file will likely be in Windows-1252 encoding.

  • Other editors: In editors like Notepad++, you can check the encoding under the Encoding menu and convert to UTF-8 if needed.

Configuring the API account

If you haven't worked with the TOPdesk API before, the chapter API Account guides you through the set up.

Assigning Permissions

In addition to the API permissions, the API account requires the following permissions:

Imports and exports

Standard import > Read

Supporting Files and Asset Managements imports

Upload source files

Note

Missing permissions lead to Error 403, Forbidden.

Uploading a file automatically from a third party system

Setting the Content-Type Header for CSV Files

If your CSV file is not in UTF-8 encoding, you can specify its encoding in the upload request. TOPdesk will then convert any supported Java character encoding into UTF-8.

To do this, add a Content-Type header that includes the correct charset. For example, if your file is encoded in Windows-1257, add this to your header:

Powershell:

'Content-Type' = 'text/csv; charset=Windows-1257'

cURL:

--header "Content-Type: text/csv; charset=Windows-1257"

cUrl script template

set mypath=D:\myfolder\mysubfolder\
set myfile=FILENAME.csv
curl --upload-file "%mypath%%myfile%" --header "Authorization: Basic USERNAME:PASSWORD" https://[YOUR_TOPDESK_URL]/services/import-to-api-v1/api/[MODULE]/sourceFiles?filename=%myfile%

Replace the following:

  • Replace D:\myfolder\mysubfolder\ with the path to the source file on your file server.

  • Replace FILENAME.csv with the name of the source file

    Important

    Don't forget to adjust the file extension.

  • Replace USERNAME:PASSWORD with the Base64 encoded login name and application password of the API account.

  • Replace [YOUR_TOPDESK_URL] with the URL of the target TOPdesk.

  • Replace [MODULE] with either assetmanagement or supportingfiles.

Powershell script template

#set variables
$customerurl='your-topdesk-url'
$mypath= "D:\Upload\"
$myfile = "filename.csv"
$file = $mypath + $myfile
$url = "https://$customerurl/services/import-to-api-v1/api/[MODULE]/sourceFiles?filename=$myfile"

#setup base64 string
$Text = 'username:ApplicationPassword'

$Bytes = [System.Text.Encoding]::UTF8.GetBytes($Text)
$EncodedAppPass =[Convert]::ToBase64String($Bytes)

$headers = @{
'Authorization' = 'BASIC ' + $EncodedAppPass
'Content-Type' = 'text/csv;'
}

#execute url
Write-Host "Uploading " $file  " to " $url -NoNewLine
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Invoke-RestMethod -Uri $url -Method PUT -headers $headers -InFile $file -SkipHeaderValidation

Replace the following:

  • Replace D:\Upload\ with the path to the source file on your file server.

  • Replace your-topdesk-url with the URL of the target TOPdesk.

  • Replace filename.csv with the name of the source file.

  • Replace 'username:ApplicationPassword with the Base64 encoded login name and application password of the API account.

  • Replace [MODULE] with either assetmanagement or supportingfiles.

remark

The URL for the API request includes a version number (import-to-api-v1). If the import service's version number changes, you need to adjust the URL in the script accordingly.

Using a task scheduler to execute the script

A task scheduling tool executes the upload script at specified times. Depending on your operating system, there are different solutions available. Configure the schedule on the server where the file originates from.

remark

Task schedulers are third-party software and are not included in TOPdesk.

Windows

You can find many tutorials on the internet about how to schedule tasks. For example, How to schedule any app (external) or Windows Central (external).

Linux

Depending on your Linux distribution, different task schedulers are available. For example, Crontab (external).



[3] This depends on the import settings (step 4 in the wizard). You can determine how the import should handle cards that are not present in the source and whether it should permit or prohibit creating/updating cards.

In this section: