Collaborate with a D2L Implementation Consultant to set up and configure the IPSIS Platform in Brightspace.
Enable IPSIS Administration and IPSIS platform
Before you can assign IPSIS role permissions and access IPSIS Administration, you must turn on the IPSIS Administration and IPSIS Platform tools.
To enable IPSIS Administration and IPSIS platform
- From the Admin Tools menu, click Organization Tools.
- On the Tool Availability page, enable IPSIS Administration and IPSIS Platform.
Configure IPSIS role permissions for administrators
Tip: You can adjust these permissions for specific roles. For example, you can set a certain role to be able to do everything, but manage IPSIS admin configuration options. A super administrator may have all permissions, but an administrator may have only the following permissions: Access IPSIS Administration Console, Manage IPSIS Bulk Operations, and Subscribe to Batch Job Notifications.
To set up a user role and assign role permissions
- From the Admin Tools menu, click Roles and Permissions.
- Create or edit a role for administering IPSIS.
- From the Edit Permissions page, assign the following IPSIS Administration permissions:
Access IPSIS Administration console - allows users to see IPSIS Administration from the Admin Tools menu.
Manage IPSIS Bulk Operations - allows users to upload files for processing and review log and troubleshooting details of past runs.
View IPSIS Configuration Options - allows users to access the Configuration tab from IPSIS Administration.
Manage IPSIS Configuration Options - allows users to edit settings from the Configuration tab, including SFTP account management.
Subscribe to Batch Job Notifications - allows users to sign up for notifications when a batch job finishes.
- Assign the following additional permissions:
- User Information Privacy > See Usernames
- User Information Privacy > See Org Defined IDs
- Org Unit Type Editor > Can Create and Edit Org Unit Types
- Security > See Roles and Permissions
Important: For more information about the permissions an administrator requires to access IPSIS Administration and IPSIS Section Association, refer to the IPSIS Administration permissions and the IPSIS Section Association permissions topics respectively.
Handler interface roles and permissions
Role settings
The LIS Adapter uses the IPSIS Handlers to interact with Brightspace. The adapter requires a user account (and role) with permissions that allow the adapter access to the org hierarchy.
It is recommended that you create a new role the following options:
- Cascading Role: Enabled. The SIS user needs access to the entire org hierarchy. By having the user belong to a cascading role, the user is implicitly enrolled in every course. In some cases, enrollment, even an explicit one, is required to read various course properties or, for example, to read learner grades (for grade push/pull export).
- Tool Behavior Options: None selected. IPSIS and the SIS user do not require special tool permission.
- Class Display Options: None selected. Leaving these options unchecked ensures the SIS user does not appear in class lists.
- Course Access Options:
- Access inactive courses
- Access past courses
- Access future courses
- Access all course sections
- Access all course groups
Role permissions
When an IPSIS handler interacts with Brightspace, permissions are required for the user account interacting through the handler to Brightspace. These permissions would be equivalent to what they would need if an actual user were performing the same activity through the Brightspace User Interface.
The following permissions for the role are required:
|
Tool
|
Section
|
Permissions
|
|
Users
|
|
The User handlers currently do not require the user initiating the handler to have any specific Brightspace permissions.
|
|
Manage Courses
|
Organization
|
- Has Access to the Manage Courses tool
- Create Course Offerings and Templates
|
|
Manage Courses
|
Course Templates
|
- Has Access to the Manage Courses tool
- Create Course Offerings and Templates
- Delete Course offerings and Templates
- Change Locale
- Force Locale
- Change Name
- Change Code
- Change Course Path
- Change Parent Org Units
|
|
Manage Courses
|
Course Offerings
|
- Has Access to the Manage Courses tool
- Create Course Offerings and Templates
- Delete Course Offerings and Templates
- Change Locale
- Force Locale
- Change Name
- Change Code
- Change Course Path
- Change Start and End Dates
- Change Status
- Change Parent Org Units
|
|
Manage Courses
|
Course Sections
|
- Has Access to the Manage Courses tool
- Create Course Offerings and Templates
- Delete Course Offerings and Templates
- Change Locale
- Force Locale
- Change Course Path
- Change Parent Org Units
|
|
Manage Courses
|
Other Org Units (Departments, Semesters, Groups, etc.)
|
- Has Access to the Manage Courses tool
- Create Course Offerings and Templates
- Delete Course Offerings and Templates
- Change Locale
- Force Locale
- Change Course Path
- Change Parent Org Units
|
|
Course Management Console
|
|
|
|
Enrollments
|
|
The Enrollment handlers currently do not require the user initiating the handler to have any specific Permissions.
|
|
Grades
|
|
For a user to access the IPSIS Grades Export page in Brightspace and initiate exports of grades to an SIS, the user requires permissions at the course offering level.
- See the Grades Tool
- Enter Final Grades
- Export Grades
- Manage Grades
- Manage Final Grade Properties (not required if only sending released grades)
To support the exporting of grades data where the SIS connects to Brightspace and pulls out the grades data, the SIS user (associated with the IPSIS Source System) needs the appropriate Brightspace grades permissions at the course offering level:
- See the Grades Tool
- Manage Final Grade Properties
- Enter Final Grades
|
Configure source systems
A source system identifies a system to which IPSIS Platform may potentially communicate. Associated with a source system is information about the connection endpoint, access credentials, as well as details and status of integrations.
When a request is submitted to an adapter (LIS, for example), the request is authenticated using a username and password set up with the source system. The username is used to determine the source system that the request originated from. In order for this to work, you must configure your source system in the IPSIS Administration.
Note: For more information about source systems, refer to the Supported source systems heading in the About the IPSIS Platform topic.
Configure org unit type mappings
The Org Unit Type Mappings configuration is required on a per source system basis to tell the integration what kind of org unit types in Brightspace are affected when requests are received from Student Information Systems.
A mapping is required for each Org Unit Type that is going to be accepted from the SIS so that the implementation knows which corresponding Org Unit Type will be used in Brightspace. Each record is associated with a specific source system.
Configure role mappings
The Role Mappings configuration is required on a per source system basis to tell the integration which Brightspace roles correspond with the roles in the SIS integration messages.
A mapping is required for each role that is going to be accepted from the SIS so that the implementation knows which corresponding role will be used in the LMS. Each record is associated with a specific Source System.
For instructions on configuring role mappings, refer to Adding and editing role mappings.
Configure IPSIS handlers
IPSIS handlers and translators are plug-ins. While a minimum set of plug-ins are required for IPSIS to function, by definition, a plug-in extends the capabilities of a system. The set of plug-ins delivered with IPSIS provide baseline functionality for integrating with a SIS. New plug-ins can be created to customize the behavior of a system.
Plug-ins, whether standard ones or ones created for an organization to customize system behavior, are picked and executed at certain times and in a certain order. When interacting with a SIS, the system looks for a list of plug-ins that are associated with that particular interaction.
Note: Care should be taken when configuring plug-ins. When configured incorrectly, data loss may occur. Always consult your D2L Integration Consultant before making changes.
Configure authentication
IMessageAuthenticator plug-ins take care of inbound and outbound authentication, and can be configured on the Configuration page of the IPSIS Admin Interface using Extension Point: IM.IPSIS.Security.IMessageAuthenticator,D2L.IM.IPSIS.Security - IPSIS.
Unlike handlers or translators which run in a sequential order, Message Authenticators simply enable or disable certain types of authentication. For instance, if the WS-Security message authenticator is not configured, no inbound or outbound messages attempting to use WS-Security can function, resulting in errors. The same applies to the basic auth authenticator. There are no side-effects to having multiple authenticators configured at the same time, and doing so enables IPSIS to authenticate messages of either type at any particular time.
For inbound authentication, the system runs every configured authenticator against the message, trying to validate its credentials. If no authenticator can properly understand the security on the message, the system throws an error.
For outbound authentication, the system tries to find authenticators which use the authentication type configured on the endpoint itself. If none are found, the system throws an error.
Therefore, a client should enable all authenticators that any inbound or outbound messages may use.
Configure logging
Currently, logging configuration must be performed by a D2L implementation consultant or technical support representative.
IPSIS utilizes the Learning Platform Logging Framework for logging errors, information, and debugging data.
As a general rule, organizations should not run with any assemblies configured for Debug unless explicitly directed by D2L. This is because debug logging is typically very intensive and slows down performance, and might increase the size of the log database significantly. It is a good idea to use the Sessions and Users option to configure logging only for the Source System User for a limited number of logins to help perform these actions safely.
IPSIS uses the following business rules when determining the level to log a message under:
- Fatal: A Fatal log indicates a severe error to the D2L system, and is not a logging level that will be used in IPSIS.
- Error: An Error log indicates an error with the system that the administrator should investigate. An unexpected event has occurred that may indicate system misconfiguration, and prevent the integration from working correctly.
- Warning: A Warning log indicates a problem with processing a particular request, but does not necessarily mean there is a misconfiguration or problem with the system.
- Info: Info logging indicates regular processing in the system. In IPSIS, Info logging provides information about the ongoing status of the integrations, but can be disabled without preventing the integration from functioning correctly.
- Debug: Debug logging provides detailed information for troubleshooting and testing. Debug logging provides information about where the state of processing is within the application and a high level trail of what has happened. Debug logging should not be so detailed as to provide a full trace, but rather to provide direction in addressing configuration errors, resolving bugs, and reproducing issues.
Production configurations and assemblies
During initial setup and troubleshooting periods, organizations might wish to bump the logging level for the IPSIS Assemblies to DEBUG. If doing so, however, ensure you disable DEBUG before going live, and regularly purge/archive the logging tables to prevent major database growth.
Production configurations
The following is a reasonable configuration for production:
- Warn Level
- D2L.IM.IPSIS.Admin
- D2L.IM.IPSIS.Default
- D2L.IM.IPSIS.Security
- Info Level
- D2L.IM.IPSIS.LIS (provides info messages on each service call)
Assemblies
The following assemblies are directly related to IPSIS, therefore logging messages from these assemblies is reflected in the System Error Log in the IPSIS Administration Tool.
- IM Platform
- D2L.IM.Platform
- D2L.IM.Platform.Data
- D2L.IM.Platform.Logging
- IPSIS Administration
- IPSIS LIS v2.0 Adapter
- IPSIS Platform
- D2L.IM.IPSIS.Default
- D2L.IM.IPSIS.Security
- IPSIS Section Association
- D2L.IM.IPSIS.SectionAssociation
Add a logging configuration
The Brightspace Logging Configuration tool is a powerful troubleshooting tool, but because it is primarily instance-wide, configurations affect all orgs. Since logging is shown in the IPSIS user interface, adding extra debugging and troubleshooting for a single org bloats the logs for other orgs. Although this is not a problem on a test environment and during initial configuration, it can be a problem on production, and when deploying the integration to a new organization on an already-live system.
The best way around this is to use the Sessions and Users configuration, which allows you to be very explicit about when the extra logging is applied. For IPSIS, for example, you can specify the source system username and the org in order to get additional debug data in a production environment for a single org without bumping the level for everyone. This also ensures that it reverts to the default after a specified number of logins (max 99), eliminating the chance of forgetting to turn debugging off.
- From the
Admin Tools menu, click Logging Configurations.
- Click New Configuration.
- On the Sessions and Users page, select the Configure by username option.
- In the Username field, enter the username you have configured for IPSIS configuration.
- To apply the logging to current sessions, select the Apply to current sessions with this username checkbox.
- To set a number of logins that the current configuration is valid for, in the Future Logins field, enter a number.
- To select an org unit, click the Select Org Unit button.
- In the Logging Levels section, click the logging type you would like to use.
- Click Save.
Set IPSIS configuration variables
You must set the configuration variables for the IPSIS Platform. For more information, refer to the IPSIS heading of the Integrations configuration variables topic.
Form elements
Require departments for course templates
This change is required if you create Course Templates that are not assigned to a Department.
- Open Admin Tools and navigate to Form Elements > Create Course > Department.
- Set the IsRequired flag to false.
Require semesters for course offerings
This change is required if you create Course Offerings that are not assigned to a Semester.
- Open Admin Tools and navigate to Form Elements > Create Course > Semester.
- Set the IsRequired flag to false.
IPSIS message security
The IPSIS platform supports two security formats for message authentication:
- WS-Security
- Http Basic Authentication
The way these security formats are used depends on whether the LMS is sending or receiving the message.
Inbound messages
Security on inbound messages is handled by the IPSISMessageInspector extension point which intercepts all WCF calls that are submitted to our endpoints. Messages are inspected to see if a valid authentication token is included.
The supplied credentials are then authenticated against Brightspace to verify that they belong to a valid Brightspace user. Once the user is verified, the system checks if the user is linked to a source system in IPSIS. If the user is linked to a source system, the request proceeds and all changes are linked with that source system and user.
Plug-ins that implement the IMessageAuthenticator interface retrieve the credentials from the message. Currently, there are two implementations of the IMessageAuthenticator interface: one for WS-Security and one for Http Basic Authentication. The message inspector checks for all configured plug-ins for the IMessageAuthenticator interface and iterates through them until one of the plug-ins finds the credentials. Once a plug-in has found credentials, either the request is allowed through if the credentials are valid, or an InvalidUsernamePasswordException is thrown. Therefore, it's possible to have multiple plug-in authenticators configured at one time if there is a need to support different schemes.
WS-Security
Plug-in name: D2L.IM.IPSIS.Security.WSSEMessageAuthenticator
This plug-in checks for a WS-Security SOAP message header similar to:
Http basic authentication
Plug-in name: D2L.IM.IPSIS.Security.BasicAuthMessageAuthenticator
This plug-in checks for an Authorization header in the Http request headers similar to:
Where the value of the header is of the form:
"Basic " + Base64Encoded(username + ":" + password)
Outbound message
Outbound messages (i.e. messages being sent from Brightspace to the SIS) are secured using the authentication type specified by the endpoint. For example, when sending a bulk request, the bulk endpoint for the desired source system is retrieved and the authentication type specified on that endpoint is used. Just as on inbound messages, only WS-Security and Http Basic Auth are currently supported.