The plug-in interface for IReplaceSectionAssociationHandler is used by IPSIS Adapters as well as the Section Association UI to support the replace operation for Section Associations.
For the typical configuration, a SectionAssociation Request is turned into an Offering in Brightspace. The Sections get hung off the Offering. The Offering inherits some properties, including Template parent, from the first Section in the list.
The interface implementation is D2L.IM.IPSIS.OrgUnits.SectionAssociations.Handlers.IReplaceSectionAssociationHandler.
The following configuration lists provide a starting point for any IPSIS implementation:
IPSIS, Template - Sections
- ReplaceSectionAssociationReadHandler (Sort Order = 10)
- ReplaceSectionAssociationPropertiesDefaultFirstSectionHandler (Sort Order = 20)
- ReplaceSectionAssociationValidateHandler (Sort Order = 30)
- ReplaceSectionAssociationCreateLMSOfferingHandler (Sort Order = 40)
- ReplaceSectionAssociationCreateIMHandler (Sort Order = 50)
- ReplaceSectionAssociationAddLMSSectionHandler (Sort Order = 60)
- ReplaceSectionAssociationUnenrollLMSGroupSectionHandler (Sort Order = 70)
- ReplaceSectionAssociationUnenrollLMSOfferingHandler (Sort Order = 80)
- ReplaceSectionAssociationRemoveLMSGroupSectionHandler (Sort Order = 90)
- ReplaceSectionAssociationSaveLMSOfferingHandler (Sort Order = 100)
- ReplaceSectionAssociationSaveIMHandler (Sort Order = 110)
IPSIS, Template - Groups
- ReplaceSectionAssociationReadHandler (Sort Order = 10)
- ReplaceSectionAssociationPropertiesDefaultFirstSectionHandler (Sort Order = 20)
- ReplaceSectionAssociationValidateHandler (Sort Order = 30)
- ReplaceSectionAssociationCreateLMSOfferingHandler (Sort Order = 40)
- ReplaceSectionAssociationCreateIMHandler (Sort Order = 50)
- ReplaceSectionAssociationAddLMSGroupHandler (Sort Order = 60)
- ReplaceSectionAssociationUnenrolLMSGroupSectionHandler (Sort Order = 70)
- ReplaceSectionAssociationUnenrolLMSOfferingHandler (Sort Order = 80)
- ReplaceSectionAssociationRemoveLMSGroupSectionHandler (Sort Order = 90)
- ReplaceSectionAssociationSaveLMSOfferingHandler (Sort Order = 100)
- ReplaceSectionAssociationSaveIMHandler (Sort Order = 110)
SA, Template - Sections
This endpoint is used by the Section Association User Interface when associations require creating or updating LMS Sections:
SA, Template - Groups
This endpoint is used by the Section Association User Interface when associations require creating or updating LMS Groups:
- ReplaceSectionAssociationAddLMSGroupHandler (Sort Order = 10)
- ReplaceSectionAssociationUnenrolLMSGroupSectionHandler (Sort Order = 20)
- ReplaceSectionAssociationUnenrolLMSOfferingHandler (Sort Order = 30)
- ReplaceSectionAssociationRemoveLMSGroupSectionHandler (Sort Order = 40)
ReplaceSectionAssociationReadHandler
The Read handler gets a large amount of information from IM and LMS tables and adds it to the request message so that later handlers may use it.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationReadHandler
Expected behavior
The handler performs the following tasks:
- Reads the Section Association from the IM Tables if it exists.
- Reads the Section Association Hierarchy from the IM Tables if it exists.
- Reads the Section Association Mappings from the IM Tables if it exists. If there are no mappings, the handler does not create or delete any sections from the LMS. Any changes to sections (add/remove) happen in the IM Tables only.
- Reads the Course Sections from the IM Tables for the Course Sections in the Association.
- Prepares a list of Sections to add. These consist of sections missing in the hierarchy that are part of the current request.
- Prepares a list of Sections to remove. These consist of extra sections in the hierarchy that are not part of the current request.
- If the mapping for the sections being removed can be determined, the handler includes the mapping.
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 is typically going to be the first handler as it is the default Read handler.
ReplaceSectionAssociationPropertiesDefaultFirstSectionHandler
If any Section Association Properties are not set to a non-null value, set them to those of the First Section in the Association List. The properties that are set if missing include the Name, Status, Dates, and Parent list.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationPropertiesDefaultFirstSectionHandler
Expected behavior
This handler only takes action the first time the Section Association is received by IPSIS (i.e., it doesn't exist in the IM Tables).
The Section Association Properties are set from those specified in the IM Tables for the first Section in the Association List if they were not previously set:
- Name
- Status
- Start Date
- End Date
- Parent List (taken from the first Offering parent of the first section, includes Templates and/or Semesters)
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 is typically configured prior to any validate and create handlers.
ReplaceSectionAssociationValidateHandler
This handler ensures that the minimum required information is available to create a Course Offering for the Section Association.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationValidateHandler
Expected behavior
This handler throws an appropriate exception if any of the following values are not set:
- Name
- Code
- Status
- Course Template Parent (new Associations only)
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 is typically configured prior to any validate and create handlers.
ReplaceSectionAssociationCreateLMSOfferingHandler
The ReplaceSectionAssociationCreateLMSOfferingHandler creates an LMS Course Offering for the Section Association if this is the first time the Section Association has been seen.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationCreateLMSOfferingHandler
Expected behavior
This handler only runs if there is no record of this Section Association in the IM Tables. The handler performs the following tasks:
- Creates an LMS Course Offering Org Unit (automatically resulting in an audit entry).
- If everything is successful, the handler sets the status of the result to EntityCreated.
- If there is an error, the handler sets the status of the result to CreateFailed.
- 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 placed after the validate handler.
- This handler should be placed before the Create IM handler.
ReplaceSectionAssociationCreateIMHandler
The ReplaceSectionAssociationCreateIMHandler creates an IM Section Association, and maps it to the appropriate LMS entity, if any.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationCreateIMHandler
Expected behavior
This handler only runs if there is no record of this Section Association in the IM Tables. The handler performs the following tasks:
- Creates an IM Section Association Record.
- If an OrgUnit is created in the LMS for the Section Association, the handler creates the Mapping.
- If everything is successful, the handler sets the status of the result to EntityCreated.
- 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 placed after the validate handler.
This handler should be placed before the Create IM handler.
ReplaceSectionAssociationAddLMSSectionHandler
The ReplaceSectionAssociationAddLMSSectionHandler creates an LMS Course Section for the associated Sections defined in the Add Section List.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationAddLMSSectionHandler
Expected behavior
The handler performs the following tasks:
- Creates an LMS Course Section Org Unit (automatically resulting in an audit entry).
- Creates an IM Mapping record for the section and the newly created Org Unit.
- 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 placed after the Create IM handler.
This handler should be placed before the Save IM handler.
ReplaceSectionAssociationAddLMSGroupHandler
The ReplaceSectionAssociationAddLMSGroupHandler creates an LMS Course Group for the associated Sections defined in the Add Section List.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationAddLMSGroupHandler
Expected behavior
The handler performs the following tasks:
- Gets the value in d2l.integration.IPSIS.GroupCategory.
- If the value is not set, the handler throws an InvalidConfigurationVariableException.
- If an LMS Group Category matching the name in d2l.integration.IPSIS.GroupCategory does not exist, the handler creates an LMS Group Category with a name and description from the config variable (triggering a create group audit entry).
- If LMS Group Category creation is not successful, the handler throws an exception with an explicit indication of the problem and section identifier.
- Creates an LMS Course Group Org Unit with the GroupType (automatically resulting in an audit entry).
- Creates an IM Mapping record for the section and the newly created Org Unit.
- 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 placed after the Create IM handler.
- This handler should be placed before the Save IM handler.
- This handler provides an alternative to ReplaceSectionAssociationAddLMSSectionHandler.
ReplaceSectionAssociationUnenrolLMSGroupSectionHandler
The ReplaceSectionAssociationUnenrolLMSGroupSectionHandler unenrolls users from any sections that are to be removed from the association.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationUnenrolLMSGroupSectionHandler
Expected behavior
This handler only runs if there are associated sections (with a mapping) to be removed from the LMS. The handler performs the following tasks:
- Determines which users are enrolled in the Section (from the IM Enrollments Table).
- Unenrolls the users from the LMS Course Section or LMS Group that is to be removed (automatically resulting in 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 placed after the Create IM handler.
- This handler should be placed before the DeleteLMSGroupSection handler to ensure that no LIS-initiated enrollments remain in the LMS entity when it is deleted.
- This handler should be placed before the Save IM handler.
ReplaceSectionAssociationUnenrolLMSOfferingHandler
The ReplaceSectionAssociationUnenrolLMSOfferingHandler unenrolls users from the offering parents of the deleted section mapping unless they are enrolled in another group/section with the same group type under the offering.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationUnenrolLMSOfferingHandler
Expected behavior
This handler only runs if there are associated sections (with a mapping) to be removed from the LMS. The handler performs the following tasks:
- Determines which users are enrolled in the Section (from the IM Enrollments Table).
- If the user is not enrolled in any other Sections (or Groups) with the same group type, under the LMS Offering, the handler unenrolls the user from the LMS Course Offering that is the be removed (automatically resulting in 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 placed after the Create IM handler.
- This handler should be placed before the DeleteLMSGroupSection handler to ensure no enrollments remain in the LMS that shouldn't.
- This handler should be placed before the Save IM handler.
ReplaceSectionAssociationRemoveLMSGroupSectionHandler
The ReplaceSectionAssociationRemoveLMSGroupSectionHandler deletes the LMS Group or Section that is mapped to the Section being removed from the Section Association.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationRemoveLMSGroupSectionHandler
Expected behavior
This handler only runs if there are associated sections (with a mapping) to be removed from the LMS. The handler performs the following tasks:
- Deletes the LMS Group/Section (automatically producing an audit entry).
- Deletes the mapping for the LMS Group/Section.
- 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 placed after the Create IM handler.
- This handler should be placed after the Unenroll handlers to ensure that no LIS-initiated enrollments remain in the LMS entity when it is deleted.
- This handler should be placed before the Save IM handler.
ReplaceSectionAssociationUpdateHierarchyHandler
The ReplaceSectionAssociationUpdateHierarchyHandler saves any changes to the IM Section Association, IM Hierarchy, and mappings for the Section Association.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers. ReplaceSectionAssociationUpdateHierarchyHandler
Expected behavior
This handler only runs if there are changes to the IM Tables. The handler performs the following options:
-
Updates the IM Hierarchy if there are any updates to the section assignments:
-
Updates the IM Mappings for any new Group/Sections that were created or removed:
-
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 would typically run last.
ReplaceSectionAssociationSaveLMSOfferingHandler
The ReplaceSectionAssociationSaveLMSOfferingHandler saves any changes to any mapped LMS Offerings.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationSaveLMSOfferingHandler
Expected behavior
This handler only runs if there are mapped Offerings and any of the Offering Properties have changed. The handler performs the following tasks:
- Updates the LMS Course Offering (automatically resulting in an Audit Entry).
- If the status of the result is not EntityCreated, and at least one field was changed, set the status of the result to EntityUpdated.
- 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 placed after the Create IM handler.
- This handler should be placed after the add/remove group/section handlers.
- This handler should be placed before the Save IM handler.
ReplaceSectionAssociationSaveIMHandler
The ReplaceSectionAssociationSaveIMHandler saves any changes to the IM Section Association, IM Hierarchy, and mappings for the Section Association.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationSaveIMHandler
Expected behavior
This handler only runs if there are changes to the IM Tables. The handler performs the following options:
- Updates the IM Section Association Record.
- Updates the IM Hierarchy if there are any updates to the section assignments:
- All Add records should have new Sections to add as children to the Section Association.
- All Remove records should have Sections to remove as children of the Section Association.
- Updates the IM Mappings for any new Group/Sections that were created or removed:
- All Add records should have new mappings to add.
- All remove records should have mappings to remove.
- 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 would typically run last.
ReplaceSectionAssociationNameNoUpdateLMSOfferingHandler
The ReplaceSectionAssociationNameNoUpdateLMSOfferingHandler is used to prevent updates to the Name of the mapped LMS Offering after initial creation.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationNameNoUpdateLMSOfferingHandler
Expected behavior
This handler only runs if there is a mapping to an LMS Course Offering. The handler performs the following tasks:
- Updates the request object to indicate that the Name should not be updated.
- 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 would typically run after the read but before the SaveLMSOffering handler.
ReplaceSectionAssociationStatusNoUpdateLMSOfferingHandler
The ReplaceSectionAssociationStatusNoUpdateLMSOfferingHandler is used to prevent updates to the Status of the mapped LMS Offering after initial creation.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationStatusNoUpdateLMSOfferingHandler
Expected behavior
This handler only runs if there is a mapping to an LMS Course Offering. The handler performs the following tasks:
- Updates the request object to indicate that the Status should not be updated.
- 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 would typically run after the read but before the SaveLMSOffering Handler.
ReplaceSectionAssociationDatesNoUpdateLMSOfferingHandler
The ReplaceSectionAssociationDatesNoUpdateLMSOfferingHandler is used to prevent updates to the Start and End dates of the mapped LMS Offering after initial creation.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationDatesNoUpdateLMSOfferingHandler
Expected behavior
The handler performs the following tasks:
- Updates the request object to indicate that the StartDate and EndDate should not be updated.
- 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 typically run after the read but before the SaveLMSOffering handler.
ReplaceSectionAssociationSetMappingsIsGradableFalseHandler
The ReplaceSectionAssociationSetMappingsIsGradableFalseHandler is used to set the Is Gradable flag to false on the association between the section and course offering. That is, the original section will be left as the gradable section (if one is set).
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationSetMappingsIsGradableFalseHandler
Expected behavior
- Updates the request object to indicate that the Is Gradable flag should be set to false.
- 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 typically run after the read but before the SaveLMSOffering handler.
ReplaceSectionAssociationValidateLMSOrgUnitExistsHandler
The ReplaceSectionAssociationValidateLMSOrgUnitExistsHandler checks to see if the org unit that the request corresponds to has been deleted in the LMS.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.SectionAssociations.Handlers.ReplaceSectionAssociationValidateLMSOrgUnitExistsHandler
Expected behavior
The handler performs the following tasks:
- Tries to get the current org unit, if the current org unit does not exist (either the request is a create, or the org unit was deleted from the LMS), the handler tries to get the ExternalOrgUnitInfo for the request.
- If the ExternalOrgUnitInfo is valid, then this isn't a create, and the org unit was deleted from the LMS and the handler throws a UpdateOrgUnitFailedException.
- This exception causes the LIS Service to respond with invaliddata.
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 placed after the read handlers, usually as one of the first validate handlers.