Overview
Howspace Hub offers a standard method for integrating users from external systems using a CSV-based approach.
Please note that the integration does not handle the deletion of users, groups, or roles; it only adds and updates them based on their IDs. User role and group relationships are fully refreshed, meaning that only the relationships included in the import will be retained.
This integration can be automated or it can be done manually from Hub admin (Settings => Import data). Both automated and manual import use exactly same data format.
Data formats
Users
Users can be imported by creating a CSV file named users.csv, which contains the following five columns:
column name | example value | required | notes |
id | P123456 | yes | Must be unique |
yes | Must be unique | ||
first_name | John | no |
|
last_name | Doe | no |
|
phone | +358412345678 | no |
|
Groups
Groups can be imported by creating a CSV file named user_groups.csv, which contains the following two columns:
column name | example value | required | notes |
id | GR123 | yes | Must be unique |
name | Swedish Office | yes |
|
Roles
Roles can be imported by creating a CSV file named user_roles.csv, which contains the following two columns:
column name | example value | required | notes |
id | mgr | yes | Must be unique |
name | Manager | yes |
|
Relations between users, groups and roles
To assign roles and groups to users, create a CSV file called user_role_memberships.csv. Please note that a user can belong to a role without being part of a group; however, group relation always require a role.
Also note that user can belong to multiple roles and groups. This file has three columns:
column name | example value | required | notes |
user_id | P123456 | yes |
|
role_id | mgr | yes |
|
group_id | GR123 | no |
|
Additional fields
In addition to these 'system-level' fields, you can extend all data structures with any custom fields you find relevant. For example, you could extend the users.csv with these columns:
column name | example value |
Department | Marketing |
Dietary options | none |
With custom values, please use readable string value as column name.
Example data
You can find a simple example of the import files here: CSV import examples.
CSV format requirements
We support most common CSV variants. Please follow these guidelines:
UTF-8 as encoding
Comma as a separator
Double quotes (") as an optional enclosure character
Double quotes should be escaped using double double quotes ("")
Always include a header row
The header row should contain column names exactly as specified above
Automating the integration
To schedule the integration to run nightly, please contact our support team. Currently, we support automation through SFTP and Azure Blob Storage.
SFTP or Azure Blob Storage will be hosted by customer, not Howspace.