# D2L Brightspace LMS Integration Guide

# 1\. How it works

Integration of the proctoring system and D2L Brightspace is performed through the [External Learning Tool (LTI)](<https://www.1edtech.org/standards/lti>) and Supervisor SDK (JS proctoring library). First, you need to place the custom SDK code on one of the HTML pages in the LMS, and then configure the LTI in the course module to enter proctoring through the LMS.

# 2\. Setting up a quiz element

In the course module, you must have created a Quiz element to which you want to connect proctoring.

Go to the "Content" section, enter the Quiz element and click the "Quiz Setup" button. In the settings in the right panel, in the "Availability Dates &amp; Conditions" section, in the "Password" field, specify a custom password to restrict access to the element:

![Quiz settings with the Password field highlighted under Availability Dates &amp; Conditions](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/01-quiz-settings-password-field.png>)

Next, you need to open this Quiz element and copy the URL from the browser's address bar:

![Quiz page with its URL highlighted in the browser address bar](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/02-quiz-page-url-in-address-bar.png>)

# 3\. Upload the proctoring script

Next, you need to place a special script for launching proctoring on the course page. You will be redirected to this page after successful user authorization via LTI.

Save the code below to the `proctoring.html` file on your computer:

```
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Proctoring</title>
</head>
<body>
  <p>There is nothing here. This is a service page for proctoring.</p>
  <script>
    (function (host) {
      var w = parent;
      var script = document.createElement('script');
      script.setAttribute('src', `https://${host}/sdk/supervisor.js`);
      script.dataset.supervisor = 'sync';
      script.onload = function () {
        w.supervisor.on('load', function (iframe) {
          var d = iframe.contentDocument;
          d.querySelectorAll('iframe').forEach(function (subframe) {
            subframe.addEventListener('load', function () {
              var pathname = subframe.contentWindow.location.pathname;
              if (pathname.endsWith('/quiz_submissions.d2l')) {
                w.supervisor.stop();
              }
            }, false);
          });
        });
      };
      w.document.body.style.overflow = 'hidden';
      w.document.body.appendChild(script);
    })('demo.proctoring.app');
  </script>
</body>
</html>
```

> **NOTE:** you need to replace "demo.proctoring.app" with the domain of your proctoring server!

Go to the "Resources" section and select "Upload / Create" → "Upload Files":

![Module content with the Upload / Create menu open and Upload Files highlighted](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/03-upload-create-menu-upload-files.png>)

In the "Add a File" dialog that opens, select the `proctoring.html` file from your computer and click the "Upload" button, and then the "Add" button:

![Add a File dialog with proctoring.html ready to be added](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/04-add-a-file-dialog-proctoring-html.png>)

After this, a new element "proctoring" (Web Page) will appear on the "Content" page of the course. Go inside this element and copy the URL from the browser's address bar:

![Proctoring web page with its URL highlighted in the browser address bar](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/05-proctoring-page-url-in-address-bar.png>)

# 4\. Creating an LTI Link

Now you need to add External Learning Tools to the course page through which participants can begin proctored assessment. Go to section "Course Administration → External Learning Tools" → "LTI Advantage Manage Tool Links (Legacy)" and press the "New Link" button:

![External Learning Tools page, Manage Tool Links (Legacy) tab, with the New Link button](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/06-external-learning-tools-new-link.png>)

In the dialog that opens, enter the following parameters:

| **Field** | **Value** |
| --- | --- |
| Title | Proctoring (or any other name) |
| URL | `https://demo.proctoring.app/api/auth/d2l?redirect=<proctoring.html>`<br>where `<proctoring.html>` should be changed to the full URL of the page from Section 3, and `demo.proctoring.app` with the domain of your proctoring server. If the address contains `?`, `&`, `#` or `+`, URL-encode it before inserting it, otherwise the parameter is cut or changed. |
| Signature | Link key/secret |
| Key | LTI key from your proctoring server |
| Secret | LTI secret from your proctoring server |
| Custom Parameters (Name = Value) | \- template = `default`<br>\- members = `@`<br>\- url = `<quiz_url>`<br>\- code = `<quiz_password>`<br>where `<quiz_url>` should be changed to the full URL of the quiz and `<quiz_password>` to the quiz password from Section 2. |
| Security Settings | Use link security settings (check all options) |

After filling in all the parameters, save the settings with the "Save" button. Return to the "Content" section of the course and add a new element to the module using the "Existing Activities" → "External Learning Tools" button:

![Existing Activities menu with External Learning Tools highlighted](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/07-existing-activities-external-learning-tools.png>)

In the dialog that opens, select the previously created LTI Link:

![Add Activity dialog listing the Proctoring LTI link](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/08-add-activity-proctoring-lti-link.png>)

After the "Proctoring" link is added to the course module, you will need to go to its settings through the "Edit properties in Place" menu and enable the "Open as External Resource" checkbox:

![Module with the Proctoring tool and the Open as External Resource checkbox highlighted](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/09-open-as-external-resource-checkbox.png>)

# 5\. Starting a proctoring session

After these steps, you will have at least three elements in your course module:

1. Quiz - the assessment itself, access to which is locked with a password
2. proctoring (Web Page) - the service page `proctoring.html` with a proctoring launch script (does not open directly).
3. Proctoring (External Learning Tools) - external tool page for launching a proctoring session.

![Module with the Quiz, proctoring page and Proctoring tool, the last marked as the entry point](<https://docs.octoproctor.com/integrations/d2l-brightspace/images/10-module-proctoring-entry-point.png>)

The learner should begin taking the proctored assessment by clicking on the "Proctoring (External Learning Tools)" link. If a user with a different role (for example, administrator or teacher) clicks on this link, they will be taken to the monitoring interface for all sessions that were started by learners using the same link.

# 6\. Setting up a proctoring host

To connect the integration API with D2L Brightspace LMS, you need to load the following config with integration parameters under the proctoring system manager:

```
{
  "id": "<Host_ID>",
  "key": "<License_Key>",
  "params": {
    "webhooks": {
      "d2l": {
        "strategy": "lti",
        "consumerKey": "demo",
        "consumerSecret": "secret",
        "callbackURL": "query.redirect",
        "profile": {
          "username": "payload.user_id",
          "role": "payload.roles.find(v => /Instructor/.test(v)) ? 'proctor' : 'student'",
          "nickname": "payload.lis_person_name_full",
          "lang": "(payload.launch_presentation_locale || '').slice(0, 2)",
          "group": "['G', payload.context_id, payload.resource_link_id].join('-')",
          "referrer": "payload.launch_presentation_return_url",
          "labels": "payload.lis_person_contact_email_primary"
        },
        "register": {
          "identifier": "[payload.user_id, payload.context_id, payload.resource_link_id].join('-').replace(/[^A-Za-z0-9_-]+/g, '_')",
          "template": "payload.custom_template || 'default'",
          "subject": "payload.resource_link_title",
          "members": "payload.custom_members === '@' ? user.group : payload.custom_members",
          "url": "payload.custom_url || payload.launch_presentation_return_url",
          "tags": "payload.lis_person_contact_email_primary",
          "code": "payload.custom_code"
        },
        "start": true,
        "stop": true,
        "pause": true,
        "submit": true,
        "iframe": {
          "sandbox": ""
        }
      }
    }
  }
}
```

> **NOTE:** the fields `consumerKey` and `consumerSecret` need to be replaced with a randomly generated sequence of characters (Latin letters of different case and numbers, the recommended length is 24 characters); `id` is the ID of the host (if you do not specify it, a new host will be created); `key` is the license key of this host.
>
> **NOTE:** the `iframe` parameter of the provider sets the `allow` and `sandbox` attributes of the frame where the assessment opens. The empty `sandbox` removes all the restrictions of the frame, which D2L Brightspace needs for its assessments. Without the `iframe` parameter, the frame has the default restrictions.
