The plug-in interface for IReplaceEnrollmentHandler is used by IPSIS Adapters to support the replace operation for Enrollments.
The interface implementation is D2L.IM.IPSIS.OrgUnits.Memberships.Handlers.IReplaceEnrollmentHandler.
The following configuration lists for the ReplaceEnrollmentHandler Interface are shipped with the product. They are listed along with the Extension point they are intended for.
IPSIS, Template - Enrollments
- ReplaceEnrollmentReadIMHandler (Sort Order = 10)
- ReplaceEnrollmentStatusDefaultActiveHandler (Sort Order = 20)
- ReplaceEnrollmentValidateSectionHandler (Sort Order = 30)
- ReplaceEnrollmentCreateIMEnrollmentHandler (Sort Order = 40)
- ReplaceEnrollmentSaveIMEnrollmentHandler (Sort Order = 50)
- ReplaceEnrollmentEnrollLMSOfferingHandler (Sort Order = 60)
- ReplaceEnrollmentEnrollLMSGroupSectionHandler (Sort Order = 70)
- ReplaceEnrollmentUnenrollLMSGroupSectionHandler (Sort Order = 80)
- ReplaceEnrollmentUnenrollLMSOfferingHandler (Sort Order = 90)
Background, Template - Background
- ReplaceEnrollmentUnenrollLMSGroupSectionHandler (Sort Order = 10)
- ReplaceEnrollmentEnrollLMSGroupSectionHandler (Sort Order = 20)
- ReplaceEnrollmentUnenrollLMSOfferingHandler (Sort Order = 30)
- ReplaceEnrollmentEnrollLMSOfferingHandler (Sort Order = 40)
ReplaceEnrollmentReadIMHandler
The ReplaceEnrollmentReadIMHandler is expected to get all relevant information from the DB from the IM tables.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentReadIMHandler
Expected behavior
To Brightspace, an enrollment is simply a link between an OrgUnit, a User, and a Role. The ReadIM handler expects to be passed in SIS identifiers for each of those entities, which it uses to look up the associated Role, User, and OrgUnit objects in both the IM and LMS tables.
The handler performs the following tasks:
- Reads the IExternalOrgUnitInfo for the given SIS OrgUnit. Fail with an exception if the ExternalOrgUnitInfo is not found (mandatory).
- Reads the Role Mapping for the given SIS Role, selecting the first if more than one is passed in. Fail with an exception if the Role Mapping is not found (mandatory).
- Reads the User Mapping for the given SIS User. Fail with an exception if the User Mapping is not found (mandatory)
- If this is an update to an existing SIS enrollment, the handler reads the IEnrollmentMapping. If no Enrollment Mapping is found, the request creates a new one.
- If an Enrollment Mapping is found, the handler validates that the User in the request matches the User in the existing enrollment.
- Reads the IOrgUnitMappings if any exist. If no OrgUnit Mapping is found, the handler logs a message and continues. There may be valid use cases where we only update the IM tables.
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration note
The Read handler is typically configured first in the list.
ReplaceEnrollmentValidateSectionHandler
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentValidateSectionHandler
Expected behavior
The expected behavior for this handler is to validate that the current enrollment request is for a course section or group.
Error behavior
If the enrollment is not for a course section or group an InvalidOrgUnitTypeException is thrown.
Configuration note
This handler should be configured before ReplaceEnrollmentCreateIMEnrollmentHandler handler.
ReplaceEnrollmentKeepLMSCreatedEnrollmentsOnUnenrollValidateHandler
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentKeepLMSCreatedEnrollmentsOnUnenrollValidateHandler
Expected behavior
The expected behavior for this handler is to validate that the current enrollment request corresponds to an enrollment record that originated from an SIS request (not a manual Brightspace enrollment).
Error behavior
If the enrollment record originated in the Brightspace (ex. the user was first enrolled manually in Brightspace, and then the SIS sent a replaceMembership for the same user and org unit), the handler throws a UserManuallyEnrolledInLMSException.
Configuration note
This handler must be configured before the ReplaceEnrollmentCreateIMEnrollmentHandler, but after the ReplaceEnrollmentReadIMHandler.
ReplaceEnrollmentCreateIMEnrollmentHandler
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentCreateIMEnrollmentHandler
Expected behavior
The expected behavior for this handler is to create Enrollment Records in the IM database tables if they do not already exist. For each Enrollment object in the creation list on the request, if no IM Mapping exists, then IM_ENROLLMENTS is updated.
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration note
This handler should be configured after the Read and Validate handlers.
ReplaceEnrollmentEnrollLMSGroupSectionHandler
The ReplaceEnrollmentEnrollLMSGroupSectionHandler enrolls users in sections or groups that are mapped in Brightspace.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentEnrollLMSGroupSectionHandler
Expected behavior
The handler performs the following tasks:
- For each Active Enrollment Object in the list of enrollments to be updated, if the User is not yet enrolled in the Section/Group, the handler enrolls the User (automatically resulting in an audit entry).
- If the User is already enrolled in the Section/Group with a different Role, the handler unenrolls the User and re-enrolls with the new Role (automatically resulting in an audit entry).
- If the User is already enrolled in the Section/Group with the same Role, the handler does nothing.
- Processing continues to the next handler (Return True).
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration notes
- This handler should be configured after the SaveIM handler.
- This handler must be configured before the Enroll and Unenroll LMSOffering handlers.
- This handler should not be configured at the same time as ReplaceEnrollmentEnrollLMSGroupSectionRoleNoUpdateHandler.
ReplaceEnrollmentEnrollLMSOfferingHandler
The ReplaceEnrollmentEnrollLMSOfferingHandler enrolls users in offerings in Brightspace.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentEnrollLMSOfferingHandler
Expected behavior
The handler performs the following options:
- For each Active Enrollment Object in the list of enrollments to be updated, if the User is not yet enrolled in the Offering, the handler enrolls the User in the Course Offering (automatically creating an audit entry).
- If the User is already enrolled in the Offering with a different Role, the handler unenrolls the User and re-enrolls them with the new Role (automatically resulting in an audit entry).
- If the User is already enrolled in the Offering with the same Role, the handler does nothing.
- Processing continues to the next handler (Return True).
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration notes
- This Handler should be configured after the EnrollLMSGroupSection Handler.
- This handler should not be configured at the same time as ReplaceEnrollmentEnrollLMSOfferingRoleNoUpdateHandler.
ReplaceEnrollmentSaveIMEnrollmentHandler
The ReplaceEnrollmentSaveIMEnrollmentHandler saves any changes to the enrollment in the IM Tables, including status and Role. It also creates a list of Enrollments that need to be updated.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentSaveIMEnrollmentHandler
Expected behavior
The handler performs the following tasks:
- Updates the Role and Active/Inactive status of the current IM enrollment and saves changes to the database if anything differs from its original value.
- Creates a list of enrollments that need to be updated. A single IM enrollment might map to multiple enrollments if the OrgUnitMappings are not one-to-one.
- Processing proceeds to next available handler.
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration note
- This handler should occur after the CreateIMEnrollment handler.
- This handler should occur before the Enroll and Unenroll LMS handlers.
ReplaceEnrollmentEnrollLMSGroupSectionRoleNoUpdateHandler
The ReplaceEnrollmentEnrollLMSGroupSectionRoleNoUpdateHandler creates or updates the enrollment in the section/group, but won't update the role if it already has one. This handler enrolls users in sections or groups in Brightspace if they're not already. It does not alter existing enrollments.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentEnrollLMSGroupSectionRoleNoUpdateHandler
Expected behavior
The handler performs the following tasks:
- For each Active Enrollment Object in the list of enrollments to be updated, the handler enrolls the User in the Brightspace Section or Group (automatically creating an audit entry).
- Processing continues to the next handler (Return True).
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration notes
- This handler should be configured after SaveIMEnrollment handler.
- This handler should be configured before the EnrollLMSOffering handler.
- This handler should not be configured at the same time as ReplaceEnrollmentEnrollLMSGroupSectionHandler.
ReplaceEnrollmentEnrollLMSOfferingRoleNoUpdateHandler
The ReplaceEnrollmentEnrollLMSOfferingRoleNoUpdateHandler creates or updates the enrollment in the course offering, but doesn't update the role if it already has one. The handler does not alter existing enrollments.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentEnrollLMSOfferingRoleNoUpdateHandler
Expected behavior
The handler performs the following tasks:
- For each Active Enrollment Object in the list of enrollments to be updated, the handler enrolls the User in the Course Offering (automatically creating an audit entry).
- Processing continues to the next handler (Return True).
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration note
- This handler should be configured after the EnrollLMSGroupSection handler.
- This handler should not be configured at the same time as ReplaceEnrollmentEnrollLMSOfferingHandler.
ReplaceEnrollmentStatusDefaultActiveHandler
The ReplaceEnrollmentStatusDefaultActiveHandler defaults the enrollment status to Active if it is null.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentStatusDefaultActiveHandler
Expected behavior
The handler performs the following tasks:
- If the status is currently null, the handler sets the status to Active.
- Otherwise, this handler is skipped and does not alter the existing status.
Error scenarios
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration notes
- This handler should be configured after Read handler.
- This handler should be configured before the CreateIM and SaveIM handlers.
ReplaceEnrollmentStatusDefaultInactiveHandler
This handler defaults the enrollment status to inactive if it is null.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentStatusDefaultInactiveHandler
Expected behavior
The handler performs the following tasks:
- If the status is currently null, the handler sets the status to Inactive.
- Otherwise, this handler is skipped and does not alter the existing status.
Configuration notes
- This handler should be configured after Read handler.
- This handler should be configured before the CreateIM and SaveIM handlers.
ReplaceEnrollmentUnenrollLMSGroupSectionHandler
The ReplaceEnrollmentUnenrollLMSGroupSectionHandler removes enrollments from Brightspace Groups and Sections.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentUnenrollLMSGroupSectionHandler
Expected behavior
This handler unenrolls users from sections if they are no longer supposed to be enrolled. The handler performs the following tasks:
- For each Inactive Enrollment Object in the list of enrollments to be updated, if the OrgUnit is an LMS Course Section or LMS Group, the handler unenrolls the user from the Section or Group (Automatically resulting in an audit entry) and sets RequestStatus = EntityDeleted.
- Otherwise, the handler skips it and continue to the next enrollment.
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration note
UnenrollLMSGroupSection should occur after Validate and before UnenrollLMSOffering.
ReplaceEnrollmentUnenrollLMSOfferingHandler
The ReplaceEnrollmentUnenrollLMSOfferingHandler removes enrollments from Brightspace offerings.
Implementation
D2L.IM.IPSIS.Default.Enrollments.Handlers.ReplaceEnrollmentUnenrollLMSOfferingHandler
Expected behavior
This handler unenrolls users from offerings in the Brightspace if they're no longer supposed to be enrolled. It only unenrolls users from offerings if they are no longer enrolled in any sections in the offering.
The handler performs the following tasks:
- For each Enrollment Object in the Deletion list, if it is no longer an active enrollment, and user is not enrolled in any other sections of the same Offering, the handler unenrolls the user from the Course Offering (Automatically resulting in an audit entry) and sets RequestStatus = EntityDeleted.
- Otherwise, the handler skips it and continue to the next enrollment.
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration note
UnenrollLMSOffering should occur after the UnenrollLMSGroupSection handler.