How to import user accounts using CSV?

We can perform once-off uploads of users accounts for you, or we can set up automated CSV imports using sFTP.

As employees join and depart an organization, you need to grant and revoke their access to Motimate. In the context of cloud or Software as a Service (SaaS) applications, user account management is referred to as provisioning and de-provisioning. This also includes adding and removing users to groups based on what department they belong to and/or what role they have in the organization.

Prerequisites for being able to login and use Motimate services are:

  1. The employee has a user in Motimate and,
  2. The user belongs to certain set of groups based on what department and role the employee has.

The employee's user accounts need to be provisioned before the users first login, and when they leave the company their accounts have to be deactivated.

Batch Scheduled CSV file transfer

The CSV file contains all the required user and group membership information for all employees that shall have access to Motimate. With CSV Imports, you may to set up a scheduled file transfer and send an updated employee data file each night. The file is transferred to Motimate by uploading the file through encrypted SFTP.

When Motimate receives the new file we grant and revoke access based on the information in the new file. If a new user account is added, it will be added to Motimate, and if a user account is not in the file anymore, the user is deactivated in Motimate. Motimate will also update existing user information and the users group memberships according to the file. If you select this option, contact support@motimateapp.com and we will provide you with with the implementation details for SFTP and CSV imports.

This import method can be combined with manual account management. Users and groups that are imported are marked as imported in the administrator page.

File content specifications

The CSV file has a set of required columns that must be included for a success ful import. You may download a copy of a CSV structure and sampel in Excel format here: The file format sample.

The organization needs to decide what should be the source system of the employee data that is needed in order to use Motimate. This should be the system that the organization uses to store employee master data.

Groups: Organizational hierarchical groups

The organization can choose to only use level 1 and level 2 groups. Level 1 is the whole organization and all users are added by default to this group. Using level 3-6 is optional. If these levels are not used just leave them empty in the file. Level 4-6 has the same fields as level 3 below. A group on level 3 will automatically be set as a child of the group on level 2. The level 4 group will be a child of the level 3 group. This is used to build a hierarchy of groups for the company. This hierarchy is used in several features in the product.

Custom groups

The custom groups are not related to other groups, and are typically used to provide a communication channel for employees with certain roles independent of their position in the organizational hierarchy. Examples of use of custom groups could be cross team groups for store managers, plumbers or household appliances specialists. Motimate is all about connecting people, and custom groups connect people across organizational structures. It’s possible to have as many custom groups as you like, and a person can be in as many custom groups as you have custom groups. In the import file, you must create one additional row for each custom group a user is a member off. Each new line must contain all the user data fields including the position fields and custom group fields.

You can not add a custom group in the same line as you import the person. Each custom group needs to be on its own line. In other words, one custom groups, require two lines. Two custom groups require three lines.

Example User Scenarios

In the examples below we will illustrate a few typical user scenarios, and how to format them in the CSV file. We assume a Motimate account with the following groups:

Group Structure Examples-Functional-drawio-png
Download this example CSV-file (or view in Google Sheets) to see how the users below have been registered in our CSV format.

Mary Smith

  • Is the head of the HR Department and has been granted role as Group Admin by setting the value of level_2_role_in_group to 1 for the group HR Department.
  • She will be able to retrieve reports for all users in HR Department, as well as of the groups below it, in this case: L&D Team and Payroll. There is no need to add her to these two child groups.
  • Her Position is set to HR Director.

Peter Jones

  • Peter Jones is a Pricing Analyst in the Pricing Team. In addition he is leading the cross-functional Innovation Project Team.
  • His level_3_role_in_group value for Pricing Team must be set to 0 because he is just a normal member of this team. The same is the case for his membership of Marketing Department.
  • However, since Peter is leading the Innovation Project Team, we will set the level_3_role_in_group value for Innovation Project Team to 1. This ensure that he will be able to retrieve reports for all other members in this project team.
  • His Position is set to Pricing Analyst. It is set on the same row as the Pricing Team. But this does not matter, as Positions in Motimate are not linked to Groups. Peter will receive training assigned to Pricing Analysts in any Groups that he is a member of.
  • Please note that even though there is space for the Innovation Project Team on the same row as the two other groups, we have entered Peter's membership in this Custom Level 0 Group on a separate row. Memberships in Custom Groups must always be registered on separate rows!

Carrie Walker

  • Carrie is a Trainee and works in both the L&D Team and in the Payroll Team.
  • It is not possible to register two groups in the level_3_group_name field on the same row. As such we must have two identical rows for Carrie, where we simply change the data for her Level 3 group.
  • Her Position is Trainee on both rows, but that is not required. We could also have registered the Position only on one of the rows.

Alan Brown

  • Alan hold two Positions in the Digital Marketing team. He is both a Marketing Analyst and Digital Specialist. He is not a member of any other group, except also the parent group: the Marketing Department.
  • It is not possible to register two Positions in the position field on the same row. As such we must have to identical rows for Alan, where we simply change the data in the position field and keep everything else the same.

Alex Williams

  • Alex is the Team Lead in the Payroll Team.
  • We only need one row, but in order for Alex to be able to retrieve report on everyone in the team, we have to make sure the value of level_3_role_in_group is set to 1.
  • The value of level_2_role_in_group must still be set to 0, because they should not have access to reporting for the entire HR Department.

Taylor Parker

  • Taylor works as Digital Specialist in the Digital Marketing Team.
  • This is your average user, and you'll find that most users can be registered on a single row very simple just like this.
It is critical that all data such as employee_id, first_name, last_name, email and phone is identical on all rows for scenarios when you need to create more than one row for a user! If data is not identical, the data on the last row for the user will overwrite that of the previous row(s).

File Transfer

The import runs in the morning at 04:30 UTC+1. The filename must contain the current date. This means that if you create it prior to midnight, make sure it has the the next days date. There are also some other format requirements listed bellow:

  1. The file extension must be .csv.
  2. The file must be saved under the account uploads folder.
  3. The filename must include the date in the following format YYYYMMDD.
  4. The file is UTF-8 encoded without BOM (Byte order mark).
  5. The file uses a semicolon ";" as its delimiter. Comma "," is not supported!
  6. The file has all columns and the order is as described in the Columns section-

By uploading a file with users to our sFTP server we will import the file and create new, delete old and update userdata of the users in Motimate each night.

Example: Acme Corporation wants to upload users file every day at 22:00. They want to start on January 1st, 2021. Since the importer runs on the morning of next day, the expected filename format must be: /uploads/20170102.csv

sFTP Details

Host: sftp.motimate.app

Username: <your-account-identifier>

<your-account-identifier> is the short name you see in the url. So for Acme Corporation, they will have the url https://acme.web.motimateapp.com and the shortname is here "acme".

Password will be provided to you separately, when you contact support@motimateapp.com to set up sFTP.

Data quality assessment

Many organizations have insufficient data quality for employee master data. This could be missing or wrong phone numbers, misspelled names, missing email addresses, employees that left the company 2 years ago are still registered as employees, wrong department associations etc.

Bad data quality can cause problems when introducing Motimate in the organization since Motimate relies on the data for example to send passwords to the users by SMS and add users the appropriate groups. For this reason, the data should be reviewed and corrected before launching Motimate in the company to reduce problems when launching. Motimate can assist the company with reviewing data quality.

Limitations

Manually created users have priority before imported users, and can not be deleted from the import. You need to handle manually created users through Web Admin manually. If you have problems with this or any other issues, please do not hesitate to contact support@motimateapp.com.