Creating Import Queue templates for Member Role Import
Overview
The https://heuristicsolutions.atlassian.net/wiki/spaces/DOCS/pages/1462567021 feature allows users to import a file containing Member and Member Role data into LearningBuilder.
There are many different business scenarios that can be implemented with this feature, and the specific outcome of processing a given row depends on the columns in the file and the data in that row.
To ensure that users upload the correct data, configurators will typically construct a template file containing the columns that should be uploaded.
This document provides guidance on creating those template files.
Getting started: which operations do you want to perform?
Each row in an uploaded file will trigger one of four operations:
Update an existing
Member RoleAdd a new
Member Roleto an existingMemberAdd a new
Member, and then add a newMember Roleto itReject the row with an error message
Therefore, the first thing you need to do is decide which of the possible operations do you want your file to perform:
Do you want to bulk modify a bunch of
Member Rolesthat you know will exist?Do you expect the
Memberrecords to always exist, and you only want to add or updateMember Rolerecords?
Having a clear (and detailed) outcome in mind will make the rest of the process easier.
Choose the “identifier columns” your file will use
Columns in the file that begin with a colon (“:”), such as :Email, have special meaning to the system. They are “identifier” columns and they are used to figure out which operation will be performed for a given row of the file.
Member Role identifier columns
Unless you want to use the internal LearningBuilder MemberRoleId field, your file will need to contain these columns:
Column | Notes |
|---|---|
| The Unique Identifier associated with the Member Role record |
| The name of the Role. (Generally, UniqueId values are unique within a Role, so Unique Id + Role Name is sufficient to find an existing record) |
| The label to associate with a Multi-Instance Role to difference the Required for Multi-Instance Roles, ignored otherwise |
If a Member Role exists matching these values, it will be processed as an update Member Role operation.
Member identifier columns
When no existing Member Role is available for update, LearningBuilder next attempts an add Member Role operation using the Member Identifier columns.
These columns tell the system how to locate the Member that will receive the newly added Member Role. There are two primary identifier columns that you can choose from:
Column | Notes |
|---|---|
| Used when email addresses are unique within a Member Type, e.g. when it is guaranteed that no two People will have the same email address. |
| Used when Unique Identifier values can uniquely identify a Person. (For more information see Understanding how :MemberNumber works ) |
Our guidance
Use :Email when email addresses are a RELIABLE unique identifier
Use this column as the Member Identifier when:
Email addresses are guaranteed to be unique (within a Member Type),
AND the party generating the data file uses the same email addresses as LearningBuilder.
The second point is important; if the person or system assembling the data file might use a different email address than is used in LearningBuilder, then you may end up with unwanted duplicates or rejections.
Use :MemberNumber by itself -UNLESS- you need to create new Members
If Email isn’t a reliable “key”, and you know that every row in your file will map to an existing Member, then use :MemberNumber and omit :Email.
If a Member Role exists matching :UniqueId and :RoleName it will be updated.
If not, a new Member Role will be created for the Member with any Member Role matching :MemberNumber.
If no such person exists, the row is rejected; new Members will NOT be created.
Use both :Email and :MemberNumber if you pay attention to the business rules!
If you include both Member Identifier columns then things get a little complicated.
In very rough terms, this is what happens:
If
:MemberNumberand:Emailboth exist in the system, for differentMembers, then the row is rejected. In this case the system cannot tell which one to use and so it aborts.If exactly one
Membermatches:MemberNumberOR:Email, then it is used even though it doesn’t match the other identifier. This rule exists to avoid the creation of duplicate records.If zero
Membersmatch either:MemberNumberor:Email, then a newMemberis created (as long as the relevant Import Step is configured to do so).
Creating new Member records
In order to create a new Member your file must include the :Email identifier column, which is used as the email address if a new record is created.
Additionally, the Workflow Action that gets triggered must include an “Update Owner Profile” Workflow Behavior that contains mappings for the First Name and Last Name fields for a Person, or the Member Name field for an Organization. These mappings tell the system how to populate required Member fields when creating the new record.
Identify the Workflow Action you want to perform
The Import Queue is a Workflow-centric feature. Every row of an uploaded file is mapped to a specific Workflow Action on a specific Data Import Step that is triggered by the import.
Before you can create your template, identify the Workflow Action that you want to be performed against each uploaded row.
Once you know the Action, you need to decide how to tell the system which Action you selected.
There are two ways for this mapping to occur:
Your file can explicitly specify a
:WorkflowActionNameor:WorkflowActionIdcolumn, ORThe system can try to figure it out dynamically
Add columns for each Workflow Attribute on the Import Step
Once the system has identified the Member Role to update (or created a new one), it will perform the relevant Workflow Action.
This includes:
Updating the Member Role Workflow Attributes to match the data columns in the file;
Executing the target Action (and any Behaviors it includes)
Your file should include columns for each of the editable Attributes on your target Step. If any of those Attributes are marked as required, but the uploaded file does not contain a value, that row will be rejected.
Save your template in .csv format
Now that you have a complete file template, save it as .csv format.
Your users are welcome to open the file in Excel if they need to enter data by hand, they just need to save the file as .csv when finished.
Attach it to the “File Type” configuration
Go to Admin → Data Import → File Types and attach your .csv file to the relevant File Type. It will then become available to end users.