Import users
  • 13 Jun 2024
  • 8 Minutes to read
  • Contributors
  • Dark
    Light

Import users

  • Dark
    Light

Article summary

  • Applies to: All Board Cloud subscriptions

To bulk import users and automatically configure their details and authorizations, you can use the Import feature.

WHAT: External file format and information

The source file must be a CSV (Comma Separated Value) file with commas as delimiters, its size can't be greater than 2048 Kb, and must have a .csv extension, for example filename.csv.

The first row of the file must contain column headers. The number of columns must match the number of values that have to be imported for each user.

The following values are suggested, when you prepare a CSV file for import:

Header name

Description

Accepted values

username

  • Text

  • Required value, must be unique

  • Refers to the "Account name" field in the Users profile panel

All characters

email

  • Text in email format

  • Syntax: xxxxx@xxxxxxx.xxx

  • Required value if boardauthentication = true

All characters

displayname

All characters

phonenumber

  • Text

  • Optional value

All characters

userlicense

  • Required value. Must be one of the accepted values

  • Refers to the "License" field in the Users profile panel

  • This value is optional and can be left blank if the user is assigned a Permission Group through the corresponding cell of the "permissiongroup" column

developer

power user

user

lite

mobile

user 15

isadmin

  • Boolean

  • Required value

  • Refers to the platform specified in the same row

  • This value is optional and can be left blank if the user is assigned a Permission Group through the corresponding cell of the "permissiongroup" column

true

false

role

  • Text

  • Required value. Must match an existing role. Roles are configured in Board Platforms (the "Admin" role is available out of the box)

  • This value is optional and can be left blank if the user is assigned a Permission Group through the corresponding cell of the "permissiongroup" column

All characters

permissiongroup

  • Text

  • Optional value. Must match an existing Permission Group name

  • If the value is left blank, no Permission Group will be assigned to the user (i.e. in the User profile panel, the option in the Permission Group drop-down menu will be set to "None")

All characters

license

  • Required value. Must be one of the accepted values

  • If the user is associated with more than one platform, it will be necessary to import him/her multiple times: one row for each platform.

  • This value is optional and can be left blank if the user is assigned a Permission Group through the corresponding cell of the "permissiongroup" column

developer

power user

user

lite

mobile

user 15

boardauthentication

  • Boolean

  • Required value

true

false

msofficeenabled

  • Boolean

  • Required value

  • This value is optional and can be left blank if the user is assigned a Permission Group through the corresponding cell of the "permissiongroup" column

true

false

disabled

  • Boolean

  • Required value

  • This value is optional and can be left blank if the user is assigned a Permission Group through the corresponding cell of the "permissiongroup" column

true

false

instancename

  • Text

  • Required value. Must match the name of one of the platform associated with the Subscription Hub

  • This value is optional and can be left blank if the user is assigned a Permission Group through the corresponding cell of the "permissiongroup" column

xxxxxxxxx.board.com

culture

  • Text

  • Optional value

  • Syntax: xx-yy (case insensitive)

    • xx is a primary sub-code that identifies the language (e.g., "en", according to ISO 639-1 alpha-2 code)

    • yy is a secondary sub-code in capital letters that specifies the national variety (e.g., "US" or "AU" or "GB" according to ISO 3166-1 alpha-2 standard)

  • Syntax examples: en-US, en-CA, es-ES, it-IT

  • A list of localization codes and tags can be found here

xx-yy

[custom metadata field name]

  • Text

  • Required value

  • Must follow the configuration in User metadata section

  • Accepts multiple values, comma separated, enclosed in double quotes

Portugal (single value) "Italy,Germany,Spain" (multiple values)

isshadmin

  • Boolean

  • Required value

  • This value is optional and can be left blank if the user is assigned a Permission Group through the corresponding cell of the "permissiongroup" column

true

false

Additional important information to note:

  • The following column headers are required and must be included in the CSV file:

    • username

    • userlicense

    • instancename

    • role

    • license

  • If the values are less than the number of columns, the import process will abort and an error message will be shown: no users will be imported

  • If the values are more than the number of columns, all the exceeding values will be discarded, but the users will still be imported in the Subscription Hub

  • If you import more users than your license allows, all the exceeding users will still be imported, but they'll be disabled by default

  • If you want to associate one user to multiple platforms, you must add one row of values for each platform.
    The following field values in each row must match (case-insensitive):

    • email

    • userlicense

    • displayname

    • boardauthentication

    • msofficeenabled

    • phonenumber

    • culture

  • If you want to associate more platforms with the same user, remember that the platform license must be equal to or lower than the main user license. If the main user license is lower than the platform license you're assigning to a user, the platform license will be downgraded and will be equal to the main license

  • If you try to import two or more users with the same email and instancename values, the update process will abort and no user will be updated

  • If you try to import two or more users with the same email value, the system will import only the first occurrence of this value

  • If you try to import a user with an email address already present within the Subscription Hub and a new username value, the system will ignore all information in the entire row

  • If you try to import two or more users with the same username and instancename values, the system will import only the first occurrence of these values

  • You can't specify any Authentication type other than Board authentication in your CSV file. If the value is set to "false", the system will apply the next authentication type available

  • The "culture" value defines the Culture attribute in the User profile panel. If the value is typed incorrectly or no value is specified, the system will ignore the information and attempt to continue

  • After the import process is finished, all users associated with the Board authentication type will have to set and confirm their account's password. To do so, an administrator will need to send them a notification email: this can be done in bulk from the Users home page or from each user's profile panel

  • If you have custom metadata you want to import, remember to configure those fields accordingly in the Subscription Hub and to add the matching column in your CSV source file

  • Client API Users cannot be imported via CSV file

  • If the import process associates users with one or more platforms affected by a Sync rule, users synchronization is performed

  • If no value is specified in a field that accepts only Boolean values, it will be interpreted as having a "false" value.  This will also happen if a value other than "true" or "false" is specified in these fields

  • In the case of a Permission Group assigned to a user via the import feature, values specified at the user level will still be saved in the User account, but the Permission Group settings will always have the highest priority. If the association with the Permission Group is removed at a later time, the user-level settings will be applied again

A basic template file can be downloaded here (replace "custom metadata" headers with the custom metadata fields's names you have in place. Add more custom metadata headers as needed)

Bulk update using CSV file

You can also bulk update users using a CSV file, but you will only be able to perform the following actions:

  • Update the email value (any existing value will be overwritten. The new value can't be equal to an email address already present within the Subscription Hub but can be empty). If the new value is different from the previous one, the user's enrollment status will be changed to Pending. Users with the enrollment status set to Imported will keep their status

  • Update the displayname value (any existing value will be overwritten)

  • Update the phonenumber value (any existing value will be overwritten)

  • Change the boardauthentication value. If the new value is set to False, the user's enrollment status will be changed to Completed. If the new value is set to True, the user's enrollment status will be changed to Pending: users with the enrollment status set to Imported will keep their status

  • Change the userlicense value. If the new license value doesn't match the accepted values, the update process will abort and no user will be updated. If the new main license value is lower than the platform license assigned to the user, the platform license will be downgraded and will be equal to the main user license

  • Update the culture value (any existing value will be overwritten)

  • Change the msofficeenabled value

  • Change the disabled value

  • Update existing platform associations

    • If the new platform name is typed incorrectly, the update process will abort and no user will be updated

    • If the isadmin value is set to True but the main user license is different from "Developer", it will be automatically set to False

    • If the new license value doesn't match the accepted values, the system will ignore all information in the entire row and will continue to the next row. If the new main license value is lower than the platform license assigned to the user, the platform license will be downgraded and will be equal to the main license

    • If the new platform license value is greater than the main user license, the platform license will be downgraded and will be equal to the main user license

  • Associate existing users with one or more platforms they're not already associated with, and set roles and licenses for those platforms

  • Update custom metadata (all custom metadata will be overwritten, in case there are new imported values)

  • Change the isshadmin value

The following column headers are required and must be included in the CSV file:

  • username

  • userlicense

  • instancename

  • role

  • license

If the update process associates users with one or more platforms affected by a Sync rule, users synchronization is performed.

A basic template file for bulk user update can be downloaded here.

HOW: Import users through a CSV file

  1. To import a user account list from a file, click on "IMPORT" in the upper left corner of the page

  2. From the pop up, select or drag and drop your file and wait for the import process to end. A pop up will then show the number of successfully imported users

  3. After the import process is finished, all users associated with the Board authentication type will have to set and confirm their account's password. To do so, an administrator will need to send them a notification email: this can be done in bulk from the Users home page or from each user's profile panel


Was this article helpful?

What's Next