This page describes how Member Role data are imported via the https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/1460502917, which is accessible at Admin → Import Data.

For simple “how-to” scenarios, jump to the “Common Scenarios” section.

This is different than the legacy https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/1498514041 feature. See https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/1498579559 for a comparison.

Changes to Member Role handling were introduced in version 11.0.22; refer to the page history for this document for earlier versions of LearningBuilder.

1 Overview
2 Supported operations
3 Limitations and constraints
- 3.1 Member Role Import does not assign system-generated Unique Identifiers
- 3.2 Cannot create new Members with multiple Member Roles in a single file
4 Key concept: Member and Member Role identifier columns
5 Supported file formats
6 Identifying the Data Import Step and/or Workflow Action
7 Common scenarios

Overview

The Member Role import feature allows demographic and credential data to be created or modified via batch file upload.

This feature uses to leverage the Workflow Engine so that Workflow Behaviors can be triggered in response to the file upload.

This supports numerous use cases:

Synchronizing LearningBuilder with 3rd party system of record
Ad-hoc data manipulation (e.g. “non-process-based” operations, such as adding new records)
Bulk processing of process-based Workflow operations (e.g. “mark all of these licenses as revoked and send notifications”)

Supported operations

Depending on the file format, this feature can perform the following operations:

Update existing Member Roles
Add new Member Roles to existing Members
Add new Member and Member Role combinations

Limitations and constraints

Key concept: Member and Member Role identifier columns

Each row in an uploaded file can result in a different operation being taken, depending on its data:

Update an existing Member Role
Add a new Member Role to an existing Member
Add a new Member, and then add a new Member Role for them

Not all files are capable of performing each of those operations; it depends on which “identifier columns” are included in the file.

Identifier columns are prefixed with a colon (“:”) and are used to determine which pre-existing Member and Member Role are related to each row.

Process flow overview

This diagram provides a high-level overview of the process for determining the operation that will be performed for each data row.

See the following sections for more information on which columns are “Member Role identifiers” and which columns are “Member identifiers”.

Member Role identifiers

These columns are used to identify an existing Member Role that should be updated, or the values that should be used when creating a new Member Role.

Data files should use one of the following sets of columns:

Identifier Column	Purpose	Updates `Member Role`?	Inserts new `Member Role`?

Identifier Column	Purpose	Updates `Member Role`?	Inserts new `Member Role`?
`:MemberRoleId`	Updates existing records based on an internal ID.	Yes	No
`:UniqueId` + `:RoleName`¹[+ `:RoleLabel`²]	Updates existing records based on the Unique Identifier and Role Name.	Yes	Yes

Member identifiers

If no existing Member Role can be updated, the system will attempt to create a new Member Role.

To do that, it must figure out whether that new Member Role should be associated with an existing Member, or whether a new Member must also be created.

Use one of the following Member Identifier schemes to support creation of new Member Roles:

Priority¹	Identifier Column	Purpose	Can insert new `Member`?

Priority¹

Identifier Column

Purpose

Can insert new
Member?

1

:MemberId

Matches an existing Member based on internal ID.

No

2

:MemberNumber

Matches a Member that has any Member role with this Unique Identifier.

No

(But can be combined w/ :Email to do this)

3

:Email

Identifies a Member by their primary email address.

Yes

Understanding how `:MemberNumber` works

In LearningBuilder, the Unique Identifier attribute is a Member Role Attribute, not a Member Attribute.

However, many programs choose to assign the same Unique Identifier to every Credential held by the same person. In those programs, Unique Identifier is a de-factor Member-level identifier.

Common configuration where `Unique Identifier` is unique to a Member, not a Member Role

Common configuration where `Unique Identifier` is unique to a Member, not a Member Role
Licensee	Credential	Unique Identifier
Joe Practitioner	Licensed Real Estate Broker	ABC-1234
Joe Practitioner	Licensed Accountant	ABC-1234

Other programs assign a truly unique identifier to every Member Role instance, so licensees with multiple credentials will also have multiple Unique Identifiers associated with their account:

Possible configuration where `Unique Identifier` is unique to each Member Role

Possible configuration where `Unique Identifier` is unique to each Member Role
Licensee	Credential	Unique Identifier
Joe Practitioner	Licensed Real Estate Broker	REAL-1234
Joe Practitioner	Licensed Accountant	NUM-1234

The :MemberNumber attribute supports this latter use case. It is a Member identifier field that matches an existing Member that has any Role with a matching Unique Identifier.

This allows a data file to add a new Member Role to an existing Member, referencing them by one of their other identifiers:

Example of using :MemberNumber to add a new Role to an existing Member

Important rule governing `:UniqueId`, `:MemberNumber`, and `:Email`

When a data file contains both :UniqueId and :Email, and a Member Role matching :UniqueId DOES exist but is owned by a Member with a different email address, the existing Member Role will be updated UNLESS :Email is in use by a completely different Member.

This supports the scenario in which multiple parties are uploading data for the same Member Role, but are using inconsistent email address data. For instance, one party knows the Practitioner by their personal email and the other party knows them by their work email, which results in two different data files that use the same Unique Id but different emails:

In this case, to avoid creating duplicate Members, the system will update the existing Member Role (matching :UniqueId) even if :Email doesn’t match the current Member details.

Supported file formats

Typically, a file will include both Member Role identifier and Member identifier columns as described above, and the two sets can be combined as needed.

This section lists some common combinations of those identifiers.

Identifier columns	Notes / Purpose	Update `Member Role`?	Insert `Member Role`?	Insert `Member`? ³	Supports multiple `Member Roles` for the same `Member` in a single file?

Identifier columns	Notes / Purpose	Update `Member Role`?	Insert `Member Role`?	Insert `Member`? ³	Supports multiple `Member Roles` for the same `Member` in a single file?
`:UniqueId` + `:RoleName`¹[+ `:RoleLabel`²]	Updates existing `Member Roles` using the Unique Identifier.	Yes	No	No	Yes
`:UniqueId` + `:RoleName`¹+ `:RoleLabel`²+ `:MemberNumber`	Updates existing `Member Roles` or adds new `Member Roles` to existing `Members`. This is useful when the people relating to your input will already exist, but may or may not have the desired `Member Role` records. If a `Member Role` matches `:UniqueId` and `:RoleName`, it will be updated If a `Member` exists with any Role matching `:MemberNumber`, a new `Member Role` is created for them Otherwise, the row is rejected	Yes	Yes	No	Yes
`:UniqueId` + `:RoleName`¹+ `:RoleLabel`²+ `:MemberNumber` `:Email`	Can perform any of the three possible operations, using Unique Identifier or Email to identify existing records. The identifiers are “OR’ed” together in this sequence: If an existing `Member Role` matches (`:UniqueId` + `:RoleName`) and belongs to a `Member` matching (`:MemberNumber` or `:Email`) then it is updated to match the uploaded data. If an existing `Member Role` matches `:UniqueId` and `:RoleName`, but NOT `:Email`, then it is updated as long as `:Email` is not used by anyone else in the system. If the identifiers point to multiple candidate `Members` then the row is rejected. (When an update occurs, the* `:Email` value is ignored; the existing `Member` does NOT get updated with a new primary email address) If NO existing `Member Role` matches `:UniqueId` and `:RoleName` then a new `Member Role` will be created, using `:MemberNumber` and `:Email` to determine if it can be assigned to an existing `Member` or if a new `Member` should be created. If a `Member` exists matching both `:MemberNumber` and `:Email`, they are given a new `Member Role` using `:UniqueId` If a `Member` exists matching `:MemberNumber` but NOT `:Email`, and `:Email` is not in use by any other Member^* , they are given a new `Member Role` using `:UniqueId`. (Same logic as above) If one `Member` exists matching `:MemberNumber`, and a different `Member` exists matching `:Email`^, the row is rejected because it does not uniquely identify a single account to modify If no `Member` exists matching `:MemberNumber`, then a new `Member` is created (using `:Email`) and is given a `Member Role` using `:UniqueId` (requires that the configuration support creating new Members, as described below*)	Yes⁴	Yes	Yes³	Yes, if the `Member Role` already exists.
`:UniqueId` + `:RoleName`¹[+ `:RoleLabel`²] + `:Email`	Can perform any of the three possible operations, using Primary Email Address to identify existing records. Similar to above, but only uses Email for locating an existing Member. If a `Member` exists matching `:MemberNumber` and a different member exists matching `:Email`, the row is rejected. If a `Member Role` matches `:UniqueId` and `:RoleName`, it will be updated even if the Member’s email address does not match `:Email` as long as the Email does not match to another member of the member type of the role. If a `Member` exists matching `:Email`, a new `Member Role` is created for them (unless they already have the specified Role with a different Unique Identifier, in which case the row is rejected) Otherwise, a new `Member` AND `Member Role` are created using `:Email` and `:UniqueId` (as long as the system satisfies the conditions required to create new Member accounts³)	Yes	Yes	Yes³	Yes, if the `Member Role` already exists.

Identifying the Data Import Step and/or Workflow Action

The Workflow Import Queue uses the Workflow Engine to manipulate data, so every row of an uploaded file must be associated with a specific Workflow Action on a specific Data Import Step. These elements can be specified in the file itself, or they can be omitted and the system will use the configuration to determine what to do.

To explicitly specify a specific action, use :WorkflowActionName or :WorkflowActionId

Common scenarios

Scenario	Notes

Scenario

Notes

I want to import demographic data for people that may or may not already exist, storing that data in a Member Role.

I want to identify the people by their Email address.

Configure a Data Import Step on the Grant Role Workflow
- Include a single “Save” action
- Configure a “Update Owner Profile” Behavior to set the First Name and Last Name for newly-created people
- Configure a “Update Member Role Attribute” Behavior to set the Is Granted status of the Role to “True”
File must include a :Email column containing the person’s email. This will be used to link to or create a Member.
File must include a :RoleName or :RoleId column that identifies the relevant Role
File must include a :UniqueId column and it cannot be left empty