The plug-in interface for IReplaceCourseTemplateHandler is used by IPSIS Adapters to support the replace operation for course templates.
The interface implementation is D2L.IM.IPSIS.OrgUnits.CourseTemplates.Handlers.IReplaceCourseTemplateHandler.
The following configuration lists provide a starting point for any IPSIS implementation:
IPSIS, Template - Course Template
ReplaceCourseTemplateRetainExistingDepartmentHandler
The ReplaceCourseTemplateRetainExistingDepartmentHandler checks if the request does not have a parent department specified. If yes, the handler keeps any existing department parents when updating the template (as opposed to deleting all parents).
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateRetainExistingDepartmentHandler
Expected behavior
The handler performs the following tasks:
- Checks to see if there is no parent specified in the request.
- If there is no parent specified, the handler attempts to get the current org unit (in order to check if the request is an update).
- If the current org unit is valid, for each parent in request.CurrentParents, the handler adds the parent to request.UpdatedParents. For each parent in the ParentOrgUnits of the current org unit, the handler adds the parent to request.ParentOrgUnits
- Proceeds to the next 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 must be configured before any Read handlers, and thus should be configured first.
ReplaceCourseTemplateReadHandler
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateReadHandler
Expected behavior
The handler performs the following tasks:
- Attempts to read information about the course template from the IM tables.
- If found, attempts to read any mappings to Brightspace for the course template.
- If found, attempts to read about the course template from Brightspace.
- Checks to see if a parent department is specified in the request. If a parent department is specified, the handler adds the parent to the ParentOrgUnits of the request. If a parent department is not specified, the org is set as the parent for the request (in request.ParentOrgUnits).
- If a parent is specified but it doesn't have IM mappings in the database, the Read handler throws a ParentNotFoundException and all handler processing stops.
- Processing proceeds to the next handler.
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 the first of the handlers, unless the ReplaceCourseTemplateRetainExistingDepartmentHandler is configured. In that case the Read handler should be the second handler.
ReplaceCourseTemplateValidateHandler
The ReplaceCourseTemplateValidateHandler is intended to ensure that the minimum required information is available for the Create handlers.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateValidateHandler
Expected behavior
The handler performs the following tasks:
- The Validate handler checks to ensure that both a code and name are specified for the request. The code and name values must be strings of length greater than 0. If either the code or the name are null or empty, the Validate handler throws an ArgumentNullException and all handler processing stops.
- Processing proceeds to next handler.
Error behavior
If there is a problem during processing, an exception is thrown, along with as much detailed information as possible.
Configuration notes
- The Read handlers should occur before the Validate handler.
- This handler should be configured to run before the Create handlers.
ReplaceCourseTemplateParentsNoUpdateLMSHandler
When a ReplaceTemplateRequest is processed through IPSIS, the ReplaceCourseTemplateParentsNoUpdateLMSHandler retrieves
custom org units above the course template and preserves this relationship even if they were not created through IPSIS so that it is not overwritten by the update operation.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateParentsNoUpdate
LMSHandler
Expected behavior
The handler performs the following tasks:
- The handler fetches all parents of the course template and updates the parent list
- Processing proceeds to next handler
Error behavior
- No errors are thrown in this handler
Configuration Node
- This handler must occur after the Read and Validate handlers
- This handler must occur before the Save handlers
ReplaceCourseTemplateDisallowParentChangesIfChildrenExistHandler
The ReplaceCourseTemplateDisallowParentChangesIfChildrenExistHandler can be used to prevent deleting or swapping a parent department for any template that already has children. In the absence of this handler, parents may be freely updated, which might alter the hierarchy information for ancestors and descendants of the current template.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateParentDepartmentValidateHandler
Expected behavior
The handler performs the following tasks:
- If the template already exists (replace instead of create):
- If a parent OrgUnit will be removed or replaced, the handler throws an exception to prevent any further handlers from running.
Configuration notes
- This handler should be configured to run after the Validate handlers.
- This handler should be configured to run before the Create handlers.
ReplaceCourseTemplateParentDepartmentValidateHandler
The ReplaceCourseTemplateParentDepartmentValidateHandler can be put into place to catch the scenario when a parent department is not provided for the template.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateParentDepartmentValidateHandler
Expected behavior
The handler performs the following tasks:
- If no parent department is found, the handler checks that the Form Element, Create Course > Department, has IsRequired set to false.
- If it is set to true, the handler throws an Invalid Config Variable Exception indicating instructions on how to resolve.
Configuration notes
- The Read handler should occur before the Validate handler.
- The Validate handler should be configured to run before the Create handlers.
ReplaceCourseTemplateCreateLMSHandler
The ReplaceCourseTemplateCreateLMSHandler creates the course template in Brightspace.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateCreateLMSHandler
Expected behavior
This handler only runs if there are no existing Brightspace course templates associated with the request. The handler performs the following tasks:
- If a parent department is not specified, then the new template has the org set as its parent. This causes an error if the course department Form Element is not configured properly. In Form Elements, check that Create Course > Department the IsRequired flag is set to false in order for the create to succeed.
- The handler creates the course template using the information passed in the request (triggering automatic Create Template audit logging).
- If the Create task is successful, the handler sets ReplaceRequestStatus = EntityCreated.
- Processing proceeds to next handler.
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 is placed after any Validate handlers.
- This handler is placed before Create IM handlers.
ReplaceCourseTemplateCreateIMHandler
The ReplaceCourseTemplateCreateIMHandler creates the Entity in the IM tables, and a mapping if one is defined.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateCreateIMHandler
Expected behavior
This handler only runs if there is no matching ExternalOrgUnitInfo and/or mapping in the IM tables. The handler performs the following tasks:
- Creates the course template in the IM Platform.
- Creates the IM Hierarchy entries.
- If there is a Brightspace OrgUnit associated with the request, the handler creates the IM Platform course template mapping to the Brightspace course template.
- If everything is successful, the handler sets ReplaceRequestStatus = EntityCreated.
- Processing proceeds to the next handler.
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 is placed after the CreateLMS handler.
- Not configuring ReplaceCourseTemplateCreateIMHandler or ReplaceCourseTemplateSaveIMHandler is legitimate. Without creating IM table entries, IPSIS doesn't know if the template exists in the Brightspace. A mapping handler should be configured that maps the SIS request to the Brightspace template allowing for updates. Without a mapping handler, IPSIS always creates a new template even if a matching one existed.
ReplaceCourseTemplateSaveLMSHandler
The ReplaceCourseTemplateSaveLMSHandler saves any changes that have been made to the Brightspace course template.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateSaveLMSHandler
Expected behavior
This handler only runs if there are changes to be saved for the Brightspace course template. The handler performs the following tasks:
- Updates the Brightspace course template (triggering automatic Update Template audit logging).
- If everything is successful, if ReplaceRequestStatus != EntityCreated, the handler sets ReplaceRequestStatus = EntityUpdated.
- Processing proceeds to the next 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 is placed after any Create handlers.
ReplaceCourseTemplateSaveIMHandler
The Save handler saves any changes that have been made to IM Entity and mappings. This includes updating the hierarchy information, and propagating changes to all ancestors and descendants of the given template.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateSaveIMHandler
Expected behavior
This handler only runs if there are changes to be saved for the Entity or mappings in the IM tables. The handler performs the following tasks:
- Updates the IM Entity.
- Updates the IM Hierarchy and updates relationship information for any parents and children affected.
- Updates the IM Entity Mappings.
- If everything is successful, the handler sets ReplaceRequestStatus = EntityUpdated.
- Processing proceeds to next handler.
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 is placed after the SaveLMS handler.
- Not configuring ReplaceCourseTemplateCreateIMHandler or ReplaceCourseTemplateSaveIMHandler is legitimate. Without creating IM table entries, IPSIS doesn't know if the template exists in Brightspace. A mapping handler should be configured that would map the SIS request to the Brightspace template allowing for updates. Without a mapping handler, IPSIS always creates a new template even if a matching one existed.
ReplaceCourseTemplateValidateLMSOrgUnitExistsHandler
The ReplaceCourseTemplateValidateLMSOrgUnitExistsHandler checks to see if the org unit that the request corresponds to has been deleted in Brightspace.
Implementation
D2L.IM.IPSIS.Default.OrgUnits.CourseTemplates.Handlers.ReplaceCourseTemplateValidateLMSOrgUnitExistsHandler
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 Brightspace, 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 Brightspace, and an UpdateOrgUnitFailedException is thrown.
- This exception causes the LIS Service to respond with invaliddata. This was deemed to be the most suitable response code for this situation.
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 placed after the Read handlers, usually as one of the first Validate handlers.