This topic details the Users Import. Import fields and file validation details are included, in addition to a sample file.

See Documentation Topics:

Overview

The Legacy Users Import has been retained for future use and is described in the topic Users Import (Legacy). The Users Import offers the ability for many users to be imported using a single file.

User records may be imported automatically, using the on-demand Master Data Import function, or may be imported from the Admin Control Panel.

The fields described in this topic apply to both import methods.

Users - Automatic Import

Buying organizations may request implementation assistance to enable them to initiate automatic, on-demand Master Data imports from staging folders specifically set up for this purpose.

When the required folders have been set up, a Master Data Import is triggered when a csv file is dropped into the file system.

The required file path must be in the following form, where information specific to the buying organization, import entity type, mode, and filename are provided (as shown within <>):

<Client Organization>/MasterData/AutomatedImport/<entity_type>/<mode><filename.csv>

Requirements for an Automatic Users Import

The requirements for an automated Users Import are as follows:

Valid entity type is user_internal
Accepted mode is delta
File type must be csv
Fields in the file must conform with the requirements set out in the section Users Import Fields

Users Automatic Import Sample Path

Example: Organization Company A may initiate a delta Users import by dropping the following file into the file system that has been set up through BuyerQuest implementation:

Company A/MasterData/AutomatedImport/user_internal/delta/April2021.csv

Users Import from the Admin Control Panel

The Users Import is available in the Admin Panel at DATA LOADS > Manage File-Based Integrations > Import. The Entity Type is Internal User.

Delta Import Only

The scope of the Users Import can be Delta only.

User Import Template

InternalUserImportTemplate11.3.csv

Custom Fields Supported in Users Import

The BuyerQuest platform provides the ability, via the Users Import, to update the values of any additional User Attributes a buying organization has defined in BuyerQuest.

A User Attribute must first be configured in the system before the attribute value may be updated via the User Import.

User Attributes are configured in the Admin Control Panel at USERS > Manage User Attributes .

User Attribute Configurations and Imported Data

Validation and Text Length for imported User Attribute data are governed by the configurations for Attribute Information in Manage User Attributes.

Input Type should be Text . Only the Text Type is supported for the Import of User Attribute values.
Select Input Validation.
When specified, Minimum and Maximum Text Length are used to validate the length of the data included in the Import.
Values Required Yes or No is used to validate the inclusion of data in the Import. See the Validation rules described below.

User Attribute Data Import Validation and Actions

Validations of User Attribute data are as follows.

Condition	Action
Column is a configured User Attribute with Input Type as Text	User Attribute is updated with value provided in the import.
Column is not a configured User Attribute or If Attribute is Required and value in import is Null or If value is invalid as governed by the configured validation type or length specified	The row is skipped and warning message displays: " Invalid <attribute_name>"
If Required and column in import is populated with text data	Record is updated with data provided.
If not Required and value provided in import is Null	Record is populated with Null.

Users Import Fields

Column Name

Description

Field Type

Required

Sample Value

Validate

Validation Type and Action

external_id

External ID associated to user

Text

Yes

Demo_106

Not Empty

WARNING

Skip Row

last_name

Last name of the user

Text

Yes

Doe

Not Empty

WARNING

Skip Row

first_name

First name of the user

Text

Yes

Jane

Not Empty

WARNING

Skip Row

email OR login_id

Login email or login_id of the user (must be unique) The column name may be either 'email' OR 'login_id' The preferred column name is 'login_id'.

Text

jane.doe@gmail.com

Not Empty, Must be a valid form of Email Address

WARNING

Skip Row

* content_group

Content group associated to user (if not set, will default to Content Group set under User Management

Text

General

Content Group Exists in System

WARNING

Skip Row

additional_content_groups

Additional Content groups associated to the user, pipe delimited. Values are assigned to the Additional Content Groups field in the User Record

varchar (255)

CG1|CG2

Content Group Exists in System

If one or more Content Groups is incorrect, the entire row is skipped

WARNING

Skip Row

* contact_email

Contact Email for user (if none, defaults to the value in the email field)

Text

john.doe12@gmail.com

Email Address

WARNING

Skip Row

* user_permission

Permission associated to user (if not set, defaults to the Default User Permission in User Management

Text

Base User

User Permission Exists in System

WARNING

Skip Row

* preferred_currency

Preferred default currency for user (if none, defaults to Site Default Currency)

Text

USD

Preferred Currency Exists in System

WARNING

Skip Row

* preferred_language

Preferred default language for user (if none, defaults to Site Default Language) If only one store in the system, field must be left blank.

Text

fr_FR

Preferred Language Exists in System

WARNING

Skip Row

* billing_location

Default billing location for user (Identified in CSV by location ID)

String

100000

Location ID Exists in System

WARNING

Skip Row

additional_default_billing

Pair of pipe- delimited Content Group and Location ID:

<content_group1>:

<location external id>|

<content_group2>:

System will assign the Location ID received as the default billing location for the received Content Group

varchar (255)

CG1:10035|CG2:34511

Content Group Exists in System

If one or more Content Groups is incorrect, the entire row is skipped

Location ID Exists in System

If one or more Location IDs is incorrect, the entire row is skipped

If a Content Group-Location pair is not specified for a Content Group that is in the User's Additional Content Groups, the default

Billing Location is Null

WARNING

Skip Row

* shipping_location

Default shipping location for user (identified in CSV by location ID)

String

100012

Location ID Exists in System

WARNING

Skip Row

additional_default_shipping

Pair of pipe- delimited Content Group and Location ID:

<content_group1>:

<location external id>|

<content_group2>:

System will assign the Location ID received as the default shipping location for the received Content Group

varchar (255)

CG1:10035|CG2:34511

Content Group Exists in System

If one or more Content Groups is incorrect, the entire row is skipped

Location ID Exists in System

If one or more Location IDs is incorrect, the entire row is skipped

If a Content Group-Location pair is not specified for a Content Group that is in the User's Additional Content Groups, the default Shipping Location is Null

WARNING

Skip Row

preferred_locations

Pair of pipe- delimited Content Group and Location ID:

<content_group1>:

<location external id>|

<content_group2>:

Values received will add preferred locations to the user's My Account

Locations and Accounting > Preferred Locations section.

varchar (255)

CG1:Loc1|CG2:Loc2

Content Group Exists in System

If one or more Content Groups is incorrect, the entire row is skipped

Location ID Exists in System

If one or more Location IDs is incorrect, the entire row is skipped

If a Content Group-Location pair is not specified for a Content Group that is in the User's Additional Content Groups, the preferred_locati ons for Content Group will be Null for that that Content Group

WARNING

Skip Row

* is_activated

Status of the user 1=Active

0= Inactive

Boolean

1 or 0

WARNING

Skip Row

* approver

External ID of the approver for the user

Text

DEMO_111

* approval_limit

Amount user is able to spend before approval by Approver is required

Decimal

500

Is Numeric

WARNING

Skip Row

* telephone

user's telephone number

String

888-478-5151

* deliver_to

Name for the Deliver To field during Checkout

Text

Jane Doe

* delegation_to

External ID of user account is delegated to, dependent on delegation_start and delegation_end

Text

DEMO_233

external_id exits in system

WARNING

Skip Row

* delegation_start

Delegation Start Date in format MMDDYYYY,

dependent on delegation_to and

delegation_end

Date

08202017

Date

WARNING

Skip Row

* delegation_end

Delegation End Date in format MMDDYYYY,

dependent on delegation and

delegation_start

Date

08282017

Date > delegation_start

WARNING

Skip Row

bqpay_company

Used to assign BQPay Company in user record

varchar (255)

BuyerQuest

BQPay

Company exists in system

BQPay

Company values are located in Admin Control Panel > ACCOUNTING

Manage BQPay

Companies

WARNING

Skip Row

* accounting_group_#

Used to assign default accounting values to user. 0 or more columns of this data are allowed. # is the id of the Accounting Group in Manage Accounting Group

Integer

0008

Id for Accounting Group exists in System

WARNING

Skip Row

Notes

The columns marked with an asterisk should be treated as defining which System is the System of Record (SoR) for that information.
If the column is listed in the CSV, then the SoR should be considered as NOT BuyerQuest. This means that all information related to this column should be overwritten by what is in the file. If the column is not present in the CSV, then the SoR should be considered to be BuyerQuest, meaning that the information should not be overwritten by the Importer.
The specified entity type of Internal User eliminates the need for User Type and so it has been removed from the template.
Supplier has also been removed from the template. Accommodation for supplier user data import is planned in a future release.
If Contact Email is not populated during import, the Contact Email field will inherit the value from the email or login_id field.

Information Set on Import

The following information is attached to a record on successful import:

Type = Internal User
Associate to Website = Main Website
Allow Access To = 0 (Customer site only)

Primary Key Algorithm

The algorithm used to determine whether a user record should be updated or created is as follows:

If External ID already exists and email matches, if so then update any other User information for that User.
If External ID exists but email does not match, then check 'Email':
If Email does not exist already in system, then update Email and any other User information for that User.
Else If Email does exist already in the system, then throw Warning ("External ID and Email already exist for different Users.").
If External ID does not exist, check 'Email':
If Email does not exist, then create User and update any other User information for that User.
Else if there is already a User with that email, update the External ID and then update any other User information for that User.

File Validation

File validation and associated messaging is detailed below for User Import.

Use Case	Import State	Message
File Completely empty. No header and No records (rows)	Failed	The file provided does not contain the expected columns. Please check columns against template and provide updated catalog
File has header but no rows.	Success	File contains no records.
File has some empty/invalid rows. (refer to note below)	Success	Invalid {attribute_name}
File has header and ALL empty/invalid rows.(refer to note below)	Failed	File contains no valid records.
File has an invalid header name	Failed	The file provided does not contain the expected columns. Please check columns against template and provide updated catalog

Notes

no rows means there is a header and a blank file after that.

empty/invalid rows means there is a header row and the first line has , , , , … no data inside

See Documentation Topics:

Overview

Users - Automatic Import

Requirements for an Automatic Users Import

Users Automatic Import Sample Path

Users Import from the Admin Control Panel

Delta Import Only

User Import Template

Custom Fields Supported in Users Import

User Attribute Configurations and Imported Data

User Attribute Data Import Validation and Actions

Users Import Fields

Information Set on Import

Primary Key Algorithm

File Validation

Related articles