Member Role Import

Owned by Seth Petry-Johnson
Last updated: Sept 25, 2023 by Sarah Willis
12 min read

This page describes how Member Role data are imported via the Workflow Import Queue (a.k.a. "Enhanced Data Import"), which is accessible at Admin → Import Data.

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

This is different than the legacy Member Profile Upload feature. See Member / Member Role Import (DRAFT) 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.

Overview

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

This feature uses Data Import Steps 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”.

https://lucid.app/lucidchart/2c174ffd-d672-4da0-a90d-d6b6e503379c/edit?viewport_loc=-239%2C-5%2C2904%2C1497%2C0_0&invitationId=inv_a0b15b2c-d470-42c4-9329-f8b07d01e3d7

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 +
:RoleName1 [+ :RoleLabel2]

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:

Priority1

Identifier Column

Purpose

Can insert new
Member?

Priority1

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

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

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? 3

Supports multiple Member Roles for the same Member in a single file?

Identifier columns

Notes / Purpose

Update
Member Role?

Insert
Member Role?

Insert
Member? 3

Supports multiple Member Roles for the same Member in a single file?

:UniqueId +
:RoleName1 [+ :RoleLabel2]

Updates existing Member Roles using the Unique Identifier.

Yes

No

No

Yes

:UniqueId +
:RoleName1 + :RoleLabel2 +
: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 +
:RoleName1 + :RoleLabel2 +
: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)

Yes4

Yes

Yes3

Yes, if the Member Role already exists.

:UniqueId +
:RoleName1 [+ :RoleLabel2] +
: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 accounts3)

Yes

Yes

Yes3

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

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 Unique Identifier.

Same as above, except use :MemberNumber instead of :EmailAddress.

This requires that a Unique Identifier can be used to uniquely identify a Member, even if it does not uniquely identify a specific Role held by that person.

 

 

Related pages

Workflow Import Queue (a.k.a. "Enhanced Data Import")
Workflow Import Queue (a.k.a. "Enhanced Data Import")
LearningBuilder Documentation
Read with this
Learning Plan Instance Import
Learning Plan Instance Import
LearningBuilder Documentation
Read with this