The plug-in interface for IReplaceUserHandler is used by IPSIS adapters to support the replace operation for users.
The interface implementation is D2L.IM.IPSIS.Users.Handlers.IReplaceUserHandler.
The following configuration list provides a starting point for any IPSIS implementation:
Template - User, IPSIS
- ReplaceUserReadIPSISHandler (Sort Order = 10)
- ReplaceUserReadLMSHandler (Sort Order = 20)
- ReplaceUserStatusDefaultActiveHandler (Sort Order = 30)
- ReplaceUserRoleDefaultFirstRoleHandler (Sort Order = 40)
- ReplaceUserValidateBaseHandler (Sort Order = 50)
- ReplaceUserCreateLMSHandler (Sort Order = 60)
- ReplaceUserCreateIPSISHandler (Sort Order = 70)
- ReplaceUserSaveLMSHandler (Sort Order = 80)
- ReplaceUserSaveIPSISHandler (Sort Order = 90)
- ReplaceUserSavePasswordPlainTextHandler (Sort Order = 100)
- ParentPortalCreateRelationshipHandler
ReplaceUserReadIPSISHandler
The ReplaceUserReadIPSISHandler populates the request object with information from the IM tables pertaining to the user indicated in the request.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserReadIPSISHandler
Expected behavior
The handler performs the following tasks:
- If the user was previously submitted, this handler first gets any existing data for this user, including mapping (UserId) from the IM tables.
- 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 note
A Read IPSIS handler should occur before a Read LMS handler.
ReplaceUserReadLMSHandler
The ReplaceUserReadLMSHandler populates the request object with information from the LMS tables pertaining to the user indicated in the request.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserReadLMSHandler
Expected behavior
The handler performs the following tasks:
- If the LMS Userid is available, the handler reads the existing LMS values for user properties.
- 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
A Read IPSIS handler should occur before a Read LMS handler.
ReplaceUserStatusDefaultActiveHandler
The ReplaceUserStatusDefaultActiveHandler defaults the status of the user to active if it was not previously set.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserStatusDefaultActiveHandler
Expected behavior
The handler performs the following tasks:
- Sets the status to Active if it was not previously set.
- 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 should be placed before the Validate handler.
ReplaceUserValidateBaseHandler
The ReplaceUserValidateBaseHandler ensures that the minimum required properties for the user have been set. These include the User Identifier, the Username, Role, and Status.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserValidateBaseHandler
Expected behavior
The handler performs the following tasks:
- Ensures that the following values set: Entity Identifier, Username, Role, and Status.
- If any of the values are not set, an ArgumentNullException is thrown with specifics of the missing value. The Adapter logs the specific exception message and returns a general error to the SIS.
- If the password is set to be updated, and the encryption type is an unsupported type, an InvalidDataException is thrown with specifics of the unsupported encryption type. The Adapter logs the specific exception message and returns a general error to the SIS.
- 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 should be placed before the first Create handler.
ReplaceUserCreateLMSHandler
The ReplaceUserCreateLMSHandler creates the user in the LMS if it doesn't already exist there.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserCreateLMSHandler
Expected behavior
The handler performs the following tasks:
- If there is not a valid LMS user object in the request, the handler creates the user in the Brightspace tables (triggering automatic audit logging).
- Enters the audit for create user if the user is created.
- 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 note
This should be placed before the IPSIS Create handler.
ReplaceUserCreateIPSISHandler
The ReplaceUserCreateIPSISHandler creates the user in the IM tables if it doesn't already exist there.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserCreateIPSISHandler
Expected behavior
The handler performs the following tasks:
- Creates the user in the IM Tables if it doesn't exist already.
- 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 should be placed after the LMS Create handler.
- This should be placed before the Save handlers.
ReplaceUserSaveLMSHandler
The ReplaceUserSaveLMSHandler saves any updates required to the LMS.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserSaveLMSHandler
Expected behavior
The handler performs the following tasks:
- If there are any user updates for the LMS, the handler saves them (triggering automatic audit logging).
- If there is a problem with the save, the status is set to Error.
- If everything is successful, the handler creates and updated user when data changes and sets ReplaceRequestStatus = 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 note
This should be placed after the Create handlers.
ReplaceUserSaveIPSISHandler
The ReplaceUserSaveIPSISHandler saves any updates required to the IM tables.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserSaveIPSISHandler
Expected behavior
The handler performs the following tasks:
- If there are any user updates for the IM tables, the handler saves them.
- 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 should be placed after the Create handlers.
ReplaceUserSavePasswordPlainTextHandler
The ReplaceUserSavePasswordPlainTextHandler saves the Plain Text Password to the LMS.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserSavePasswordPlainTextHandler
Expected behavior
The handler performs the following tasks:
- If there is a password that is provided in plain text, and it is identified as updated, the handler saves the password to the LMS. If the password is stored in any other encryption type, the handler does nothing.
- The handler creates an updated password audit entry.
- A handler should be configured for the specific encryption type.
- If the password was updated, and the status was not EntityCreated, then the status is set to EntityUpdated.
- Proceed 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 note
This should be placed after the Create handlers.
ReplaceUserRoleDefaultFirstRoleHandler
The ReplaceUserRoleDefaultFirstRoleHandler Defaults the primary role of the LMS user to the first role from the role list in the request, if one was not previously set.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserRoleDefaultFirstRoleHandler
Expected behavior
If a Primary Role has not been set, set it to the first role from the request role list, and proceed to the next handler.
If a Primary Role has not been set and the request role list is empty, this handler continues to the next handler without a defined primary role.
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 before the Validate handler.
- This handler populates the role in the IPSIS request object, and this role is used when creating/updating the LMS user. This handler should be configured if a role from the request should be applied to LMS users. Without this handler, the request role(s) are not used when creating/updating the LMS user.
- When used in conjunction with ReplaceUserRoleDefaultConfigVariableHandler, this handler should be placed before it if you ever want the role from the request set as the user's role. If you expect role information to be missing from the request, also configure ReplaceUserRoleDefaultConfigVariableHandler to follow this handler.
ReplaceUserRoleDefaultConfigVariableHandler
The ReplaceUserRoleDefaultConfigVariableHandler is used to set a role based on the d2l.Integrations.IPSIS.DefaultRole configuration variable if one was not previously assigned. The configuration variable is set to a Brightspace Role ID.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserRoleDefaultConfigVariableHandler
Expected behavior
The handler performs the following tasks:
- If a primary role has not been set, the handler sets it to the role found in d2l.Integrations.IPSIS.DefaultRole, and proceeds to the next handler.
- If a primary role has been set, the handler does nothing and 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.
- If the config variable is not configured, a RoleNotFoundException is thrown with the message "No default role is set for config value: d2l.Integrations.IPSIS.DefaultRole".
Configuration notes
- This should be placed before the Validate handler.
- This handler populates the role in the IPSIS request object, and this role is used when creating/updating the LMS user. This handler should be configured in one of two situations:
- LIS person requests always exclude a role. A role is necessary to create an LMS user.
- LIS person requests may sometimes, but not always, specify a role. Another handler, such as the ReplaceUserRoleDefaultFirstRoleHandler should be configured before this one to set the IPSIS request object role to the role from the request, thereby ensuring the user is created/updated with the role from the request. However, when the request is missing a role, this handler sets a role, and ensures the user can be created properly.
ReplaceUserUsernameFromEmailPrefixHandler
The ReplaceUserUsernameFromEmailPrefixHandler sets the Username to the Email Address prefix ( before the @ ) if a username is not already set.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUsernameFromEmailPrefixHandler
Expected behavior
If a username is not set, and there is a value in the email address, the sets the username to the email address prefix and 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 note
This handler is typically placed before Validation.
ReplaceUserUsernameGenerateHandler
The ReplaceUserUsernameGenerateHandler generates a Username using the LMS Username generation method if a username is not already set.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserUsernameGenerateHandler
Expected behavior
If a username is not set, generate one using the LP Username generation algorithm and proceed 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 note
This handler is typically placed as the last Username handler before Validation.
ReplaceUserUsernameFromEmailHandler
The ReplaceUserUsernameFromEmailHandler sets the username to the full email address if a username is not already set.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserUsernameFromEmailHandler
Expected behavior
The handler performs the following tasks:
- If a username is not set, and there is a value in the email address, the handler sets the username to the email address.
- The handler 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 typically placed before Validation.
ReplaceUserUsernameNoUpdateHandler
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserUsernameNoUpdateHandler
Expected behavior
The handler performs the following tasks:
- Updates the request object to indicate that the username should not be updated.
- 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 typically placed before the Create/Save handlers.
ReplaceUserFirstNameNoUpdateHandler
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserFirstNameNoUpdateHandler
Expected behavior
The handler performs the following tasks:
- Updates the request object to indicate that the First Name should not be updated.
- 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 typically placed before the Create/Save handlers.
ReplaceUserLastNameNoUpdateHandler
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserLastNameNoUpdateHandler
Expected behavior
The handler performs the following tasks:
- Updates the request object to indicate that the Last Name should not be updated.
- 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 note
This handler is typically placed before the Create/Save handlers.
ReplaceUserOrgDefinedIdNoUpdateHandler
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserOrgDefinedIdNoUpdateHandler
Expected behavior
The handler performs the following tasks:
- Updates the request object to indicate that the orgdefinedid should not be updated.
- 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 typically placed before the Create/Save handlers.
ReplaceUserPasswordNoUpdateHandler
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserPasswordNoUpdateHandler
Expected behavior
The handler performs the following tasks:
- Updates the request object to indicate that the password should not be updated in the LMS.
- 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 typically placed before the Create/Save handlers.
ReplaceUserRoleNoUpdateHandler
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserRoleNoUpdateHandler
Expected behavior
The handler performs the following tasks:
- Updates the request object to indicate that the role should not be updated in the LMS.
- 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 must be placed after a handler that sets the Brightspace Role in the request.
- This handler must be placed before the Create/Save handlers.
ReplaceUserMapByUsernameAndOrgDefinedIdHandler
The ReplaceUserMapByUsernameAndOrgDefinedIdHandler associates an SIS User with existing LMS Users by matching on Username and OrgDefinedId.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserMapByUsernameAndOrgDefinedIdHandler
Expected behavior
The handler performs the following tasks:
- If there is no existing user Mapping in the IM Tables, the handler attempts to find a user in the LMS that matches on both Username and OrgDefinedId.
- If a match is found, the handler updates the request object to contain the matched user. The match, if any, is always unique.
- Proceeds to the next handler.
Error behavior
- If a mapping already exists with the same username, but has a different sourcedId, a DuplicateUsernameException is thrown.
- 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 placed between the Read handlers and the Create handlers, in which case it only executes if the Read handlers fail to find a mapped OrgUser.
ReplaceUserMapByUsernameHandler
The ReplaceUserMapByUsernameHandler associates a SIS User with existing LMS Users by matching on Username.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserMapByUsernameHandler
Expected behavior
The handler performs the following tasks:
- If there is no existing user Mapping in the IM Tables, the handler attempts to find a user in the LMS that matches on Username.
- If a match is found, the handler updates the request object to contain the matched user. The match, if any, is always unique.
- Proceeds to the next handler.
Error behavior
- If a mapping already exists with the same username, but has a different sourcedId, a DuplicateUsernameException is thrown.
- 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 placed between the Read handlers and the Create handlers, in which case it only executes if the Read handlers fail to find a mapped OrgUser.
ReplaceUserMapByOrgDefinedIdHandler
The ReplaceUserMapByOrgDefinedIdHandler associates an SIS User with existing LMS Users by matching on OrgDefinedId.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserMapByOrgDefinedIdHandler
Expected behavior
The handler performs the following tasks:
- If there is no user Mapping and no OrgUser on the request message, the handler attempts to find a user in the LMS that matches on OrgDefinedId.
- If a match is found, the handler updates the request object to contain the matched user.
- There may be more than one match in the database, but platform only returns a single result. This handler should only be used if the OrgDefinedId is expected to be unique within an Org.
- Proceeds to the next handler.
Error behavior
- If a mapping already exists with the same username, but has a different sourcedId, a DuplicateUsernameException is thrown.
- 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 placed between the Read handlers and the Create handlers, in which case it only executes if the Read handlers fail to find a mapped OrgUser.
ReplaceUserRequirePasswordChangeOnCreateHandler
The ReplaceUserRequirePasswordChangeOnCreateHandler ensures that new users must change their password on first access.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserRequirePasswordChangeOnCreateHandler
Expected behavior
The handler performs the following tasks:
- Sets the flag on the request that is passed to the create handler, which marks the user as having to change the password at first login.
- 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 typically placed before the Create/Save handlers.
ReplaceUserStatusDefaultInactiveHandler
The ReplaceUserStatusDefaultInactiveHandler defaults the status to Inactive if a status is not provided.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserStatusDefaultInactiveHandler
Expected behavior
The handler performs the following tasks:
- Sets the status to Inactive if it was not previously set.
- 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 typically placed before Validation.
ReplaceUserVerifyConsistentSourcedIdHandler
The ReplaceUserVerifyConsistentSourcedIdHandler verifies that the request is not trying to give a new sourcedId to a user which is already mapped.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserVerifyConsistentSourcedIdHandler
Expected behavior
The handler performs the following tasks:
- If the request has no set D2LOrgUser, the handler does nothing.
- If an org user is set, the handler checks if there are any mappings for that user in the current system/org.
- If there are not, the handler does nothing.
- If there are mappings, the handler checks if the existing mapping sourcedId matches the request sourcedId.
- If they match, the handler does nothing.
- If they do not match, the handler throws a DuplicatedUsernameException to notify the SIS that it is trying to set a new sourcedId on an existing user.
Error behavior
If a user mapping already exists for the user, and it has a different sourcedId, the handler throws an exception.
Configuration note
This handler should be placed after a MapBy handler (such as ReplaceUserMapByUsernameHandler) to verify that user isn't already mapped to a different sourcedId. It should also be placed before the save/create handlers.
ReplaceUserUpdateIPSISSourcedIdForMatchedUserHandler
The ReplaceUserUpdateIPSISSourcedIdForMatchedUserHandler verifies that the request is not trying to give a new sourcedId to a user who is already mapped.
Implementation
D2L.IM.IPSIS.Default.Users.Handlers.ReplaceUserUpdateIPSISSourcedIdForMatchedUserHandler
Expected behavior
the handler performs the following tasks:
- If the request has no set D2LOrgUser, the handler does nothing.
- If an org user is set, the handler checks if there are any mappings for that user in the current system/org.
- If not there are no mappings, the handler does nothing.
- If there are mappings, the handler checks to see if the existing mapping sourcedId matches the request sourcedId.
- If they match, the handler does nothing.
- If they do not match, the handler checks to see if a user mapping already exists in the source system with the request's sourcedId.
- If the mapping exists, the handler throws a DuplicatedUsernameException to notify the SIS that it is trying to set a new sourcedId on an existing user, and that the sourcedId of the existing user cannot be changed to the new one due to conflict.
- If they don't match, the handler changes the sourcedId of the user in the mappings table to the one on the request and sets the UserMapping on the request to the now-renamed mapping.
Error beheavior
If a user mapping already exists for the user, and it has a different sourcedId AND the requested sourcedId is already in use, the handler throws an exception.
Configuration note
This handler should be placed after a MapBy handler (such as ReplaceUserMapByUsernameHandler) but before the save/create handlers. This handler should be used in place of the ReplaceUserVerifyConsistentSourcedIdHandler.