Member Role Import
- Seth Petry-Johnson
- Sarah Willis
- Peter Fasano
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 RolesAdd new
Member Rolesto existingMembersAdd new
MemberandMember Rolecombinations
The Workflow Import Queue can also update Member information by attaching an Update Owner Profile Behavior to the Action that is performed.
Limitations and constraints
Member Role Import does not assign system-generated Unique Identifiers
The Member Role Import feature will not assign a system-generated Unique Identifier. If you intend to create new Member Roles via import, the data file must contain the identifier to assign to them. If you include the :UniqueId column, but leave it blank, you will get errors.
Additionally, if you assign your own Unique Identifier values in the import file, you must make sure that those IDs will not conflict with a yet-to-be-auto-generated ID in the future, because this will result in that future generated ID being a duplicate.
A feature proposal has been identified to support system-generated identifiers; please contact support if you have a use case for that ability.
Cannot create new Members with multiple Member Roles in a single file
Multiple new Member Roles can be added to an existing Member in a single file, but a file cannot contain multiple Member Roles for a Member that does not already exist.
To handle that situation, upload one file to create the Member records (or use legacy Profile Upload) and then add all of the remaining Member Role records in a second file.
Key concept: Member and Member Role identifier columns
Understanding this section is key to a successful implementation of this feature! Please be sure to understand the nuances of the file formats and which business rules they support.
Additional supporting information: Workflow Import Queue (a.k.a. "Enhanced Data Import") | CSV file conventions
Each row in an uploaded file can result in a different operation being taken, depending on its data:
Update an existing
Member RoleAdd a new
Member Roleto an existingMemberAdd a new
Member, and then add a newMember Rolefor 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 | Inserts new |
|---|---|---|---|
| Updates existing records based on an internal ID. | Yes | No |
| Updates existing records based on the Unique Identifier and Role Name. | Yes | Yes |
1 :RoleId can be provided instead of :RoleName. If both are provided, they both must match the existing record.
2 :RoleLabel is required when the target Role supports multiple instances. It is optional (and ignored, if provided) for single-instance Roles.
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 |
|---|---|---|---|
1 |
| Matches an existing | No |
2 |
| Matches a See below for a detailed explanation of how this field works. If | No (But can be combined w/ |
3 |
| Identifies a When combined with Member Role identifiers, email matching is always restricted by the Role Type of the target This will only match primary email; alternate email addresses are not used for Member identification purposes. | 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 | ||
|---|---|---|
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 | ||
|---|---|---|
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:
:MemberNumber to add a new Role to an existing MemberWhen a row including :MemberNumber is used to create a new Member Role, the new Member Role is assigned a unique identifier that matches :UnqiqueId.
:MemberNumber is only used to find an existing Member, it is not used to assign any new values.
Important rule governing :UniqueId, :MemberNumber, and :Email
This section documents changes introduced in LearningBuilder 11.0.22.
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:
:UniqueId, but different :EmailIn 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.
In this scenario, the Primary Email of the existing Member record is NOT updated; it is left as-is in the database.
If :UniqueId points to Member 1, and :Email is in use by Member 2, then the row will be rejected instead. In this case the data row is referencing inconsistent Member and Member Role data and is considered invalid.
If :UniqueId does NOT point to an existing Member Role, then :Email will be used to locate (or create) a Member the same as it works in other scenarios.
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.
Confused by all of this? See https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/3515482271 for some guidance on how to choose a format.
Identifier columns | Notes / Purpose | Update | Insert | Insert | Supports multiple |
|---|---|---|---|---|---|
| Updates existing | Yes | No | No | Yes |
| Updates existing This is useful when the people relating to your input will already exist, but may or may not have the desired
In some configurations, the same Unique Identifier value is given to all In those configurations, the New | Yes | Yes | No | Yes |
| Can perform any of the three possible operations, using Unique Identifier or Email to identify existing records. As of release 11.0.22 this can be used when Email Address is NOT a reliable identifier, such as when incoming data is from different systems that may have different email addresses for the same practitioner. In those scenarios, the If The identifiers are “OR’ed” together in this sequence: If an existing If an existing If NO existing
* Checks for Cannot contain multiple Roles for the same Member unless that Member already exists. The system cannot create a new Member and then add multiple Roles to it in the same file. | Yes4 | Yes | Yes3 | Yes, if the |
| 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.
Requires that email address is a “reliable unique identifier”. All uploaded data files must refer to people and organizations using the Primary Email Address for that record in LearningBuilder. Cannot contain multiple Roles for the same Member unless that Member already exists. The system cannot create a new Member and then add multiple Roles to it in the same file. | Yes | Yes | Yes3 | Yes, if the |
1 :RoleId can be provided instead of :RoleName. If both are provided, they both must match the existing record.
2 :RoleLabel is required when the target Role supports multiple instances, and is optional (and ignored) otherwise.
3 Requirements for creating new Members
In order to create a new Member, all of the following conditions must be met:
The file must contain an
:EmailcolumnThe Member Role workflow has Extrinsic fields to capture at least the imported
First NameandLast Name(if the target Role is a “Person” type Role), orMember Name(for Orgs)The
Workflow Actionthat gets executed must have an “Update Owner Profile” BehaviorThat Behavior contains mappings from those extrinsic attributes for at least
First NameandLast Name(if the target Role is a “Person” type Role), orMember Name(if the target role is for an “Organization”).
Without this configuration, the system will not be able to satisfy the minimum requirements for creating a new Member, and the file row will be rejected.
4 What happens if multiple Member Identifiers are included in the file?
There are special business rules that apply to the use of :UniqueId, :MemberNumber, and :Email in the same file.
In order to avoid creating unwanted duplicate accounts, :UniqueId and :RoleName are sufficient to update an existing Member Role even if the existing record does not match :Email, as long as :Email does not already belong to a different Member. In this case, it is assumed that the data file is using an outdated email address and the existing matching Member Role is still updated.
If the Member Role identifiers cannot uniquely identify a single record to update, the row will be rejected.
See the table above for more details.
Identifying the Data Import Step and/or Workflow Action
All Import Steps should be configured on Grant Role Workflows. Edit Role Workflows do not support this feature.
Typically, you will want to ensure that the “Perform step in terminal state” feature is enabled for the Step in question, so that it will be able to modify an existing Member Role when the Grant Role Workflow Instance is in a Completed state.
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 |
|---|---|
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. |
|
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 This requires that a Unique Identifier can be used to uniquely identify a |
|
|