Table of Contents

Objectives

This entry describes how to approach the process of adding Activity Instances to LearningBuilder. It helps navigate the various configuration option available to import accomplishments into the system.

Background

The Attendance Upload feature was designed to allow organizations to add Activities to Practitioners' Learning Plans electronically. The feature reduces the administrative burden of Activity reporting on the Practitioner by adding the Activities electronically. It is intended to support organizations that want to report attendance electronically but may not have the wherewithal to implement an integration.

We describe the feature as “Attendance Upload,” because the dominant use case is to record continuing education activity on a Practitioner’s Learning Plan. However, it is also often used to record examination results for organizations who have not implemented an integration between their test administrator and LearningBuilder.

Professional Development Activities vs Examination Results

Reporting Activity attendance and exam results are structurally similar, but do have some nuances. Examinations have a special set of attributes that treat results differently than other Activities. Because examinations have consequences for passing and failing, the system recognizes details about those statuses. The rules governing pass and fail results mostly affect duplicate prevention. Because we know Members may fail examinations multiple times but only pass them once, the system has special scenarios to govern duplicates. Please see the Duplicates Prevention section below for additional details.

Functional Details

Attendance Upload has the following components:

• An XML file that defines the data requirements for an upload file

• A CSV template to define the file properties

• A set of system rules to govern how to place the Activity Instance on the correct Learning Plan and in the correct Task Group and to manage duplicates

The following sections describe each of these functional areas in greater detail.

XML Requirements Definition

The format of the CSV file can be configured by updating the ImportValidationRules.xml file.  Each column in the file is controlled by an <Import Rule> XML file.  The <Import Rule> node requires the following parameters:

• Name - This is the internal element in LearningBuilder that the column should map to.  One rule is required for each of these values.  

  • ActivityId - The ID of the activity on which the attendance is being reported (Required must be "true" or Default must be provided for upload to work).

  • CompletionDate - The completion date of the activity (Required must be "true" or Default must be provided for upload to work).

  • GrantedUnits - The granted units to give to the practitioner for this activity.

  • RequestedUnits - The requested units to give to the practitioner for this activity. 

  • UniqueId - The Unique ID of the practitioner (Required must be "true").

  • FirstName - The first name of the practitioner (optionally used to validate the person in conjunction with the "FirstNameMatch" assertion below; new in Release 8.4)

  • LastName - The last name of the practitioner (optionally used to validate the person in conjunction with the "LastNameMatch" assertion below; new in Release 8.4)

  • CycleEndDate - The cycle end date of the learning plan on which to add the activity (new in Release 8.4)

  • CycleEndYear - The year of the cycle end date of the learning plan on which to add the activity (new in Release 8.4) 

  • RoleName - Used to locate the correct learning plan to which to add the activity.

  • WorkflowCompletionStatus - The ending status to which to set the activity instance workflow.

  • LearningPlanName - The name of the learning plan on which to add the activity.

  • TaskGroupName - The name of the task group on which to add the activity.

• Label - This is the column header in the CSV file that has the data that corresponds to the internal element.

• MustInclude - If set to "true," the CSV file header row must have this column or the file will be rejected.

• Required - If set to "true," the CSV file must have a value in this column for every record.

• Ignore - If this is set to "true," the system will ignore this column in the file.  This is needed when files contain columns not used by LearningBuilder.  This data will not be stored anywhere in LearningBuilder and this is not available on the Provider Attendance Search Page.

• Default - If this is set, any blank value in this column will be set to this value.  If the column is not included in the file (MustInclude = "false") then LearningBuilder will use this value.

• IsExtrinsic - Must be set to "true" when additional validation rule is being used on an extrinsic field.

• MaxLength - If this is set, LearningBuilder will reject the file if any value in this column exceeds the length specified.

• DataType - must be "ShortText;" not used.

• GlossaryOverride - If set to "true" and the Label matches a glossary term, the value of glossary term will be used for the label.  Note: Prior to 8.4.1, the UniqueID field (e.g. Practitioner ID) always used the glossary term.

• Object - must be "UploadedAttendance;" not used.

• FormOrder - If this is set to a value other than "0," this field will appear on the Attendance Entry page in the order specified.  If this number duplicates another field in the XML file, the order will be based on the position in the XML file.

• RetainData - If set to "true," the Attendance Entry Page will retain the data on the form after each submission.  This is helpful for fields that are likely to be the same between submissions.

• Example:  <ImportRule Name="ActivityId" Label="Activity Id" MustInclude="true" Required="true" Ignore="false" Default="" MaxLength="" DataType="ShortText" GlossaryOverride="false" Object="UploadedAttendance" FormOrder="1" RetainData="true" />

Additional validation rules can also be specified by adding an additional child <ImportAssertion Type> element within the <Import Rule> node.  The following import assertion types are supported:

• Range - A "Range" assertion validates that the uploaded value is between two fixed values.

  • This assertion can be applied to any numeric field and is evaluated by all processor types (not just the Attendance Upload Processor).

  • Example: <ImportAssertion Type="Range" MinValue="1.1" MaxValue="2.1" ErrorMessage="Value must be between 1.1 and 2.1" />

• DateRange - A "DateRange" assertion validates that the uploaded value is between two fixed dates.

  • This assertion can be applied to any date field and is evaluated by all processor types (not just the Attendance Upload Processor).

  • MinValue and MaxValue are both optional.  If omitted, that portion of the rule is omitted.

  • Example: <ImportAssertion Type="DateRange" MinValue="01/01/2010" MaxValue="01/01/2012" ErrorMessage="Date must be between 01/01/2010 and 01/01/2012" />

• EqualsActivityUnits - An "EqualsActivityUnits" assertion validates that the uploaded value is exactly equal to the number of Units assigned to the relevant Activity. 

  • This assertion is ONLY evaluated by the Attendance Upload processor.

  • If provided, the error message MUST contain a placeholder "{0}" for the Activity units value. [If the assertion fails, this is the value included in the error message].

  • Example: <ImportAssertion Type="EqualsActivityUnits" ErrorMessage="Value must equal the Activity Units which are {0}" />

• LessThanOrEqualsActivityUnits - A "LessThanOrEqualsActivityUnits" assertion validates that the uploaded value is less than or equal to the number of Units assigned to the relevant Activity. 

  • This assertion is ONLY evaluated by the Attendance Upload processor.

  • If provided, the error message MUST contain a placeholder "{0}" for the Activity units value. [If the assertion fails, this value is included in the error message].

  • Example: <ImportAssertion Type="LessThanOrEqualsActivityUnits" ErrorMessage="Value must be less than or equal to the Activity units which are {0}" />

• LessThanOrEqualsCurrentDate - A "LessThanOrEqualsCurrentDate" assertion validates that the uploaded value is less than or equal to the current date.

  • This assertion can be applied to any date field and is evaluated by all processor types (not just the Attendance Upload Processor).

  • Example: <ImportAssertion Type="LessThanOrEqualsCurrentDate" ErrorMessage="Date must be not be in the future." />

• GreaterThanOrEqualsActivityStartDate - A "GreaterThanOrEqualsActivityStartDate" assertion validates that the uploaded value is on or after the Start Date assigned to the relevant Activity. 

  • This assertion is ONLY evaluated by the Attendance Upload processor and only if the Activity End Date is set.

  • If provided, the error message MUST contain a placeholder "{0}" for the Activity Start Date value. [If the assertion fails, this is the value included in the error message].

  • Example: <ImportAssertion Type="GreaterThanOrEqualsActivityStartDate" ErrorMessage="Date cannot be before Activity Start Date which is {0}" />

• LessThanOrEqualsActivityEndDate - A "LessThanOrEqualsActivityEndDate" assertion validates that the uploaded value is on or before the End Date assigned to the relevant Activity. 

  • This assertion is ONLY evaluated by the Attendance Upload processor and only if the Activity End Date is set.

  • If provided, the error message MUST contain a placeholder "{0}" for the Activity End Date value. [If the assertion fails, this is the value included in the error message].

  • Example: <ImportAssertion Type="LessThanOrEqualsActivityEndDate" ErrorMessage="Date cannot be after Activity End Date which is {0}" />

• GreaterThanOrEqualsCycleBeginDate - A "GreaterThanOrEqualsCycleBeginDate" assertion validates that the uploaded value is on or after the Cycle Begin Date of the learning plan.

  • If provided, the error message MUST contain a placeholder "{0}" for the Cycle Begin Date value. [If the assertion fails, this is the value included in the error message].

  • Example: <ImportAssertion Type="GreaterThanOrEqualsCycleBeginDate" ErrorMessage="Completion Date cannot be before Cycle Begin which is {0}" />

• LessThanOrEqualsCycleEndDate - A "LessThanOrEqualsCycleEndDate" assertion validates that the uploaded value is on or before the Cycle End Date of the learning plan. 

  • If provided, the error message MUST contain a placeholder "{0}" for the Cycle End Date value. [If the assertion fails, this is the value included in the error message].

  • Example: <ImportAssertion Type="LessThanOrEqualsCycleEndDate" ErrorMessage="Date cannot be after Cycle End Date which is {0}" />

• RoleEndDateGreaterThanOrEqualToCompletionDate - A "RoleEndDateGreaterThanOrEqualToCompletionDate" assertion validates that the person who was identified in the member data field on which this assertion is attached has a Role End Date that is greater than or equal to the Completion Date in the field.  

  • If provided, the error message MUST contain two placeholders, "{0}" and "{1}", for the Role End Date and Completion Date values, respectively. [If the assertion fails, this is the value included in the error message].

  • Example: <ImportAssertion Type="RoleEndDateGreaterThanOrEqualToCompletionDate" ErrorMessage="Instructor role expires on {0} which is prior to the course completion date [{1}]." />

• RoleBeginDateLessThanOrEqualToCompletionDate - A "RoleBeginDateLessThanOrEqualToCompletionDate" assertion validates that the person who was identified in the member data field on which this assertion is attached has a Role Begin Date that is less than or equal to the Completion Date in the field.  

  • If provided, the error message MUST contain two placeholders, "{0}" and "{1}", for the Role Begin Date and Completion Date values, respectively. [If the assertion fails, this is the value included in the error message].

  • Example: <ImportAssertion Type="RoleBeginDateLessThanOrEqualToCompletionDate" ErrorMessage="Instructor role was granted on {0} which is after to the course completion date [{1}]." />

• FirstNameMatch - A "FirstNameMatch" assertion validates that the first name of the practitioner provided in the file matches that already in the system.  

  • The "CharMatch" parameter limits the number of characters that are checked.  For example, if it is "1", the first name is considered a match if the first character matches, no matter the other characters.  Billy and Bob would be a match.

  • If provided, the error message MUST contact two place holders, "{0}" and "{1}", for the name in the file and on the system, respectively.

  • Example: <ImportAssertion Type="FirstNameMatch" CharMatch="1" ErrorMessage="Licensee First Name [{0}] doesn't match the name on file [{1}]." /> 

• LastNameMatch - A "LastNameMatch" assertion validates that the last name of the practitioner provided in the file matches that already in the system.  

  • The "CharMatch" parameter limits the number of characters that are checked.  For example, if it is "4", the last name is considered a match if the first four characters matches, no matter the other characters.  Smith and Smithy would be a match.

  • If provided, the error message MUST contact two place holders, "{0}" and "{1}", for the name in the file and on the system, respectively.

  • Example: <ImportAssertion Type="LastNameMatch" CharMatch="4" ErrorMessage="Licensee Last Name [{0}] doesn't match the name on file [{1}]." /> 

CSV Template

The CSV Template gives Providers and Administrators guidance on the fields to provide when providing results. Files must contain a minimum data set to establish the Member, Activity, and results. Files may also contain extrinsic attributes defined by the Activities.

The CSV templates must have the following fields:

• Course ID

• Unique ID

• First Name

• Last Name

• Completion Date

• Units

System Rules

LearningBuilder applies rules to ensure Activities end up in the right place. They include:

• Determine the Learning Plan to use

• Determine the Task Group to use

• Manage duplicate rules

Determine the Learning Plan to use

LearningBuilder identifies the Learning Plan to use as follows:

1. Limit the search to a specific Learning Plan definition if a Learning Plan Name was provided (or defaulted via the XML configuration).  If none was provided, all learning plans are considered.

2. Look for an Active Learning Plan whose dates correspond to the Activity Completion date, Cycle End Date, or Cycle End Year provided.

   • If a Cycle End Date or Cycle End Year is provided, use that to find a Learning Plan based on a matching Cycle End Date or Year.

   • If only a Completion Date was provided, use that to find a match are based on the Learning Plan Date Settings.

   • If more than one active learning plan is found, the system generates an error.

3. If none is found, it repeats this, looking for a matching Inactive Learning Plan.

Determine the Task Group to use

The system looks for the first Task Group that allows the Activity Type in question. LearningBuilder will use the “Restrict to Specific Activity Types” setting on each Task Group to determine eligibility.

LearningBuilder uses the position starting with top to determine which Task Group to use.

If no Task Groups allow the Activity Type of the Activity to upload, the system generates an error.

Duplicate Prevention Rules

To prevent Administrators from inadvertently uploading duplicate Activities, LearningBuilder imposes several rules governing duplicates. If the possibility of duplicates is a concern, the system manages them as follows:

• Set the Allow Duplicates to Yes.

With this setting in place, LearningBuilder will manage duplicates with the following criteria: