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

FieldsDescriptionFormatExample
GUID*

Must be unique.

This is the unique identifier for each user.

Stringb1d084c4
Username*

Must be unique.

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

Stringlaura.marling@invotra.com
email*

Must be unique.

The email address of the user.

Emaillaura.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)

StringCould be anything
ForeNameThe person’s first name.StringLaura
SurnameThe person’s last name.StringMarling
role IDThe unique identifier of the person’s job role. This must reference an existing job role in the system.Stringjobrole-1234
PhoneWork phone number of the person.String01234567891
MobileMobile phone number of the person.String01987654321
LinkedinLink to the person’s LinkedIn profile.URLhttps://www.linkedin.com/in/lauramarling/
FacebookLink to the person’s Facebook profile.URLhttps://www.facebook.com/laura.marling
TwitterLink to the person’s Twitter profile.URLhttps://twitter.com/LauraMarling
LocationIDThe unique identifier of the person’s location. This must reference an existing location in the system.Stringlocation-1234
Organisational IDA field to store an organisational identifier such as a staff number.Stringabc1234
Org unit IDThe unique identifier of the person’s team. This must reference an existing team in the system.Stringteam-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  
ManagerThe 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.Stringb1d086bg

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

FieldsDescriptionFormatExample
ExternalId*

Must be Unique.

Unique identifier used to reference this team.

Stringteam-1234
Parent termUse the ExternalId (above) to reference a parent team if you have a team hierarchy. This will help build the team hierarchy on your site.Stringteam-1236
Term name*The name of the team.StringMarketing
Term descriptionA description of the team, which will display on the team page.StringThis is the marketing team, responsible for marketing our product.
ContactThis field allows you to display contact information for the team which will display on the team page.StringTo 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

Integer1

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

FieldsDescriptionFormatExample
ExternalId*

Must be unique.

Unique identifier used to reference this location.

Stringlocation-1236
Parent termUse the ExternalId (above) to reference a parent location if you have a location hierarchy.Stringlocation-1234
Term name*The name of the location.StringChertsey House
Term descriptionA description of the location, which will display on the location page.StringThis 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.Stringbuilding
Published*

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

1 = Published

0 = Unpublished

Integer1

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

FieldsDescriptionFormatExample
ExternalId

Must be unique.

Unique identifier used to reference this job role.

Stringjobrole-1234
RoleThe name of the job role.StringDigital Workplace Manager
DescriptionA description of the job role if necessary.StringManager of the site in internal comms.
Published

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

1 = Published

0 = Unpublished

Integer1

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