Skip to main content

User Import

This document describes the file-based interface for user import into the Swiss Learning Hub. The personal data can be transferred in XML format via SFTP.

Data transfer
The files are transferred to the SLH server via SFTP. You will receive the SFTP access data from your SLH contact person.

File format
The file format is XML. The files must be encoded as UTF-8.

Process time
The process time can be determined individually (usually once a day at night), but must be coordinated with other processes by SLH.

User import
The full functionality of a user import can only be executed if all current users are listed in the transferred file. It is possible to configure the user import for a specific organizational unit only. Thus, further organizational units can be maintained manually in the Swiss Learning Hub and are not affected by further processes.

Processes

Removing users
The user import is designed to automatically remove users that are not listed in the file. The import can be configured accordingly, so that these users are effectively deleted (incl. all learning data) or archived (thus access by the user to the system is prevented, but as an administrator one still has access the user incl. all his/her learning data). If a user has set the value "Deletable" = no (0) in the Swiss Learning Hub, this user will never be removed by the user import. Thus, e.g. via the interface of the Swiss Learning Hub, external users can be subscribed, which do not have to be part of the user import file.
It's also possible to protect user from deletion by adding them to a specific organizational unit. In the setup a queryparameter ('excludeorgs') with a list of units which should be excluded from deleting/archiving.

Updating users
If a user is already integrated in the Swiss Learning Hub, it will not be newly created by the user import, but updated. However, the user must be uniquely identifiable for this purpose. In the first priority, the user is identified by the personnel number. A personal id can be, for example, a system ID from the conversion system or effectively an internal company value. It should be noted that this is unique and will certainly never be changed (e.g., in the event of a name change due to marriage) or reassigned to another person (e.g., e-mail addresses are reassigned after a resignation). This is important in case persons are not deleted from the Swiss Learning Hub for data protection reasons, but archived and certainly thus never overwritten by a new user. In second priority, the user is also identified by user name or e-mail address.

Updating user roles
By default the import does not update a users role. It's set on the first import (on create) of a user. After that, higher roles than “learner” have to be set manually in user administration. 
There is a functionality (query parameter 'changerole') in place which explicitly allows to update all user roles given in an import file.

Data model

Object Person

Name Description Key Format Example
Prename first name of the person. prename String 255 character Max
Name last name of the person. name String 255 character Muster
E-Mail E-mail address of the person. email String 255 character max.muster@meinefirma.ch
Username Unique username of the person. username String 255 character max.muster@meinefirma.ch
Personnel number Unique internal id of the person. personal_id String 255 character 135487
Status Status of the person:
  • activated = person can use the Swiss Learning Hub
  • deactivated = person cannot use the Swiss Learning Hub, but the administrator can use the person, just like an activated person
  • archived = person cannot use the Swiss Learning Hub, the admin can access the person incl. learning data.
 status Enum:
  • enabled
  • disabled
  • archived
 enabled
Birthday Birthday of the person. birthday Date yyyy-mm-dd 1986-04-12
Deletable Defines whether a person can be deleted by the user import (manually or automatically). is_deletable Boolean (0/1) 1
Language The language of the person. language Language (CLDR)
  • de = german
  • fr = french
  • it = italian
  • en = english
 de
Role The system role of the person. role Enum:
  • learner
  • default-subadministrator
  • administrator
 learner
Organizational units All organizational units of the person. orgunits Array of the object organizational unit  
Job descriptions All job descriptions of the person. jobdescriptions Array of the object job description  

Object Organisational unit

Name Description Format Example
Name Complete path of the organisational unit String. Organisational units are separated by "/", per unit max 255 chars can be used OU-1/OU-11/OU-111

Object Jobdescription

Name Description Format Example
Name Complete path of the jobdescription String. Jobdescriptions are separated by "/", per unit max 255 chars can be used Developer/Frontend

Example

<?xml version="1.0" encoding="UTF-8"?>
<persons schemaVersion="1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="https://cdn.swisslearninghub.com/xml/trc/v2.0/import_person"
  xsi:schemaLocation="https://cdn.swisslearninghub.com/xml/trc/v2.0/import_person https://cdn.swisslearninghub.com/xml/trc/v2.0/import_person.xsd">
    <person>
        <prename>Max</prename>
        <name>Muster</name>
        <email>max.muster@meinefirma.ch</email>
        <username>max.muster</username>
        <personal_id>135487</personal_id>
        <status>enabled</status>
        <birthday>1986-04-12</birthday>
        <is_deletable>1</is_deletable>
        <language>de</language>
        <role>learner</role>
        <orgunits>
            <orgunit>OU-1/OU-11</orgunit>
            <orgunit>Entwicklung/Team Frontend</orgunit>
        </orgunits>
        <jobdescriptions>
            <jobdescription>Meine Tätigkeit</jobdescription>
            <jobdescription>Frontend Entwickler</jobdescription>
        </jobdescriptions>
    </person>
    <!-- more persons -->
</persons>

Validate XML file using xmllint and schema file:

# Download schema file
wget -O import_person.xsd https://cdn.swisslearninghub.com/xml/trc/v2.0/import_person.xsd

# Validate/Lint XML file
xmllint --schema import_person.xsd import_persons.xml --noout
Back to top