Data imports

The quickest way to get all of your user details into Invotra. As a webmaster, this is where you learn how to get data importing right, for example, formatting your data correctly.

The available importers are:

  • Users
  • Teams
  • Locations
  • Job Roles

 

Users, teams, locations, and job roles are separate entities

They must be imported separately and referenced to one another accordingly. We will the outline the necessary format to import all four entities as a CSV import.

 

Accessing the importer

As a webmaster…

1. Go to Administration from your workbar

2. Locate and select ‘Import’

3. Select the appropriate importer

 

Mandatory CSV formatting

  • All CSVs must be in comma-separated value format
  • All CSVs must be UTF8 encoded
  • There must be no empty columns in the CSVs
  • There must be no columns included containing attributes that are not defined in the formats outlined for user, team, location, and job role imports
  • If there is a non-mandatory column that you would not like to use, remove it entirely from your CSV
  • The attribute titles outlined in the user, team, location, and job roles extract templates must be used, and they are case sensitive

 

Best practices for import management

  • Run large extracts, or extracts with a significant number of changes, outside of peak site usage hours
  • Either create users, teams, locations, and job roles via the importer; or do it manually via ‘User Management’ — avoid using both
  • If you’re using Single Sign-On (SSO) authentication, new users must be created via the user import, as they must be assigned a value in the Authname field
  • If you’re using SSO, your data source for CSV generation as a best practice should be your SSO identity provider (e.g. Active Directory, Azure, Salesforce)

 

Running a first-time import

Import your data in the following order:

1. Job roles, locations, teams (in any order)

2. Users

3. Users again (to make sure the manager references are updated)

 

Bulk blocking users

Be sure that all the users you want to block, are blocked:

1. Go to Administration

2. Locate and select ‘Import’

3. In the CSV file you’re going to upload, add a ‘Status’ column

4. For the users you want to block, add ‘Blocked’ in their row in the status column

5. For easy filtering add ‘Active’ to your active users’ rows, however, a blank field will default to active

 

Subsequent imports and maintaining data integrity

Complete regular teams, locations, and job roles imports to capture and create all-new teams, locations, job roles that your users need.

 

Import structures and field details for users, teams, locations, and job roles

User Import

The table below shows all available fields and the required format.

* = Mandatory field

** = Mandatory field if you are using single sign-on (SSO) to authenticate

Fields Description Format Example
GUID*

Must be unique.

This is the unique identifier for each user.

 String b1d084c4
Username*

Must be unique.

We recommend using the email address here if you do not have a current set of usernames.

 String laura.marling@invotra.com
email*

Must be unique.

The email address of the user.

 Email laura.marling@invotra.com
Authname**

Must be unique.

The unique string used for SSO (in most cases this will be the same as the value used for GUID)

 String Could be anything
ForeName The person’s first name. String Laura
Surname The person’s last name. String Marling
role ID The unique identifier of the person’s job role. This must reference an existing job role in the system. String jobrole-1234
Phone Work phone number of the person. String 01234567891
Mobile Mobile phone number of the person. String 01987654321
Linkedin Link to the person’s LinkedIn profile. URL https://www.linkedin.com/in/lauramarling/
Facebook Link to the person’s Facebook profile. URL https://www.facebook.com/laura.marling
Twitter Link to the person’s Twitter profile. URL https://twitter.com/LauraMarling
LocationID The unique identifier of the person’s location. This must reference an existing location in the system. String location-1234
Organisational ID A field to store an organisational identifier such as a staff number. String abc1234
Org unit ID The unique identifier of the person’s team. This must reference an existing team in the system. String team-1234
  A field to store an organisational identifier such as a staff number. See Add users to multiple teams via the ‘User import’ – Invotra Developer for how to add a user to multiple teams    
Manager The unique identifier (GUID) of the person’s manager. This must reference an existing user in the system. This will be used to build the Org Chart on the site. String b1d086bg

Here’s an example of a User Import CSV file with SSO disabled.

Here’s an example of a User Import CSV file with SSO enabled.

 

Team Import

The table below shows all available fields and the required format.

* = Mandatory field

Fields Description Format Example
ExternalId*

Must be Unique.

Unique identifier used to reference this team.

 String team-1234
Parent term Use the ExternalId (above) to reference a parent team if you have a team hierarchy. This will help build the team hierarchy on your site. String team-1236
Term name* The name of the team. String Marketing
Term description A description of the team, which will display on the team page. String This is the marketing team, responsible for marketing our product.
Contact This field allows you to display contact information for the team which will display on the team page. String To get in contact with the marketing team use this shared inbox – marketing@invotra.com or alternatively call 0987654333.
Published*

Define whether or not the team should be published and visible.

1 = Published

0 = Unpublished

 Integer 1

Here’s an example of a Team Import CSV file.

 

Location Import

Locations are structured in the following hierarchy:

-Site

–Building

—Floor

—-Space

This is based on the BIM model, however, we can support a flat list of office locations if you specify each location to be a ‘building’.

The table below shows all available fields and the required format.

There are more fields available if you wish to use the BIM model as mentioned above. Please contact us if you would like to explore this.

* = Mandatory field

Fields Description Format Example
ExternalId*

Must be unique.

Unique identifier used to reference this location.

 String location-1236
Parent term Use the ExternalId (above) to reference a parent location if you have a location hierarchy. String location-1234
Term name* The name of the location. String Chertsey House
Term description A description of the location, which will display on the location page. String This is our head office.
Type* Enter site, building, floor or space. If you are not using the BIM model, set this to ‘building’ for all locations. String building
Published*

Define whether or not the location should be published and visible.

1 = Published

0 = Unpublished

 Integer 1

Here’s an example of the Location Import CSV file.

 

Job Role Import

The table below shows all available fields and the required format.

* = Mandatory field

Fields Description Format Example
ExternalId

Must be unique.

Unique identifier used to reference this job role.

 String jobrole-1234
Role The name of the job role. String Digital Workplace Manager
Description A description of the job role if necessary. String Manager of the site in internal comms.
Published

Define whether or not the job role should be published and visible.

1 = Published

0 = Unpublished

 Integer 1

Here’s an example of the Job Role import CSV file.

 

Error logging on imports

Once an import is complete, a summary and error log is generated. You can access the error log by selecting the ‘Log’ tab on the import screen.

 

Hide users email address and/or phone number

  1. Generate a CSV

2. Add two additional columns to CSV: 

  • Hide email 
  • Hide phone 

3. Enter a value of ‘0‘ if you do NOT want to hide the email / phone number. Enter a value of ‘1‘ if you DO want to hide the email / phone number

4. Download the CSV in comma seperated value UTF-8 encoded format

5. Navigate to ‘Administration’ and then select ‘Import’

6. Select ‘User importer’ and upload CSV file

7. Tick option: ‘Notify users of the new account’

8. Choose role ‘External’ 

9. Select ‘Import’

 

Please note: Steps 7 and 8 can only be completed if the site has Invotra Auth enabled as the authentication mechanism 

Â