# OctoProctor Documentation > Guides for the OctoProctor proctoring system: user roles, product reference, use cases and step-by-step integrations with learning platforms. OctoProctor is a proctoring system that confirms the results of online assessments in learning platforms (LMS). These guides cover each user role (test-taker, proctor, administrator, manager), the product, use cases, and integrations with Blackboard, Canvas, D2L Brightspace, iSpring Learn, LearnDash, LearnWorlds, Moodle, Open edX, Sakai, any LTI-compliant LMS, SCORM and the WebSDK. # Overview # OctoProctor documentation This website is the documentation for the [OctoProctor]() proctoring system, which confirms the results of online assessments taken in learning platforms (LMS). It has guides for each user role, a product reference, use cases, and step-by-step integration guides with code snippets and host configuration for each supported platform. Pick a guide by who you are: - **Test-takers** take proctored assessments: start with the Test-taker's Guide. - **Proctors** watch sessions and review reports: start with the Proctor's Guide. - **Administrators** manage sessions, users and schedules: start with the Administrator's Guide. - **Managers** configure the host, licenses and integrations: start with the Manager's Guide, then the integration guide for your platform. ## For AI agents Every guide is also available as plain Markdown. Use [llms.txt]() as an index of the guides, [llms-full.txt]() to read all of them in one file, or add `index.md` to a page address (for example `https://docs.octoproctor.com/integrations/websdk/index.md`) to get a single guide. ## User guides - [Test-taker's Guide]() - [Proctor's Guide]() - [Administrator's Guide]() - [Manager's Guide]() ## Product - [Frequently Asked Questions]() - [OctoProctor Features List]() - [OctoProctor system installation and upgrade Guide]() ## Use cases - [Use case for Google Forms and Microsoft Forms]() - [Safe Exam Browser implementation Guide]() - [Use case without integration]() ## Integrations See the [integrations index](). # Integrations Each integration folder holds its guide (`README.md`) and its screenshots (`images/`). - [Blackboard LMS Integration Guide]() - [Canvas LMS Integration Guide]() - [D2L Brightspace LMS Integration Guide]() - [iSpring Learn LMS Integration Guide]() - [LearnDash LMS Integration Guide]() - [LearnWorlds LMS Integration Guide]() - [LTI-compliant LMS Integration Guide]() - [Moodle LMS Integration Guide]() - [Open edX LMS Integration Guide]() - [Sakai LMS Integration Guide]() - [SCORM LMS Integration Guide]() - [SCORM Player Guide]() - [WebSDK-based Integration Guide]() # User guides # Administrator's Guide # 1\. System assignment The proctoring system is designed to confirm the results of online assessments when passing assessments in Learning Management Systems (LMS). OctoProctor Proctoring System allows you to: - remotely supervise and support the participant throughout the assessment; - verify the identity of the test-taker; - identify any possible violations during the assessment and calculation of a credibility score; - record each session, form complete reports, including sound, webcam and desktop videos; - resolve possible controversial points after the assessment, based on the session protocol. # 2\. Technical requirements There are no special technical requirements for the administrator's PC or laptop. You need just any updated web browser, but Chrome 92+ is recommended. # 3\. Logging in to the system To enter the proctoring system, open its URL in your web browser and type in your login and password. To access the administrator interface, the user must be given the appropriate rights. ![Proctoring system login page]() When logged in, the top panel of the interface contains language switching, full screen mode, settings and the exit buttons. There is the navigation menu on the left side. And there is a section selected in the menu in the central part. To avoid problems with time display, make sure that the time and time zone on your computer are set correctly. If Two-factor authentication (2FA) is enabled for the profile a user will be required to enter a one-time TOTP code, generated by the authenticator app such as [Google Authenticator]() or [Authy](). ![Login form with a TOTP code field marked 2FA and the Log In button]() # 4\. Session management ## 4.1. Session life cycle Participants of assessments (test-takers) undergo proctoring sessions in accordance with the life cycle, the diagram of which is shown below. It includes two logically separated blocks: preliminary steps and supervision. If there is no date and time specified in the "Remove at" field, the session is stored for the duration of the license agreement. ![Session life cycle]() ## 4.2. Search and management The session schedule table displays a list of all sessions or for a specific period of time. The following functions are available for the administrator: - full-text search by fields with expression syntax support; - session management (add, edit, delete); - export and import of a session list in CSV format (with comma as a separator, UTF-8 encoding); - viewing sessions and participants information (by clicking on a session name or a participant name); - observing current sessions (switching to the observation mode of the selected session); - viewing the session protocol (switching to the protocol of the selected session). ![List of sessions]() When integrating with the LMS, sessions are created automatically, but the administrator can create a session manually or upload a session list from a CSV file. To change the parameters of an existing session, select it in the list and press the "Change" button in the toolbar or double-click on the selected session. The session card editing dialog will be opened. To create a new session manually, **click the "Add" button** on the toolbar. To resume a completed session, select it and click the **"Restart"** button. All previously recorded data will be retained, and the session will simply continue. > **NOTE:** The restart operation is affected by the **Lifetime** and **Close at** fields; the session will only proceed if the current time falls within the allowed limits. There are several icons representing specific information about a session. The table below includes brief explanation of their meaning: | Icon | Definition | | --- | --- | | ![Icon of an outlined person for a profile that is not verified]() | Profile is not verified. No photo available for verification | | ![Icon of a filled person for a verified profile]() | Profile is verified. The initial photo of the face matches the face in front of the camera during the session | | ![Icon of a crossed-out person for a photo mismatch]() | A mismatch was found in the available images. | | ![Bug icon for an equipment check error]() | An error occurred on the equipment check stage. Hover over the icon to see details | | ![Envelope icon for an unread chat message]() | An unread message from the test-taker in chat | | ![Flag icon for an incident]() | An incident flag. Appears if any incidents were triggered. Hover over the icon to see the number of incidents | You can use the search field to display only the necessary sessions. You can use the syntax of [regular expressions]() in your search. Here are some examples: - To find a session with the required identifier: `^123$` (where 123 is the required identifier, requesting an accurate match); - To find a session with the required identifier: `student1` (where student1 is the login of the test-taker); - To find sessions that begin with the word "Entrance": `^entrance` (case-insensitive); - To find sessions with the word "exam" in the title: `exam`. The search query can be formulated more precisely using the syntax of regular expressions. Search queries support the operators listed in the Table below. The list of the names of all supported fields can be seen in the data export dialog (via the "Export" button on the toolbar) or in Section 4.3. Date and time formats are in ISO-8601 format (YYYY-MM-DDThh:mm:ss). **Operators for search expressions** | **Operator** | **Description** | **Example query** | | --- | --- | --- | | `now` | You can use the "now" symbol, as well as the "+"
or "-" symbols, followed by a number and a unit
("s" for seconds, "m" for minutes, "h" for hours,
or "d" for days). The default unit is days. | `createdAt > now-1d & createdAt <= now` | | `=` | Equal (any) | `status = template \\| status = [accepted,rejected]` | | `>=` | Equal or greater than | `violations.b1 >= 50` | | `<=` | Equal or less than | `score <= 50` | | `>` | Greater than | `createdAt > 2019-12-01` | | `()` | Grouping expressions | `startedAt > 2019-12-01 & (status = rejected \\| score < 50)` | | `<` | Less than | `duration < 5` | | `&` | Logical AND | `createdAt > 2019-12-01 & duration < 5` | | `\\|` | Logical OR | `status = accepted \\| score > 90` | | `~*` | Matches a case insensitive regular expression | `subject ~* ^exam` | | `~` | Matches the regular expression | `student.username ~ ^student\d+$` | | `!=` | Not equal (any) | `conclusion != positive` | | `==` | Strict equal (all) | `members == [proctor1,proctor2]` | | `!==` | Strict not equal (all) | `members !== []` | | `" "` `' '` | Text that may include spaces or other operators | `subject ~* "some name"` | ## 4.3. Parameters On the "Parameters" tab of the session card, the following fields are available for editing: - *Identifier* (`identifier`) — A unique identifier of the session, which is formed in the used LMS (allowed characters: A-Za-z0-9\_-). - *Provider* (`provider`) — Specifies the name of the integration provider for this session (for example: jwt, lti, plain, etc.). - *Attempts* (`attempt`) — The number of additional attempts to pass the session; i.e., if 2 is specified, then one main attempt and two additional attempts will be given, for a total of three. - *Subject* (`subject`) — Name of the session for displaying in the proctoring system interface. - *Student* (`student.username`) — A user with the "student" role for whom the session has been created aka test-taker - *Open at* (`openAt`) — Date and time until which a test-taker will not be able to start a proctoring session. If not specified, it is not taken into account. - *Close at* (`closeAt`) — Date and time of forced termination of the session. If not specified, it is not taken into account. - *Lifetime* (`lifetime`) — Duration of the session in minutes after its launch; when the specified time is over, the session ends automatically. The force termination time cannot be greater than that specified in the "closeAt" field. If not specified or equal to 0, then it is unlimited. - *Timeout* (`timeout`) — Sets countdown in minutes that activates each time in case of test-taker's disconnection from proctoring session. If the test-taker fails to reconnect, the session is automatically finished after **1 additional minute**. - Timeout = 0 or not specified - unlimited - Timeout = 1 - the session terminates after 2 minutes of disconnection. - Timeout = 2 - the session terminates after 3 minutes of disconnection, etc. - *Remove at* (`removeAt`) — Date and time after which the session should be deleted. If not specified, it is not taken into account. - *Expires* (`expires`) — Number of days from the start of the session, after which the session must be deleted (an alternative to the "removeAt" field). - *Localization* (`locale`) — PDF protocol language, for example, "en". - *Timezone* (`timezone`) — PDF protocol time zone, for example, "Europe/Berlin". - *Rules URL* (`rules`) — Page address with the rules of the assessment, which is displayed when the "rules" add-on is enabled. There are the following example web pages: - Video instruction in English: [https://files.proctoring.app/video/en/index.html]() - Your YouTube video: `https://files.proctoring.app/tools/youtube.html?id=Mvyh5CwNFT4` (where `Mvyh5CwNFT4` is the YouTube video identifier) - *Content URL* (`url`) — Assessment page address that will be opened in an IFRAME. - *Code* (`code`) — Access code (password) for a quiz in the LMS. This code is automatically injected into the page specified in the IFRAME URL field. - *Tags* (`tags`) — Comma-separated list of keywords that can be searched in the session schedule table. A participant can go through each proctoring session only once; i.e., if the session has been completed, it cannot be continued. If for some reason you need to continue a completed session, then you can change the "deadline" field, indicating a time later than the current one. ![Session card, Parameters tab]() Also, in addition to the session card, there are parameters that are filled in by the system during its operation: - *Template* (`template`) — Assessment identifier that was used while creating the session. - *Duration* (`duration`) — Actual duration of the session in minutes. - *Creation date* (`createdAt`) — Session creation date and time. - *Start* (`startedAt`) — Session start date and time. - *End* (`stoppedAt`) — Session end date and time. - *Signed* (`signedAt`) — Date and time when the conclusion was made by the proctor. - *Status* (`status`) — Session status: - `created` — Created, but not started yet; - `started` — Started, in progress; - `paused` — Paused, the participant has disconnected (no connection for 2-3 minutes), but they are able to get back within the specified timeout; - `skipped` — Skipped, was not started before the deadline; - `stopped` — Completed, but not rated by the proctor; - `accepted` — Positively rated by the proctor; - `rejected` — Negatively rated by the proctor; - `undecided` — Requires manual review because the session results cannot be evaluated as positive or negative yet. This status can be assigned either manually or automatically; - `removed` — Removed, leaving only the session information. - *Student Verification Flag* (`student.verified`) — Indicates whether the user's identity was successfully confirmed during this specific session. This ensures that the face photo captured at the start of the assessment matches the profile picture on file. - *Student Uniqueness Flag* (`student.unique`) — Checks if the student's photos match those of other users. The system cross-references their face against all other students' profiles. If any similar records are found, this flag is set to true. - *Score* (`score`) — Credibility score of the session. - *Passed* (`passed`) — This field displays the success of the attempt: ☑ Yes (Passed) if the test taker's score obtained from the SCORM package exceeds the configured "Passing Score," or ☒ No (Failed) otherwise. - *Grade* (`grade`) — Displays the raw test score obtained from the SCORM package during the assessment. - *Proctor* (`proctor`) — Login of the proctor who made the conclusion. - *Coverage* (`coverage`) — The percentage of the actual session duration that was under any proctor's observation. - *Incidents* (`incidents`) — Number of incidents sent by proctors in chat during the session. - *Conclusion* (`conclusion`) — Conclusion of the session credibility: - `positive` — Positive; - `negative` — Negative; - `uncertain` — Uncertain; - `null` — No conclusion. - *Comment* (`comment`) — Proctor's comment, left when making the conclusion. - *IP-address* (`ipaddress`) — Test-taker's IP address at the moment the session was started. - *User-Agent* (`useragent`) — Contains the browser (application) name and its version, along with information about the computer's operating system. - *Error* (`error`) — Contains the text of the error in case it occurs. ## 4.4. Addons > **NOTE:** Only the add-ons included in your license are active and selectable. To unlock additional features, please contact your OctoProctor representative or support@octoproctor.com. On the "Addons" tab of the session card, the following fields are available for selection: - *Rules of the assessment* (`rules`) — Displays the assessment rules as the first step and requires participants to agree to them. - *Equipment check* (`check`) — Adds an equipment check step before the session; the list of checks depends on the selected metrics, including checking the browser, network, camera, microphone, and screen. - *Filling out the participant's profile* (`profile`) — Adds a step where participants must manually enter their full name. - *Manual face photography* (`face`) — Requires the test-taker to take a photo of their face. The captured photo is compared with the face photo in the participant's profile. The result of the comparison is either saved in the session card or blocks the transition to the next step in case of a mismatch when the `verify` add-on is enabled. - *Manual photography of the passport* (`passport`) — Requires the test-taker to take a photo of their identity document. The captured photo is compared with the ID photo in the participant's profile. The result of the comparison is either saved in the session card or blocks the transition to the next step in case of a mismatch when the `verify` add-on is enabled. - *Upload a scanned copy of the passport* (`scan`) — Adds an option to upload a scanned copy of an identity document, instead of taking its photo. The uploaded image is compared with the ID photo in the participant's profile. The result of the comparison is either saved in the session card or blocks the transition to the next step in case of a mismatch when the `verify` add-on is enabled. - *Add additional passport pages* (`extrapages`) — Allows test-takers to photograph or upload additional pages of their identity document or any other document. If you want to **upload a document photo without any checks**, you can enable the `extrapages`+`scan` add-ons and disable the `passport` . **By "checks" during this step, the system is verifying that the provided image qualifies as an ID (i.e., it contains a face photo and text)**: | **Combination of add-ons** | **Result** | | --- | --- | | passport | photo with checks | | extrapages | photo without checks | | extrapages + passport | photo with checks + photo without checks | | scan | **file** with checks | | scan + passport | photo or **file** with checks | | scan + extrapages | photo or **file** without checks | | scan + extrapages + passport | photo or **file** with checks + photo or **file** without checks | - *Require identity verification* (`verify`) — In case verification fails (by face or document at the "face" or "passport" / "upload" stages), do not proceed to the next step until the problem is resolved. - *Verify the name in the passport* (`name`) — Verifies the name entered by the test-taker against the name in the scanned/photographed document. If verification fails, the test-taker cannot proceed. This feature only supports the **English** language. - *Mobile camera connection via QR code* (`qrcode`) — Includes the step of connecting an additional smartphone camera using a QR code. - *Check the possibility to start the session* (`ready`) — Displays a confirmation dialog before the session begins to ensure the test-taker is ready to start. **The add-on is recommended to use for each assessment.** - *Live video streaming* (`live`) — Enables real-time observation of test-takers during the assessment and provides the proctor with all standard monitoring features. Also adds WebRTC functionality test at the "equipment check" stage. If disabled, proctors will be unable to view live video streams, use video or audio communication - *Functionality restriction for proctors* (`limited`) — When the add-on is enabled, the proctor loses the following capabilities: | During Live Monitoring | During Post-Review | | --- | --- | | Use the microphone, camera and screensharing to communicate with the student | Download the PDF protocol | | Finish and evaluate the session | Download the ZIP archive | | Send free-form messages in the chat. Only predefined templates are allowed | Evaluate the session | - *Time logging for proctors* (`timelog`) — Enables the logging of proctors' live observation time. When active, tracking data is captured and displayed both within the individual session card and in the dedicated 'Time report' view, available for administrators. > **NOTE:** requires (`live`) add-on enabled - *Participants must schedule the session time* (`schedule`) — Adds a step where participants must select the date and time of their assessment from available slots provided by the proctors listed in the "**Invitations**" field. - *Track metrics* (`track`) — Starts tracking indicators in the session. - *Record video* (`record`) — Saves the video recording of the session. If the "images" add-on is disabled, video recordings are saved without taking separate image snapshots. - *Save captured images* (`images`) — Saves captured minute-by-minute images during a session (webcam, screen, mobile camera) - *Allow to run on mobile* (`mobile`) — Permits participants to take the assessment on mobile devices - *Record an overview of a room* (`overview`) — Requires test-takers to record a brief video overview of their room before the session starts. - *Enable screen capture* (`screen`) — Enables screen recording for participants during the session. - *Allow starting only from Safe Exam Browser* (`seb`) — Requires participants to use the Safe Exam Browser to access the assessment. See more [here](). - *Enable content copy protection* (`content`) — Enables protection against copying assessment content during a session: - Prevents the context menu (right-click) from appearing; - Prevents text and content selection via mouse or keyboard; - Prevents printing of the page content; - Replaces the page with "about:blank" if the DevTools panel is opened; - Blocks unauthorized keyboard shortcuts (when the page has focus and is not in an iFrame on another domain). **Requires** (`lock`) **add-on**; - Prevents screenshots by hiding the page content immediately when focus is lost. **Requires** (`lock`) **add-on**; - Blocks third-party browser extensions from injecting code, disabling external spellcheckers, copy-bypass tools, and unauthorized plugins; - Hides the window content when switching tabs or windows (losing focus), restoring it upon return. **Requires** (`lock`) **add-on**; - Blocks native browser features such as spell check, autocomplete, and page translation; > **NOTE:** Content protection cannot be fully applied to elements displayed within an iFrame. - *Webcam preview and toolbar* (`preview`) — Displays a circular window with webcam preview of the test-taker along with a toolbar, allowing test-takers to receive violation notifications from the proctoring system and adjust their positioning or behavior. - *Allow chat with proctor* (`chat`) — Allows the test-taker to open a chat with a proctor by clicking on the preview during an active session or on the question mark icon in the top right during the preliminary steps. - *Calculator widget* (`calculator`) — Allows the participant to open the calculator from the toolbar menu. - *Whiteboard widget* (`whiteboard`) — Allows test-takers to open a whiteboard from the toolbar menu to make notes and drawings during the session - *Allow uploading files to the chat* (`upload`) — Allows test-takers to upload files to the chat. - *Virtual machine detection* (`vm`) — Enables virtual machine usage protection. A VM will be identified during the equipment check, preventing the test-taker from starting the exam, and during the proctoring session, triggering metric b1. - *Virtual or remote camera detection* (`vcam`) — Enables protection against the use of virtual or remote cameras during the equipment check and during the session, triggering metric c1 - *Screen lock in case of violations* (`lock`) — Blocks the assessment screen in case a violation lasts for more than 20 seconds. The screen automatically unlocks 10 seconds after the issue is resolved. - *Make available on the link* (`shared`) — Makes the session available by a link without authorization at "/api/report". - *Allow participants to finish the session* (`finish`) — Shows the "Finish" button in the test-taker's interface. - *Automatic conclusion based on session scoring* (`auto`) — Allows the proctoring system to set the final conclusion for the session based on confidence assessment. - *Use SCORM player* (`scorm`) — Enables support for SCORM packages within the assessment. Allows the playback of a SCORM package linked to the "Content URL" field of the session card. > **NOTE:** standard documents (HTML) or files will not open if this add-on is enabled ![Session card, Addons tab]() ## 4.5. Metrics > **NOTE:** Only the metrics included in your license are active and selectable. To unlock additional features, please contact your OctoProctor representative or support@octoproctor.com. On the "Metrics" tab of the session card, the following metrics are available for selection: - *Browser is not supported* (`b1`) - *Focus changed to a different window* (`b2`) - *Full-screen mode is disabled* (`b3`) - *Remote control or overlay window is detected* (`b4`) — *Not available in iFrame* - *Unusual key combination is detected* (`b5`) — *Not available in iFrame* - *Webcam is disabled* (`c1`) - *Face not found in front of the camera* (`c2`) - *Several faces in front of the camera* (`c3`) - *Unidentified face in front of the camera* (`c4`) - *Microphone is not working or its volume is low* (`m1`) - *Conversation or noise in the background* (`m2`) - *Network connection is lost* (`n1`) - *Mobile camera is disconnected* (`n2`) - *Records are not saved* (`n3`) - *Screen activities are not shared* (`s1`) - *Second display is used* (`s2`) You should also specify the *Threshold* (`threshold`) parameter, which is the threshold value used exclusively for the automatic conclusion of a session. If the final score is below the set threshold, the tolerance parameter is not set, and automatic evaluation is enabled, the verdict will be "Rejected"; otherwise, "Accepted". Each metric has its own weight, which is equal to 0.1 by default. This weight is used to form a confidence rating. The fixed indicators in the session are multiplied by it. The formation of a confidence assessment will be described below. ![Session card, Metrics tab]() *Tolerance* (`tolerance`) — parameter adds an offset to the threshold for the automatic conclusion. If the session score falls within this offset range it will receive an "undecided" status, meaning it requires manual review by a proctor. ![Tolerance diagram: threshold 50 and tolerance 10 give an undecided zone from 40 to 59]() ## 4.6. Members On the "Members" tab of the session card, a list of proctor logins that will have access to this session is indicated. The proctors specified in this list will see all the sessions assigned to them in their interface. You can add either the user's login or his group to the list of observers. User groups are conveniently used to organize access to sessions to a large number of participants without the need for each session to specify this large list. The order in which participants are added is not important. Administrators see all sessions; adding them to the list of participants is not required. ![Session card, Members tab]() ## 4.7. Invitations On the "Invites" tab of the session card, a list of proctors to be added to the session participants according to some predefined rules is indicated. Invitations can be used when it is necessary to organize the distribution of proctors by session so that each proctor sees only their own part of the sessions. As a list of proctors, as well as in the list of observers, their logins are indicated. However, here you can specify the rules for appointing proctors to a session; these rules will be applied to the specified list, and the proctors selected by these rules will be added to the observers in the session. Proctors are distributed equally between the test-taker. If proctors are assigned by a schedule (the "schedule" add-on is enabled), then the selection of a proctor and their moving to the list of proctors (the "members" field) occurs not at the time the session is started, but at the moment a participant selects the date and time. ![Session card, Invites tab]() The following assignment rules are supported: - *Quorum* (`quorum`) — A minimum number of proctors for the session. If the quorum is greater than zero, the specified number of proctors is required to start the session. Prior to version 4.0, this parameter was called "quota". - *Concurrent* (`concurrent`) — A limited number of simultaneous performances per proctor. If "0" is specified, it is unlimited. - *Begin* (`planAfter`) — Limits the planning range of the assessment on the part of the participant; no time slots will be offered before the specified date and time. - *End* (`planBefore`) — Limits the planning range of the assessment on the part of the participant; no time slots will be offered after the specified date and time. ## 4.8. Similar Faces If a similar profile was found based on the user's photo, the similar tab will be available, where you will see a list of similar profiles found. Please note that similar faces in the session card can appear only after a face photo is saved in the current session ![Session card Similar tab listing two similar profile photos]() ## 4.9. Assessments Registering the sessions through the external source through the integration it is possible to set up the default parameters. These will be displayed for the units, which were not transferred through the integration. There is a special tab named "**Assessments**". Each assessment has its own ID, which should be transmitted later when registering sessions through the API in the field "**template**". For the sessions created with using **Assessments** there is a field "**template**" inside the card of the session. By default, if there was not a particular **assessment**, the system will use the one with the ID "*default*" when registering new sessions. It is convenient to use Assessments for the identification of some default parameters, which could be needed for the different categories of the tests. It is enough to create all the necessary Assessments in advance. From the LMS side it is only needed to give one the Assessments' ID and for the new session the parameters listed in it will apply. > **NOTE:** The **Candidates** tab in Assessment. If no test-takers are listed in it, anyone is entitled to enter the session created based on this entity. Otherwise, only users whose **usernames** are specified in this list will be allowed to take the assessment. ## 4.10. Interval metric values The session card and PDF report include a table of metric values with the session duration divided into 10 equal intervals. The table contains two parts, separated by a column with the name of metrics. The main part displays the **raw (unweighted) anomaly values** of the violations for each of the 10 time intervals. Severity **weights** are not applied to the timeline data and are only used in the last column representing the overall weighted penalty for the entire session and in the final credibility score. Take a look at the table example: ![Table of metric values over 10 time intervals]() *Legend:* - c2, n1, n3, etc. are metrics, - t1, …, t10 are time intervals, - v is the violation for the whole session, - "–" are intervals with no data for specific metrics. ## 4.11. Credibility score The credibility of the assessment results is calculated using a weighted, interval-based scoring framework. This approach accurately isolates anomalies and prevents multiple minor violations from unfairly compounding. The final credibility score ranges from **0 to 100**. **How the score is calculated:** 1. **Data Collection:** First, the values of all triggered metrics are collected every second throughout the assessment. 2. **Dividing into Intervals**: The entire session is divided into exactly 10 equal time intervals. 3. **Peak Selection:** Within each of these 10 intervals, the system isolates only the single strongest violation (the one with the highest weighted score). Other concurrent minor violations in that same interval are ignored. 4. **Applying Weights:** The collected result for each metric is multiplied by its specific severity weight (ranging from 0.0 to 1.0). 5. **Final Calculation:** These peak violation scores from all 10 intervals are summed up. Finally, this total penalty is subtracted from a perfect baseline of 100 to get the final score (if the result is less than 0, the score is simply 0). **Calculation Example** Suppose your session is divided into 10 equal intervals: - **Interval 1:** The system detects metric c2 (No face in front of the camera) with a weighted score of 30, and metric b2 (Focus changed) with a weighted score of 10. The peak penalty for this interval is **30** (only the highest is taken). - **Interval 2:** The system detects metric m2 (Conversation or noise) with a weighted score of **15**. - **Intervals 3 to 10:** No violations are detected (penalty is 0). The total penalty across all intervals is: 30 + 15 = 45. The final Credibility Score is: 100 - 45 = **55%**. This method ensures that a severe violation retains its full penalty without being diluted by the overall session length, and prevents background noise from multiple metrics from accumulating into a false penalty. ## 4.12. Face recognition The proctoring system uses facial recognition technology to verify the test-taker's identity and ensure they are not replaced by someone else during the assessment. The facial recognition process is divided into two stages: 1. **Pre-session Verification:** Before starting a session (when the face add-on is enabled), the test-taker takes a baseline photo of their face. This photo is matched against the reference photo saved in their user profile to verify their identity. At this stage, the system also performs a one-time check to find if any similar profiles exist in the database. 2. **Continuous Session Monitoring:** Throughout the active session, the system periodically captures photos of the person sitting in front of the camera. These minute-by-minute photos are continuously compared only to the baseline photo taken right before the session started. If the system detects a mismatch—meaning a different person is recognized—it triggers the **Unidentified face in front of the camera** (`c4`) metric. The photo capturing this violation is automatically saved and placed on the timeline within the session report for further review. > **NOTE:** The system only compares the passport photo with the facial photo when both of these images appear in the user profile (usercard). The comparison result is stored directly within the usercard. Look at these examples: **Gray outline** — Indicates there is nothing to compare the photos against. This is the test-taker's first session, and their face and passport photos are going to be saved to the usercard. ![Session card Photos tab with gray outlines and empty profile slots, nothing to compare]() **Green outline** — Indicates a successful match. The face captured during the session (from the pre-session 'face' verification step) matches the photo in the usercard. The same applies to the user's identity document. ![Session card Photos tab with green outlines marking a successful face and ID match]() **Purple outline** — Indicates a mismatch. The face and/or passport photo from the current session does not match the corresponding photo in the profile. ![Session card Photos tab with purple outlines marking a face and ID mismatch]() ## 4.13. Online proctoring The administrator can observe each session in real time. To do this, on the right side of the line of each ongoing session there is a "Supervision" button. When moving to observing the selected session, the interface opens as shown below. In the central part, the test-taker's video is displayed, in the right part there is a chat, and in the upper part of the video link button with the test-taker and the "Finish" button, which allows you to finish the session. ![Real-time session supervision interface]() ## 4.14. Session report All audio, video, text messages, violations, and attachments are stored in the system and bound to the session protocol. Only proctors and administrators can view the protocols. Proctors can only view the protocols of those sessions in which they were participants. The session protocol includes: - Detailed information about the session: - Parameters: name, start and end date and time, duration, deadline, assessment of identity verification, confidence assessment; - Add-ons included; - Indicators included; - List of participants. - **"Rate" button** to set or change the conclusion of the session and comment on it; - **"PDF" button** to download the protocol; - Chat messages with photos and attached files (if any); - The list of proctors who supervised this session and the duration of observation for each of them. This is located in the rightmost tab of the chat. - Area with video recordings of broadcasts (webcam and test-taker's screen); - Timeline divided into several sections: - Total rate of violations per minute (when hovering, it shows a histogram with explicit details of violations); - Marks of the moment of photographing the face of the test-taker; - Marks of the moment of sending messages to the chat; - Playback control (play, pause, on/off sound, timeline scale, playback speed); - A histogram of average indicators for the entire period of time. - The gray bar marks the period during which a proctor was observing this session. At the bottom of the protocol, the session timeline is displayed, which consists of a timeline, the current playback position (vertical moving line), and three horizontal sections. The color coding (from green to red) indicates the severity of violations for each minute. The value ranges from 0 (no violations, green) up to 100 (critical violation, red), representing the raw, unweighted intensity of violations detected in that minute. In the first section, events are displayed: the moment of photographing a person for verification of identity, chat messages, proctor notes. The second section displays the video tracks. The third section displays a pop-up histogram of metrics for each minute. Moving along the timeline, you can find the violation moments and play back the video recordings of these sections. The histogram of average values of indicators can determine the most frequent and long-term violations. ![Session online report]() Throughout the session, data is collected on the metrics listed in Section 4.5. Based on the collected metrics, the credibility score is calculated; the formula is given in Section 4.9. Because data is stored per minute, the credibility is not set for sessions with a continuous duration of less than 1 minute. Identity verification and the "c4" metric appear after the total presence of a face in front of the camera for at least 1 minute, provided that the quality of the photo allows recognition of the face with a biometrics subsystem. The administrator, along with the proctor, can evaluate the sessions, indicating a positive or negative conclusion and commenting on it. To call the conclusion dialog for the session, **click the "Rate" button** in the protocol interface. ![Session rating dialogue]() ## 4.15. PDF report In addition to the main online report, you can get a PDF version of the report, which can be downloaded using the **"PDF" button**. This is an abridged version, including a test-taker's profile and photo, a session card, a map of the distribution of violations by time, as well as averaged indicators for the session. Pages 3 and above of this PDF can contain proctor notes with screenshots added via the session report interface. Images below show an example of such a protocol; the QR code contains a session identifier. ![PDF report page with the test-taker profile and session card]() ![PDF report page with the distribution of events over time]() ## 4.16. ZIP archive In some cases, there is a need to download all data for a particular session. This can be done with the **"Download ZIP"** button from the session table interface or from a specific session log. When downloading the archive, you can select which data to include. The following data can be selected: - Video recordings (videos) - Image snapshots (images) - Photos of all found faces (faces) - Chat messages and attachments (chat) - Proctor's recording (proctor) - HTML player (player) ![Exporting session data in a ZIP archive]() ## 4.17. Log in as a test-taker The administrator can log in as a different user with the "student" role and the specified session. To do this, use the button in the session card. ![Log in as a test-taker to a specified session]() ## 4.18. Link to report without authorization You can create special links to access a specific session protocol. By these links, you can open the session protocol without logging in. To allow opening sessions using a link without authorization, you need to enable the "Make available by link (`shared`)" add-on for a specific session or in the Assessment. In this case, it is recommended to use complex random session IDs, which are protected from brute-force attacks. The link to the protocol is formed as follows: ``` https://demo.proctoring.app/api/report/ ``` where `demo.proctoring.app` is the address of the proctoring system server, and `` is the session identifier. You can get the link from a session card with the button in the header. ![Getting link to the shared report]() # 5\. User management ## 5.1. Search and management A list of all users of the system is available to the administrator. Users are either added automatically when configuring a connection with an external authorization provider, or are imported from a CSV file, or are added manually by the administrator. The following functions are available to the administrator: - user profile creation; - editing user profile; - delete user profile; - import and export users from a CSV file; - full-text search in table fields. ![List of users]() ## 5.2. User profile When adding or changing a user account, it is required to fill in the required fields, which are marked with red asterisks. - *Username* (`username`) — A unique user ID that is generated on the software side (allowed characters: A-Za-z0-9\_-). - *Provider* (`provider`) — Specifies the name of the integration provider for this user. - *Password* (`password`) — Password for logging in without integration with the software. The password must meet the following rules: - The maximum depth of the old password history for checking used passwords is 5 (history) + 1 (current); - Allows a maximum of 5 failed login attempts; - Lock account for 5 minutes after maximum login attempts; - Allows a minimum of 12 characters, including at least one uppercase, one lowercase, and one number. - *Role* (`role`) — The user's role in the proctoring system. It can take the following values: Student, Proctor, Administrator. - *Nickname* (`nickname`) — The name of the user displayed in the proctoring system interfaces. - *Group* (`group`) — An arbitrary identifier of the user's group, which indicates that the user belongs to a specific group. This allows connecting multiple proctors to the same group and adding this group to session participants. In this way, all proctors with this group, both old and newly created, will automatically become participants in sessions with this group. - *Language* (`lang`) — The language of the user interface; by default, the browser's language is used. - *Labels* (`labels`) — A comma-separated list of labels that can be used for searching. - *Locked* (`locked`) — The blocked user will not be able to log in to the proctoring system. - *Identity verification* (`verified`) — The flag comparing the photo from the camera and the photo on the identity document within the user profile. ![User card]() ## 5.3. Two-factor Authentication (2FA) To enhance overall system security, the two-factor authentication (2FA) can be enabled for user accounts with roles **administrator** or **manager**. To do this: - Go to the 2FA tab in the user card ![User card 2FA tab with QR code, TOTP secret and TOTP code fields]() - Scan the QR code using a mobile authenticator app (e.g., [Google Authenticator]() or [Authy]()), and enter the code from the app into the **TOTP code** field - Alternatively, instead of scanning the QR code, it's possible to manually enter the **TOTP secret** value into the authenticator app - Save the user card by clicking on the **check** icon The 2FA can be disabled by using the same tab. The disabling will require entering a code from the authenticator app to confirm the action. ## 5.4. Photo of the face and the ID The administrator can view a photo of the user's face and the ID, or add/delete them. When you upload photos, the face is recognized on them, so you can only upload photos where there is only one face and it can be recognized. ![User profile Similar tab with a grid of similar faces]() ## 5.5. User rating Once the sessions are passed, test-taker profiles are rated if their sessions have been issued a conclusion. The rating can be used to rank test-takers according to the results of proctoring sessions they have completed. The rating is calculated using the following formula: $$R=\\frac{(R\_0+C)}{2}$$ where $$R\\in\[0,100\]$$ — new rating, $$R\_0$$ — previous rating (the first is $$R\_0=C$$), C — proctor's conclusion (100 — Positive, 0 — Negative). # 6\. Draft chat messages In the Drafts interface, an administrator can create a list of predefined messages to communicate with participants. This list will be visible to all proctors in the chat interface. Using this list, proctors can respond more quickly to typical questions or send regular information to participants. Messages are bound to a template and can be grouped by a specified key. If no template is specified, such messages will be linked to sessions without a template. ![Draft messages]() You can add a new draft message or edit an existing draft message. ![Editing a draft message]() Each draft has the following parameters: - *Template* — Specifies for sessions which template should be used to display this draft. The field can have several values: - Blank — Only displayed in sessions that do not have a template; - `*` (asterisk) — Displays in all sessions; - Session template identifier — Only displays in sessions that have been created based on the specified session template. - *Title* — The abbreviated name of the draft for display in the proctor interface. If the field is empty, the full text of the message will be displayed. - *Group* — The name by which to group drafts in the proctor's interface. This visually divides the drafts into groups for the proctor to work with. - *Message* — Message which will be inserted into the proctor's chat when you select this draft from the list. - *Rule* — An auto-response rule, a [regular expression]() (basic POSIX syntax) which is applied to all incoming messages from a test-taker. If there is a match for this regular expression in the message from the test-taker, the system will automatically reply with the message from this draft. The "Group" field will be used as the sender name of the message. In the proctor interface, the draft message list can be accessed via the button next to the chat text entry field. ![Draft messages list in the proctor chat interface]() # 7\. File manager In the "Files" interface, the administrator can upload static files of arbitrary types, which will be available without authorization via a unique link. This functionality can be used to publish SCORM packages in ZIP format. You can also upload pages with rules there that need to be displayed at the first stage before the start of each session to participants. Uploaded files are available without authorization via unique links in the format `/api/files/:path`, where `:path` is the relative path to the file in the file manager. ![File manager interface]() # 8\. Proctors schedule planner In the "Scheduler" interface, the administrator can view, add and delete time slots for a specific proctor in 15-minute increments. If the schedule is filled, test-takers will be able to select slots designated by the proctor on the calendar, and the proctor will become an observer for those sessions. ![Scheduler interface]() The scheduler interface is presented in the form of a weekly calendar, where you can select an arbitrary number of time slots on any future day. # 9\. Monitoring and viewing session reports In the "Supervision" interface, the administrator can connect to any of the ongoing sessions, carry out selective group monitoring and view the reports of past sessions. > **NOTE:** To keep monitoring orderly and transparent, the admin **will only receive events from the sessions they have selected** in the left-hand column. You choose the sessions you wish to focus on, and once you are finished reviewing them, you select the next set of sessions. ![Supervision interface]() # 10\. Proctor Time Reports The "Time report" tab shows how much time proctors spent on actual observation of sessions over a period of 1 month. You can select the period both in the filter at the top and in the calendar at the top right. The "Percent of coverage" column shows how much time, on average, this proctor observed each session relative to the duration of the session itself. For example, if all sessions were 1 hour long, and they observed each one for 6 minutes, the Percent of coverage = 10%. ![Time report table with active time, number of sessions and percent of coverage per proctor]() # 11\. Usage statistics The "Statistics" interface displays the average number of active sessions and online users. You can specify the range of dates and times for the statistics you want to view. The top part of the interface displays the maximum values of the indicators that were recorded for the specified period of time, e.g. Active Sessions, Online Users, CPU and RAM workload. If no date is set, the interface will display data for the last hour, and the graphs will be updated every minute. You can set a date and time period in order to capture the statistics for a certain period. The time interval is calculated from the current time (input field "End date"), and the interval corresponds to one minute. If you do not change the end date, then every minute there will be a request for data from the server. If the date is set, then the schedules will not be updated. To view data for a longer period, you can increase the interval. ![Load statistics]() # 12\. Journal The **Journal interface** displays the log of changes in the proctoring system data. This function is designed to provide transparency and control over user actions in the system. ![Journal interface]() Changes in the "config", "user", "room", "draft" models are saved in the log. If the change is related to a specific user (for example, changed session parameters or logged into the system), then the "actor" of this change is indicated. If the change is not directly related to the user, then "actor" is not specified (for example, when the session status changes). For example, you can find all changes for a specific session or user by copying their Internal ID from the Sessions tab or Users tab accordingly. Then, paste it into the filter editor on the Journal tab and select the "Record ID (record)" field. ![Record ID in the journal]() If you specifically need to find all the changes made by a user, you can use the "User ID (actor.id)" field. In the dropdown list of fields in the filter editor on the Journal tab, you can choose from numerous parameters to filter the data according to your needs. The log can be exported to CSV. And using the filter, you can select only the changes of interest from all. # 13\. Typical use cases ## 13.1. Extend session time If for some reason a proctoring session was accidentally terminated by a test-taker or proctor, it might be necessary to extend the session. To do this, it is enough to find it, proceed to editing, and change the `openAt` field so that the date and time in it exceed the current one. After that, you need to **save the changes**; the session status will change to "started", and the test-taker will be able to reconnect. ## 13.2. Uniform distribution of sessions among proctors This can be done through an "Assessment" or by distributing invite parameters through the integration. To equally assign proctors from a predefined list to each new session, you need to go to the corresponding "Assessment" and go to the "Invitations" tab. You can add proctor logins to the list one by one or enter several at once, separating them with commas. Make sure that proctors with the listed logins have already been pre-registered in the system; otherwise, during the distribution, test-takers will be assigned to a non-existent proctor. Next, you need to configure the parameters of the equal distribution. *Quorum* is a parameter that determines how many proctors will be assigned to one test-taker (session). For example, if the quorum is 1, only one proctor will be bound to each session, and if 2, no more than two proctors are allocated to one session. *Concurrent* is a parameter that limits the number of sessions per proctor. When using this parameter, there is a risk that some test-takers will be left without a proctor if the total number of concurrent sessions exceeds the number of proctors multiplied by the concurrent session limit. ## 13.3. Technical check after the start of a session The beginning of a session means a successful start of testing. Rechecking the hardware after returning to the previously left session would take extra time, so it is not conducted. However, in this case, there is a risk that the participant returns to testing using equipment that is not supported by the proctoring system. To track this behavior, the system provides the "b1" metric — Browser is not supported. ## 13.4. Link to protocol without authorization You can create special links to access a specific session protocol. By these links, you can open the session protocol without logging in. To allow opening sessions using a link without authorization, you need to enable the "Make available by link (shared)" add-on for a specific session or in the Assessment. In this case, it is recommended to use complex random session IDs, which are protected from attacks. The link to the protocol is formed as follows: ``` https://demo.proctoring.app/api/report/ ``` where `demo.proctoring.app` is the address of the proctoring system server, and `` is the session identifier. ## 13.5. Uploading of users and sessions from a CSV When the system is used without integration via IFRAME, it can be convenient to upload sessions and users in one package from a CSV file. To do this, you need to use the import function. The minimum set of columns in a CSV table is recommended as follows (in brackets are names of the fields that should be inserted as the first line in the file as a header): - Sessions: - *Identifier* (`identifier`); - *Title* (`subject`); - *Source* (`url`); - *Test-taker's login* (`student.username`). - Users: - *Test-taker's login* (`username`); - *Password* (`password`); - *Test-taker's name* (`nickname`). The CSV file must be saved in Unicode (UTF-8) encoding, with a "`,`" separator (comma). Next, this file must be imported in the "Users" and "Sessions" sections. The above-mentioned steps result in a template file for filling in users and sessions. Now you need to fill in the information on users and sessions. If sessions with an `identifier` or users with `username` already exist in the system, then to update such sessions, you need to add a field — the internal identifier `id`. ## 13.6. Opening of CSV reports in Excel Microsoft Excel can read a UTF-8 encoded CSV file in a few simple steps: 1. Open Microsoft Excel → Click the "Data" tab → click the "From Text" button → a dialog box opens. 2. In the dialog box select the CSV file → a window opens. 3. In the window select the Unicode encoding (UTF-8) and the column separator "`,`" — comma. ## 13.7. Exporting CSV reports from proctoring In order to export sessions, if it is necessary: 1. Click the "filter" button. 2. Click the "add filter" button. 3. Select the field you want to search for. 4. Specify the operator and the value of the field. 5. Click the "save" button. 6. Click "Export CSV". ![Exporting CSV reports]() All sessions can be exported by clicking the **"Export CSV"** button without entering any filters. # Manager's Guide # 1\. System purpose The OctoProctor proctoring system is designed to validate the results of online assessments when taking tests in learning management systems (LMS) and allows the following: - remotely supervise the test-taker during the assessment; - test-taker's identity verification; - detect possible violations during the assessment and give a confidence rating; - record the session including audio, video from the webcam and desktop; - resolve any controversies occurring after the assessment based on the session log. # 2\. Technical requirements There are no specific requirements for the administrator's computer. Any contemporary web browser is expected to be used for operation, but Chrome 92+ is recommended. # 3\. Logging in to the system In order to log in to the proctoring system you have to open the address of the proctoring system in a web browser and enter your login and password. The user must have the appropriate rights to access the administrator interface. ![Login form with username and password fields]() If Two-factor authentication (2FA) is enabled for the profile a user will be required to enter a one-time TOTP code, generated by the authenticator app such as [Google Authenticator]() or [Authy](). ![Login form with an additional TOTP code field marked 2FA]() After logging in, the top panel of the interface contains the menu buttons for language switching, full screen window expansion, user profile options and the exit button. There is a navigation menu on the left side. And the central section displays a selected partition. To avoid the time display issues, make sure that the time and time zone are correctly set on your computer system settings. In the user profile, you can change the manager's login, password and interface language. ![User profile dialog with username, nickname, language and password fields]() # 4\. Configurations management ## 4.1. Configurations list Each configuration is an isolated instance of the proctoring system with its own parameters and license. A list of these configurations is presented in the form of a table. ![Configurations list with two hosts and toolbar buttons at the top right]() ## 4.2. Adding a new configuration There are two options for adding a new entry to the configuration list: - **Using the "Add" button ("+" icon)** - **Configuration import via JSON file.** Adding a new entry is an entry of the license key and system instance parameters into the configuration list. Configurations are differentiated from each other by host name, one configuration cannot have two different hosts and different configurations cannot have the same host. The license key contains (encoded): - host name of the system instance - license validity period - charge unit - volume in charging units - number of days for storing session data - features, addons and metrics covered by your license ![Configuration dialog, Parameters tab, with host, dates, unit, volume, storage and license key]() ![Configuration dialog, Features tab, with the White-label option checked]() ![Configuration dialog, Addons tab, with a checklist of optional assessment steps]() ![Configuration dialog, Metrics tab, with a checklist of violation metrics]() **Configuration import via JSON file.** The JSON file for importing the configuration must contain the `key` field and may additionally contain the `params` field with the system instance parameters. For example: ``` { "key": "...", "params": { "webhooks": { "jwt": { "strategy": "jwt", "secretOrKey": "secret", "profile": { "username": "payload.username", "role": "payload.role", "nickname": "payload.nickname" }, "register": { "name": "payload.name", "subject": "payload.subject", "url": "payload.url", "template": "payload.template" } } } } } ``` ## 4.3. Integration parameters The integration parameters define data exchange in between the proctoring system and the LMS. These parameters are specified in the `webhooks` section. The format of the fields is `webhooks..*`, where `` is the name of the integration provider (random text identifier). Parameters description: | **Parameter** | **Description** | | --- | --- | | `webhooks..strategy` | Integration strategy, may have the following values: `jwt`, `lti`, `lti13`, `plain`. | ### "jwt" strategy only | **Parameter** | **Description** | | --- | --- | | `webhooks..secretOrKey` | Secret key used to verify JWT. | ### "lti" strategy only | **Parameter** | **Description** | | --- | --- | | `webhooks..consumerKey` | LTI consumer key. | | `webhooks..consumerSecret` | LTI secret key. | ### "lti13" strategy only | **Parameter** | **Description** | | --- | --- | | `webhooks..clientId` | LTI client ID (optional). | | `webhooks..privateKey` | Private key in PKCS\#8 format. | | `webhooks..publicKeysetURL` | URL to retrieve the platform's public keys. | | `webhooks..accessTokenURL` | URL to retrieve the platform's access token. | | `webhooks..authRequestURL` | URL to perform the authorization request to the platform. | ### Common parameters | **Parameter** | **Description** | | --- | --- | | `webhooks..callbackURL` | Redirect page after successful authorization, it is usually used with LTI integrations. | | `webhooks..headers.
` | Custom headers for outgoing requests (webhooks). | | `webhooks..profile.` | Mapping of fields to populate the user's profile, which defines the logic behind the relationship between internal and external fields. External fields are accessible via the "payload" object. | | `webhooks..register.` | Mapping of fields to fill in the session parameters, which takes place immediately after the user is authorized and uses the data that is passed along with the user data (the "payload" object). | | `webhooks..start.` | Parameters of the handler that is called at session startup and is used to send startup data via the API to the LMS. | | `webhooks..pause.` | Handler parameters that are called when the user has been disconnected for more than 2 minutes and are used to send the event data to the LMS via API. | | `webhooks..stop.` | Parameters of the handler, which is called when the session is terminated and is used to transmit the termination data via API to the LMS. | | `webhooks..submit.` | Parameters of the handler that is called when a session statement is issued or modified and used to send the results to the LMS via the API. | ## 4.4. SDK parameters The SDK parameters define the settings for the client part of the proctoring system. These settings are specified under `sdk`. Parameters description: | **Parameter** | **Description** | | --- | --- | | `sdk..height` | maximum image height in pixels. | | `sdk..width` | maximum image width in pixels. | | `sdk..frameRate` | maximum video frame rate. | | `sdk..bitrate.audio` | audio bitrate for video calls in kbps. | | `sdk..bitrate.video` | video stream bitrate for video communication in kbps. | | `sdk..recorder.audioBitsPerSecond` | audio recording bitrate in bps. | | `sdk..recorder.videoBitsPerSecond` | video recording bitrate in bps. | | `sdk.css.` | SDK interface styling parameters, the following variables are supported ``:
`--color-background: #fff;`
`--color-foreground: #1b1718;`
`--color-neutral: #a1a1a1;`
`--color-neutral-foreground: #f5f5f5;`
`--color-primary: #9932c2;`
`--color-primary-foreground: var(--color-background);`
`--color-secondary: #7a82f0;`
`--color-secondary-foreground: var(--color-background);`
`--color-success: #27ae60;`
`--color-success-foreground: var(--color-background);`
`--color-warning: #ffa500;`
`--color-warning-foreground: var(--color-background);`
`--color-danger: #ff5c4c;`
`--color-danger-foreground: var(--color-background);`
`--font-family: "Arial", "Helvetica", sans-serif;`
`--font-family-monospace: monospace;`
`--font-size: 16px;`
`--line-height: 1.5em;`
`--border-radius: 4px;`
`--border-width: 2px;`
`--backdrop-background: #00000080;`
`--fab-size: 90px;`
`--fab-border: 4px;`
`--fab-offset-x: 10px;`
`--fab-offset-y: 10px;` | | `sdk.iframe.allow` | ["allow"]() option in IFRAME mode. | | `sdk.iframe.sandbox` | ["sandbox"]() option in IFRAME mode. | ## 4.5. Removing a configuration In order to delete a configuration you no longer need, you select the row in the **Configurations** tab, click the **Delete** icon in the top panel, and the system will prompt you to enter the configuration's full name for confirmation. ![Delete confirmation dialog asking for the host name, with arrows to the menu and Delete icon]() > **NOTE:** Once deleted, the host cannot be restored. All data on the host will be purged. # 5\. Jobs In the "Jobs" section you can monitor the execution of background tasks, such as collecting statistics on system usage, clearing unnecessary downloaded files, auto-completion and session cleanup. This is actually more system information and is only useful in case of some problems on the server or with integration. ![Jobs table with job names, next and last run times, duration and errors]() The tab includes the following fields: - Next run - Shows the date and time the job is planned for. If empty, then the job is one-time - Last run - Shows the time the job started. If empty, then the job hasn't been executed before - Duration - Shows how long it took to execute and complete the job. If it is empty, then the job hasn't been executed ever before, or is being executed at the moment - Errors - Shows description of errors if any happened # 6\. Statistics The Statistics interface displays the number of active sessions, online users, CPU and RAM usage on the server including all configurations. You can specify the date and time interval for which you want to view the statistics. The top part of the interface displays the maximum values of the indicators that were recorded during the specified time interval. If no date is specified, the data will be displayed for the last hour and the graphs will be updated every minute. ![Statistics page with six summary counters above time-series charts]() # 7\. Journal The Journal interface displays the log of changes in the proctoring system data. This function is designed to provide transparency and control over user actions in the system. ![Journal table of changes with model, action, login, role and changes columns]() Changes in the "config", "user", "room", "draft" models are saved in the log. If the change is related to a specific user (for example, changed session parameters or logged into the system), then the "actor" of this change is indicated. If the change is not directly related to the user, then "actor" is not specified (for example, when the session status changes). The manager can view the log for all hosts, including the manager's host. The log can be exported to CSV. And using the filter, you can select only the changes of interest from all. # 8\. License calculation License usage is calculated **per minute** with no rounding up to the hour. For example, three 20-minute sessions will consume exactly **one hour** of license time. Data storage on the cloud server is **180 days** by default. This period can be modified according to your license terms. The storage countdown begins only for **finished** sessions. Sessions that were **never started** do not consume license time, and their storage period is not initiated. # Proctor's Guide # 1\. System assignment The proctoring system is designed to validate the independence of passing online assessment (exams or tests) in learning management systems (LMS). It verifies the identity of the participant and monitors in real time to identify possible violations. # 2\. Technical requirements Technical requirements of the proctoring system are given in the table below. | **Parameter** | **Minimum requirements** | | --- | --- | | Web browser | Chrome 92+, Opera 90+, Firefox 85+, Edge 90+, Safari 14.1+ | | Operating System | Windows 7, macOS 10.13, Linux, Chrome OS | | Webcam (optional) | 640x480, 15 fps | | Headset | Any | | Network speed | 256 Kbit/s x number of test-takers observed | Before the assessment, you must check the compatibility of the computer with the proctoring system on [the dedicated page](). Additionally, you can check the webcam, microphone and network here: - [Webcam test]() - [Microphone test]() - [WebRTC test]() - [Check the internet speed]() # 3\. Log in to the system Logging into the proctoring system for the proctor is possible through the LMS, depending on the integration option, or from the login page of the proctoring system by login and password. To enter the proctoring system: 1. Open the system address in a web browser. 2. Enter your login and password. ![Proctoring system login page with username and password fields]() Once logged in, the monitoring interface is displayed. # 4\. Work planning Some sessions may allow the participant to schedule the assessment date and time. In this case, the proctor needs to fill out his work schedule in the calendar, which can be opened with the corresponding button in the upper right corner of the page. If the schedule is full, test-takers will be able to select slots designated by the proctor on the calendar, and the proctor will become an observer for those sessions. The scheduler interface is presented in the form of a weekly calendar, where you can select an arbitrary number of time slots on any future day. ![Scheduler weekly calendar with available time slots highlighted in blue]() To manage slots: 1. Switch between weeks in the calendar using the arrow buttons on the toolbar. 2. **Add slots:** Select the range with the mouse and click the add button on the toolbar or press Enter. 3. **Delete slots:** Select the range with the mouse and click the delete button on the toolbar or press Delete. Past slots can no longer be deleted, and the past calendar area is highlighted in gray. Once slots are added, test-takers will be able to sign up for the designated times. If test-takers have already signed up for sessions, removing slots by the proctor will not cancel the test-takers' registrations. Already scheduled sessions can be seen in the monitoring interface. Only the system administrator can change, cancel, or change proctors in already scheduled sessions. # 5\. Supervision interface Each proctor can observe up to 25 sessions at a time. The more powerful the computer and the faster the Internet, the more sessions can be displayed simultaneously. The left side of the monitoring interface displays a list of sessions assigned to the proctor, which is grouped by the current state of the session. Those sessions that are in process can be watched online. You can view protocols for the past sessions. > **NOTE:** To keep monitoring orderly and transparent, the proctor **will only receive events from the sessions they have selected** in the left-hand column. You choose the sessions you wish to focus on, and once you are finished reviewing them, you select the next set of sessions. The proctoring system Administrator can see the periods of invigilation for completed sessions by each proctor that observed it, the Administrator sees the proctor's username, and the total duration of their observation for that session. The event of "observation" by a proctor is recorded in the system if the session or several sessions were **selected** in the list on the left, and if a proctor has made at least 1 mouse movement within 5 minutes. The minimum observation duration is 10 seconds. You can use the search to display only the desired sessions. You can use the following syntax in your search: - `^123$`: Find the session with the desired identifier (123 — exact match). - `student1`: Find sessions with the specific test-taker (student1 —test-taker's login). - `^proctor1|proctor2$`: Find sessions with the necessary participants (proctor1 or proctor2 — proctor logins, "|" means OR). - `^entrance`: Find sessions starting with the word "entrance" (not case sensitive). - `exam`: Find sessions containing the word "exam" in the name. In the central part, video of those sessions that are selected in the list on the left is displayed. **To select specific sessions:** - One session can be selected by clicking on the list item. - Several sessions can be selected by clicking with the "Ctrl" ("Cmd" for Mac users) key held down. - Several consecutive sessions can be selected by clicking on another element of the list with the "Shift" key held down. - All current sessions can be selected using the combination "Ctrl + A" ("Cmd + A" for Mac users). - You can remove the session selected by the green frame from the central part of the observation with the "Del" ("Backspace" for Mac users) key. ![Supervision interface with the session list on the left and a grid of test-taker video tiles]() A search query can be formulated more accurately using expression syntax. The following operators are supported in search queries, listed in Table below. You can see the list of names of all supported fields in the data export dialog (administrator interface). The date and time format is ISO-8601 (YYYY-MM-DD hh:mm:ss). **Operators for search expressions** | **Operator** | **Description** | **Example Query** | | --- | --- | --- | | `now` | You can use the "now" symbol, as well as the "+"
or "-" symbols, followed by a number and a unit
("s" for seconds, "m" for minutes, "h" for hours,
or "d" for days). The default unit is days. | `createdAt > now-1d & createdAt <= now` | | `>` | Greater than (for numeric or date fields) | `date>2025-01-01` | | `<` | Less than (for numeric or date fields) | `date<2025-12-31` | | `>=` | Greater than or equal to | `date>=2025-01-01` | | `<=` | Less than or equal to | `date<=2025-12-31` | | `=` | Exact match for a field value | `session=123` | | `!=` | Not equal to | `session!=123` | | `==` | Strict equality (case-sensitive match) | `student==Student1` | | `!==` | Strict inequality (case-sensitive mismatch) | `student!==student1` | | `~` | Partial match for a field value | `name~exam` | | `~*` | Case-insensitive partial match | `name~*Exam` | | `&` | Logical AND between conditions | `student=student1&session=123` | | `\\|` | Logical OR between conditions | `^proctor1\\|proctor2$` | | `()` | Group conditions for precedence | `(student=student1\\|student=student2)` | | `" "` | Double quotes for exact phrase search | `"entrance exam"` | | `' '` | Single quotes for exact phrase search | `'entrance exam'` | | `,` | Separate multiple values in a list | `student=student1,student2` | It is possible to switch between selected sessions; the current active session is surrounded by a green frame. The sound from the test-taker's computer is reproduced only for the active session surrounded by a green frame; the sound of the remaining sessions is muffled at this time. For an active session, the top bar displays the session title and controls. The proctor can prematurely end the active session with the "Finish" button, and a dialog will appear in which you can immediately give the conclusion and comment. ![Rate the session dialog with conclusion options and a comment field]() A proctor can chat with a test-taker both during the preliminary steps, except for the login page, and during an active session. In addition to chat, the proctor can communicate with the test-taker via video by clicking on the microphone icon (sound only) or the camera (video + sound) icon at the top of the surveillance interface. When switching between sessions in the chat, the history of one selected session is loaded. You can send not only messages, but also pictures or files to the chat. To send them you need to open a chat, press the button with the image of a paper clip, and select a file on the computer. After that, the file will be attached to the chat. To send it, you need to click the "Send" button or the "Enter" key. In the chat, you can send a message in the "Incident" mode; in this case, the message is marked in red and the user is blocked from accessing the assessment contents. To unblock the content, you need to send one more message as normal mode. ![Chat panel beside the active session video with message input and attachment button]() In each observed session, events that are recorded at the last minute (they are updated every minute) are displayed using special icons on top of the test-taker's video. A list of all recorded events with symbols is given in the table below. **The list of recorded events and error codes** | **Code** | **Pictogram** | **Description** | | --- | --- | --- | | b1 | ![Pictogram b1, a browser logo]() | Browser is not supported | | b2 | ![Pictogram b2, a two overlapping windows]() | Focus changed to a different window | | b3 | ![Pictogram b3, a window with a full-screen frame]() | Full-screen mode is disabled | | b4 | ![Pictogram b4, a monitor with a remote cursor]() | Remote control or overlay window is detected | | b5 | ![Pictogram b5, a keyboard]() | Unusual key combination is detected | | c1 | ![Pictogram c1, a crossed-out camera]() | Webcam is disabled | | c2 | ![Pictogram c2, a ghost]() | Face not found in front of the camera | | c3 | ![Pictogram c3, a two people]() | Several faces in front of the camera | | c4 | ![Pictogram c4, a face inside a scan frame]() | Unidentified face in front of the camera | | m1 | ![Pictogram m1, a crossed-out microphone]() | Microphone is not working or its volume is low | | m2 | ![Pictogram m2, a speaker with sound waves]() | Conversation or noise in the background | | n1 | ![Pictogram n1, a two laptops with a cross]() | Network connection is lost | | n2 | ![Pictogram n2, a crossed-out smartphone]() | Mobile camera is disconnected | | n3 | ![Pictogram n3, a crossed-out recording symbol]() | Records are not saved | | s1 | ![Pictogram s1, a crossed-out screen]() | Screen activities are not shared | | s2 | ![Pictogram s2, a two overlapping screens]() | Second display is used | # 6\. Session assessment Each session is finished either by test-takers themselves, or the proctor, or automatically at the end of the allotted time. All audio, video, text messages, and recorded events are saved in the system and are attached to the session report. ![Session report with chat, PDF, ZIP and Rate buttons and the metrics timeline at the bottom]() After the end of the session, the system automatically evaluates credibility in the assessment results, including all indicators of the session. The score can be in the range from 0 to 100. At the bottom of the protocol, the session timeline is displayed, which consists of a timeline, the current playback position (vertical moving line), and three horizontal sections. The color (from green to red) highlights the minutes for which metrics in the proctoring system are collected. The greater the sum of the metrics for this minute, the more red the minute is highlighted. Weights are ignored on the timeline and are only applied to the final score and the rightmost column of the session card. In the first section, events are displayed: the moment of photographing a person for verification of identity, chat messages, proctor notes. The second section displays the video tracks. The third section displays a pop-up histogram of metrics for each minute. Moving along the timeline, you can find violations you are interested in and play videos of these areas. The histogram of average values of indicators can determine the most frequent and long-term violations. If an opinion on the session has not yet been issued, the proctor must do so immediately after checking the protocol. **To set a conclusion:** Click the "Rate" button on the top panel of the protocol, after which a proctor conclusion dialog will be displayed. ![Rate the session dialog opened from the Rate button of the report]() # 7\. Evaluation criteria for results The system automatically assigns an assessment of the level of credibility in the assessment results, which depends on the factors described below. For the correct operation of the algorithms, the test-taker must ensure that the following conditions are met: - The test-taker gives his or her consent for audio and video recording and subsequent storage of the entire assessment. - The webcam must be installed strictly in front of the face, and it is not allowed to install the camera from the side. - The head must be fully framed, and no partial or complete exit from the camera's field of view is permitted. - The face should be in the center of the webcam's field of view and occupy at least 10% of the space captured by the camera during the entire session. - The face should be evenly lit, the light source should not be directed at the camera or only one half of the face. - Hair, clothing, hands, or anything else should not cover the face area. - It is not permitted to wear sunglasses; glasses with transparent lenses may only be used. - There shouldn't be any other people in the room. - It is prohibited to leave the workplace during the assessment. - There shouldn't be voices or noise in the background; it is most preferable if the assessment is held in silence. - The assessment must be passed in a browser with a full screen window, you cannot switch to other applications (including other browsers) or minimize the browser, you cannot open third-party tabs (pages). - It is prohibited to use any remote control software (such as TeamViewer, AnyDesk, etc.) or applications that create overlay windows during the assessment. - All programs that use the webcam should be disabled on your computer, except for your browser. - The materials and contents of the assessment may not be recorded in any way or passed on to third parties. - It is strictly prohibited to use unauthorized keyboard shortcuts (e.g., Ctrl+any key, F1–F12, Alt+F1–F12, PrintScreen, ScrollLock, Pause, and Alt combinations). - Do not use sound, visual, or any other clues. - If an attempt to deceive the system or the proctor is detected, the results of the assessment are invalidated. # 8\. Conference calls with other proctors Some assessment scenarios involve organizing an examination committee. Members of such a commission can communicate with each other through a special conference interface. ![Conference room interface with a video area and a chat panel]() To join a conference: 1. In the main menu, select the "Conference" item. 2. Enter the conference ID. By default, the identifier of the group to which the proctor belongs is inserted. 3. If multiple proctors join a conference with the same ID, they will be able to communicate with each other via audio, video, and chat. # Test-taker's Guide # 1\. System assignment The proctoring system is designed to validate the independence of passing online assessments (exams or tests) in learning management systems (LMS). It verifies the identity of the participant and monitors in real-time to identify possible violations. # 2\. Technical requirements Technical requirements of the proctoring system are given in the table below. | **Parameter** | **Minimum requirements** | | --- | --- | | Web browser | Chrome 92+, Opera 90+, Firefox 85+, Edge 90+, Safari 14.1 | | Operating System | Windows 7, macOS 10.13+, Linux, Chrome OS | | Mobile browser | Android 12+ (Chrome 92+), iOS 13+ (Safari) | | Webcam | 640x480, 15 fps | | Microphone | Required | | Speakers | Optional (for communicating with a proctor) | | Network speed | 256 Kbit/s | Before the assessment, you should check the compatibility of the computer with the proctoring system [on the dedicated page]() on OctoProctor. Additionally, you can check the webcam, microphone and network here: - [Webcam test]() - [Microphone test]() - [WebRTC test]() - [Check the internet speed]() # 3\. Registering for the assessment Depending on the scenario chosen by the organizer, you may need to register for the assessment first. There are two fields to fill in: - Your login is a unique and unchangeable identifier of the participant consisting of Latin letters and numbers (sometimes it is already filled in, in this case it does not need to be changed); - Your password should be a minimum of 12 characters, at least one uppercase, one lowercase and one number; - The assessment identifier is a set of Latin letters and numbers indicating a specific assessment. ![Registration dialog with login, password and assessment identifier fields]() > **NOTE:** Your login and identifier information is supplied by the organizer of your assessment in advance. # 4\. Assessment rules To start an assessment with proctoring, you should get familiar with its rules and consent to the conditions of the proctored assessment. > **NOTE:** If the event organizer has enabled support before the assessment begins, you can get help during the preliminary steps by clicking the '?' icon in the top-right corner of the window, as shown in the image below. ![Rules of the assessment dialog with a video player and a help (?) icon in the top-right corner]() The system automatically evaluates credibility in the assessment results based on the indicators listed below. Abidance with the following rules during the whole assessment session would help you to get the highest credibility in the assessment results: - You give your consent to the audio and video recording and subsequent storage of the entire assessment; - The webcam must be placed strictly in front of your face, no cameras may be placed on the side; - The head should be fully framed, and no partial or complete exit from the camera's field of view is permitted; - The face should be in the center of the webcam's field of view and occupy at least 10% of the space captured by the camera during the entire session; - The face must be lit evenly and the light source must not be directed into the camera or illuminate only one half of the face; - Hair, clothing, hands or anything else should not cover the face area; - It is not permitted to wear sunglasses, glasses with transparent lenses are only allowed to be used; - There shouldn't be any other people in the room; - It is prohibited to leave the workplace during the assessment; - There shouldn't be voices or noise in the background, It's best if the assessment is held in silence; - The assessment should be passed in a browser with a full screen window, you cannot switch to other applications (including other browsers) or minimize the browser, you cannot open third-party tabs (pages); - It is prohibited to use any remote control software (such as TeamViewer, AnyDesk, etc.) or applications that create overlay windows during the assessment. - All programs that use the webcam should be disabled on your computer, except for your browser; - Ensure a stable internet connection; - The materials and contents of the assessment may not be recorded in any way or passed on to third parties; - It is strictly prohibited to use unauthorized keyboard shortcuts (e.g., Ctrl+any key, F1–F12, Alt+F1–F12, PrintScreen, ScrollLock, Pause, and Alt combinations). - Do not use any audio, visual or any other prompts; - If an attempt to deceive the system or the proctor is detected, the results of the assessment are invalidated. One or more participants can be present during the session (proctors or observers). At the same time, the session can be run without any other participants, or with the participation of a virtual proctor. In this case, the evaluation of the assessment credibility will be carried out either by the proctor once the session is over (based on the protocol) or by the system automatically. # 5\. Planning the assessment time Some assessments do not have a specific date and time, in which case you will need to independently select the date and time from the proposed options. The interface of this step is presented in three stages: 1. Selecting a date via the calendar interface. 2. Selecting a time slot from free ones. 3. The ability to change the date and time before the start of the assessment. Once you select your date and time, you can move on to the next step. ![Planning dialog with a monthly calendar for choosing the assessment date]() ![Planning dialog showing the selected date and a free 7:00 PM time slot]() ![Planning dialog confirming the chosen date and time, each with a change button]() # 6\. Equipment check Computer and Internet connection check that allows identifying possible technical problems before the start of the assessment is conducted at the start of each session. The check is run automatically, so the user's interference is needed only in case problems are identified. ![Equipment check dialog listing browser, webcam, microphone, screen, network and WebRTC checks]() Equipment check stages are the following: 1. At the browser compliance check stage, the system checks whether your browser complies with the minimum requirements of the proctoring system; browser window should be switched to full-screen mode. 2. At the webcam check stage, you should enable camera access in the browser, if such a request is made. If the camera works correctly, then you will pass the webcam check. 3. At the microphone check stage, you should enable microphone access in the browser, if such a request is made. If the volume of your microphone is enough, then you will pass the microphone check. 4. At the screen check stage, you should give access to the entire screen. If access is given only to a part of the screen, or an additional monitor is installed, then the check will result in an error. 5. The connection test phase checks that a web socket connection to the server is possible. The test will be successful if this type of connection is not blocked. 6. The connection test phase checks that video traffic can be transmitted on your network using WebRTC technology. The test will be successful if the traffic is not blocked. Potential issues and their solutions are listed in Table below. **Potential Issues and their Solutions** | **Issues** | **Solution** | | --- | --- | | Browser check error | Your browser does not comply with the minimum requirements of the proctoring system. Install the latest version of [Google Chrome]() and try again. | | Webcam check error | Your webcam is not working or is being blocked by other computer applications. Check whether your webcam is [working properly in the browser](); close other applications that might be using your webcam;
disable antivirus; if there are several webcams on your computer, choose the correct one in the browser settings. If the webcam is working, but the error is still present, try to restart the computer. | | Microphone check error | The microphone is not working or disabled in the settings of your computer (operating system). Increase the volume of the microphone or plug another microphone and then choose it in the browser settings. Check whether your microphone is [working properly in the browser](). | | Screen check error | Access to the screen is disabled; your browser does not support screen sharing; you give access only to a part of the screen. If the browser requests you to enable screen sharing, do so; otherwise, refresh the browser. | | Network connection check error | The web-socket connection to the server cannot be established. Extensions in the browsers, such as AdBlock or VPN can cause the problem. Using a proxy server can also cause the problem. Disable all browser extensions or try a different browser and do not use/disable proxies or VPNs. | | WebRTC check error | Your computer or your internet provider blocks the transmission of video traffic using WebRTC technology. Your bandwidth must be at least 256 kbps (send and receive), also TCP/UDP 3478 ports on your network and workstation (firewall) should not be blocked. A VPN usage may also cause issues. Please check your [network speed]() and [port blocking]() and disable VPN. | # 7\. Filling in the profile If your name is not yet specified in your account, you will need to fill in your full name at the corresponding step. ![Profile dialog with last name, first name and middle name fields]() # 8\. Face photo The proctoring system may ask you to take a picture of your face using a webcam. The face photo stage is a part of an identity verification procedure. ![Webcam photo step with the face inside a red oval frame and a Take Photo button]() # 9\. ID photo The proctoring system may require your identification document (ID), which should be done via webcam or uploaded to a JPEG file up to 5 MB from your PC. In case a scan is uploaded, the image should contain only the side with your photograph placed horizontally. The document is automatically checked by the proctoring system to be correct and clear, and the ID photo is verified with your face. An ID photo is the part of your identity verifying procedure. ![ID step with a card inside a red frame and Take a Picture and Upload buttons]() # 10\. Recording the overview of the workplace The process can involve filming an overview of the workplace before the assessment starts. There is a separate step for this: 1. Make sure that the camera picture is displayed on the screen. 2. Press the "Start Recording" button. 3. Within 60 seconds slowly rotate the camera as if you were taking a panoramic picture, so that you can see the entire workspace and the room. 4. If you manage to show the entire room faster, press the "Stop recording" button. 5. The recording you just made will start playing back and watch it. 6. If the recording clearly shows the whole workplace and room, press the "Save" button. 7. If the recording fails, press the "Retry" button and start the recording again. 8. You can record the overview with your smartphone camera by pressing the "QR code" button, scan the code with your smartphone camera and open the resulting link in the browser on your smartphone. ![Workplace recording step with webcam preview, Start Recording and QR Code buttons]() # 11\. Mobile camera connection Sometimes you may need to connect your smartphone camera for a better view of the workplace and the room during the assessment, to do this you need to scan the QR code displayed on your computer screen with your phone and then open the link obtained from the code in the browser on your phone. If the camera has been successfully connected, you should see "Camera successfully connected" on the screen of your phone. ![Connect mobile camera dialog with a QR code to scan with a smartphone]() - Android systems - Scan the QRcode with the **standard "Camera" app**, copy the resulting link and open it in the **Google Chrome** browser. - iOS systems - Scan the QRcode with the **standard "Camera" app**, copy the resulting link and open it in the **Safari** browser. # 12\. Start of the assessment Before you begin an assessment task, a dialogue is usually displayed with information about the assessment and a "Start" button. If the time of the assessment has not yet arrived or has already passed, or if there are no available proctors at the moment, a message will appear. If all is well, the proctoring will go into supervision mode and the assessment page will open. ![Connection dialog with full name, assessment title and a Start button]() # 13\. Taking the assessment Once the previous steps are successfully completed, the assessment page will open. The assessment page opens in the central part of your window, and a small circle is displayed in the lower left corner with the image from your camera. During the proctoring session, you can communicate with the proctor watching the assessment procedure, if they are online. Chat with the proctor opens on the right side of the screen. In some cases, the proctor may connect via video and audio, then video from the proctor's camera appears above the chat. During the assessment, make sure your face is fully placed in the circle and well lit. Notifications may appear next to the FAB (floating action button) circle if any rules of the assessment are not followed, turning the notification yellow or red. ![Assessment page with the proctor chat on the right and the camera circle at the lower left]() Clicking on the FAB circle will open a menu where there may be useful tools for passing the assessment. # 14\. End of assessment Once the tasks provided by the assessment are completed, finish the assessment inside the LMS. Once the assessment is completed, it will no longer be possible to restart it. In case of violations and infringements of assessment rules, the proctor has the right to cut the session off, then the assessment procedure is stopped, and its results are canceled. Also, the completion occurs automatically after the end of the time allotted for your assessment. All audio, video and text messages, as well as recorded violations, are stored in the system and linked to your proctoring protocol. After a while, the results are checked and the final proctoring conclusion is given, which is transmitted to the LMS. # Product # Frequently Asked Questions # 1\. Supported browser versions Supported browser versions for PC: - [Chrome]() 92+ (Windows 7+, macOS 10.13+, Linux, Chrome OS) - [Edge]() 90+ (Windows 7+) - [Firefox]() 85+ (Windows 7+, Linux) - [Opera]() 90+ (Windows 7+, Linux) - [Safari]() 14.1+ (macOS 10.13+) Supported browser versions for smartphones: - [Chrome]() 92+ (Android 12+) - [Safari]() (iOS 13+) # 2\. Checking your computer for compatibility You can take a practice proctored quiz here: [https://octoproctor.com/demo]() Computer test page: [https://octoproctor.com/check]() Individual test pages can also be set up to check the settings for specific assessments. We recommend that you check your computer before the assessment starts so that you can make the necessary computer settings in advance. If the check is successful, the corresponding message is displayed. ![Equipment check passed with a green checkmark and a success message]() # 3\. Error "Your browser is not supported" during equipment check Please, make sure you use supported equipment and software for the proctoring session. Technical requirements and useful links can be found in our [Test-takers guide](). If all the requirements are met, the error may mean the system can't access your device's graphics card through **WebGL**, that is needed for the system check and platform to work properly. **Common causes:** - Graphics drivers are missing/outdated - Hardware acceleration is turned off in the browser - WebGL is disabled **Quick Fix Steps:** **1\. Update your graphics drivers** Install the latest official drivers for your graphics card from an official provider website (NVIDIA, AMD, Intel) **2\. Enable hardware acceleration & WebGL in your browser** *2.1. Google Chrome* 1. In the address bar, type: `chrome://settings/system` → Enter 2. Turn **ON** "Use graphics acceleration when available" 3. Relaunch Chrome 4. Optional check: type `chrome://gpu` → look under "Graphics Feature Status" → WebGL should say **Hardware accelerated** *2.2. Microsoft Edge* 1. In the address bar, type: `edge://settings/system` → Enter 2. Turn **ON** "Use hardware acceleration when available" 3. Click **Restart** if prompted *2.3. Mozilla Firefox* 1. Go to **Settings** → **General** → scroll to **Performance** 2. Check **"Use recommended performance settings"** (or uncheck it and manually enable **"Use hardware acceleration when available"**) 3. Advanced check: type `about:config` → accept the risk → search for `webgl.disabled` → Value must be **false** (if true → double-click to toggle) *2.4. Safari (macOS)* WebGL is normally enabled by default. If you see the error: 1. Update macOS to the latest version (System Settings → Software Update) 2. Temporarily disable third-party extensions (especially aggressive ad blockers or privacy tools) via Safari → Settings → Extensions After applying these changes, refresh the assessment page and run the system check again. # 4\. Access to the camera and microphone Page for checking webcam in browser: [https://webcammictest.com]() Page for checking microphone in browser: [https://webcammictest.com/mic/]() ## 4.1. In Chrome Browser The first time you request permission to place windows on your screens, access the camera and microphone, you must answer "Allow": ![Browser prompt asking to manage windows on all your displays, with Allow and Block]() ![Browser prompt asking permission to use your cameras]() ![Browser prompt asking permission to use your microphones]() If several cameras are connected to the computer: 1. Click on the camera icon on the left side of the address bar and go to the settings by the "More options arrow" (Windows and Linux) or the "Manage multimedia device settings" button (MacOS) ![Chrome site info popup with the arrow next to Camera highlighted]() 2. Select "Manage" ![Chrome camera permission panel with the Manage link at the bottom]() 3. In the pop-up list, select another camera ![Chrome camera settings with the camera selection drop-down open]() After changing the settings, you need to refresh the test page. If several microphones are connected, you should follow the same steps for the "Microphone" item. If access was blocked: 1. Click on the camera icon on the left side of the address bar and go to the settings by the "More options arrow" (Windows and Linux) or the "Manage multimedia device settings" button (MacOS) ![Chrome site info popup with the Camera arrow highlighted, used to restore blocked access]() 2. Remove from the list of blocked sites `https://*.proctoring.app:443` ![Chrome camera settings with the delete icon next to the blocked site highlighted]() 3. Reload the page and reply to the request for access "Allow" ![Chrome camera prompt shown again after reloading the page]() Another way to allow access to the camera and microphone is to click on the settings icon in the left part of the address bar and click toggle switches of the "Camera" and "Microphone" items. ![Chrome site info popup with the Camera and Microphone toggles highlighted]() ## 4.2. In Firefox Browser The first time you request permission to access the camera and microphone, you should answer "Allow". To avoid repeated requests, you can check the box "Remember for all cameras and microphones". If access was denied, you should reload the page and give permission again. ![Firefox prompt to share camera and microphone with the Remember checkbox and Allow button]() # 5\. Screen access **To provide screen access in any browser, you need the following**: Go to your browser settings and make sure that the proctoring site has all the necessary permissions. To access the screen, the site must have "Window management" permission (the name may vary in different browsers) ## 5.1. In Chrome Browser There are three ways to allow access to the screen on a computer in the Chrome browser: 1. In the version of Chrome 92+, access to the screen is requested automatically, no additional actions are required 2. In older versions of Chrome, you need to install the Supervisor browser extension 3. Instead of the extension, you can allow access to the screen with a special flag, which must be specified as an argument when running the "chrome.exe" file: `--enable-usermedia-screen-capturing` You should provide access to the **entire screen** ![Chrome screen sharing dialog with the Entire Screen tab and Share button highlighted]() During the session the **access should not be withdrawn**, so you shouldn't click "Stop sharing", but you can click "Hide". ![Chrome notification bar saying the site is sharing your screen, with Stop sharing and Hide]() ## 5.2. In Firefox Browser There are two ways to allow access to the screen on a computer in the Firefox browser: - In Firefox 66+, access to the screen is automatically requested; no additional actions are required; - In older versions of Firefox, you must install the Supervisor browser extension. You should provide access to the entire screen. To do this, in the pop-up window in the window or screen selection field, select "Entire screen", and then click "Allow": ![Firefox prompt to share the entire screen with the Allow button]() ## 5.3. "Full-screen mode is disabled" message on MacOS If your browser window is maximized, but the "Full-screen mode is disabled" warning still appears in the bottom-left corner, please hide your bookmarks bar: - **Google Chrome:** Cmd + Shift + B - **Safari:** Cmd + Shift + B as well as similar panels and sidebars. ![Proctored quiz in Chrome on macOS with the bookmarks bar and the full-screen warning highlighted]() # 6\. Check for compatibility with WebRTC technology In order for online video surveillance to work properly, outgoing connections to ports on the users' network must be allowed: - `3478/tcp` - `3478/udp` - `49152-65535/udp` WebRTC verification can be done at [WebRTC Test](). To start the test, click on the "Start Test" button. If no problems are found, then all items should be green. ![WebRTC test results with microphone, camera, network, connectivity and bandwidth all green]() If the check fails, carry out the following steps: While using PC: - Step 1 - Disable VPN, if in use. - Step 2 - Disable the firewall, if using Windows OS. If not, go to step 3. [Instructions to disable the firewall.]() - Step 3 - Try connecting to a different internet service provider or sharing the internet from your phone. Also, if you are using a router, you should try connecting the cable directly to your computer/laptop. - Step 4 - Check the speed of your internet connection. [Link to check.]() The minimum incoming and outgoing internet connection speed to pass the test must be 256 kbps. While using smartphone or tablet: - Step 1 - Connect to the internet connection that you are using on your computer/laptop. - Step 2 - Disable any extraneous software, including antivirus. You should only have your browser running. - Step 3 - If none of the above helps, please contact your university/organization's technical support team, specifying your phone/tablet model and name and version of your phone's operating system. # 7\. No access to webcam or black square instead of video If a picture with a crossed out camera, a black rectangle, or a loading indicator is displayed, it means that the browser cannot access the camera or the camera does not work correctly. The reason may be problems with the webcam, the camera driver or access to the camera from a web browser, if the camera is in use by another application in the operating system (such as Skype or another browser), or access the camera is blocked Antivirus (ESET — static picture icon crossed out camera, Kaspersky — black screen). You should close all applications that can work with the camera, disable the antivirus (or camera protection in it) and update the current tab in the browser. You can try restarting the computer. ![ESET antivirus blocking example]() If everything else fails, you can try resetting Chrome by opening the "chrome://settings/resetProfileSettings" page and confirming the action. For Windows 10: 1. Select "Start" → "Settings" → "Privacy & security" → "Camera", then make sure your camera access is turned on. This setting lets any user on the device choose if they want apps to be able to access the camera. 2. Find Allow apps to access your camera and make sure it's turned on. This setting allows you to choose if any of your apps can access the camera. It doesn't set which specific apps can access the camera. ![Windows setting Allow desktop apps to access your camera switched On]() 3. Once you've allowed your apps to access the camera, you can change the setting for each app. Find the app you want, then turn on camera access for that app. 4. If you don't see an app in the list, it might be a desktop app. Find Let desktop apps access your camera and make sure it's turned on. You can't change camera access settings for individual desktop apps. ![Windows Privacy Camera settings with the device and app camera access toggles highlighted]() # 8\. The assessment page does not open in IFRAME Cookies of third-party sites should not be blocked in the browser, in Chrome this is done in the settings "Settings" → "Privacy and security" → "Cookies and other site data" or you can simply enter "chrome://settings/cookies" into the address bar. "Allow all cookies" should be enabled there. ![Chrome Cookies and other site data page with Allow all cookies selected]() Page loading can also be blocked by some browser extensions, such as VPN Proxy or [AdBlocker](). You should try disabling all third-party extensions. In the Chrome browser, this can be done on the "chrome://extensions/" page, which can be opened through "Menu" → "Advanced Tools" → "Extensions". # 9\. No access to the screen Access must be granted to the entire screen and no additional monitors must be connected to the computer and no multiple virtual desktops must be set up. Otherwise there will be an error when checking screen access. ## 9.1. macOS Starting with macOS "Catalina" 10.15, you need to grant additional permission in the system settings to access the browser screen. To do this, go to system settings in the System Preferences menu. ![macOS dialog asking to grant accessibility access, with the Open System Preferences button]() Then select "Security" → "Privacy". On the left, scroll down and click "Screen Recording". ![macOS Privacy tab with Screen Recording selected and the list of browsers]() In the suggested list, select the browser that you want to allow access to the screen recording. ![Google Chrome checked in the Screen Recording list]() After that, you will need to restart the browser. ![macOS prompt that Google Chrome can record the screen until it is quit, with Quit Now]() ## 9.2. Linux Sometimes in Linux there is a problem when only the mouse cursor is displayed instead of a picture from the screen. ![Linux screen share showing a black screen with only the mouse cursor circled]() This problem occurs if the original (proprietary) video driver is not installed on the computer. You need to install the driver, restart the computer, after which the screen should be shared correctly. # 10\. The MediaRecorder error on Safari ## 10.1. macOS The MediaRecorder option must be enabled in Safari on macOS for the system to work correctly. This is done by enabling the developer menu under "Safari" → "Properties" → "Show Develop menu in menu bar": ![Safari Advanced preferences with Show Develop menu in menu bar checked]() Then activate the "Develop" → "Experimental Features" → "MediaRecorder" option: ![Safari Develop menu with Experimental Features open and MediaRecorder enabled]() ## 10.2. iOS For the system to work correctly in iOS Safari, the MediaRecorder option must be enabled in the "Settings" → "Safari" → "Advanced" → "Experimental Features" → "MediaRecorder". ![iOS Experimental WebKit Features list with MediaRecorder switched on and highlighted]() # 11\. Scrolling does not work on Safari ## 11.1. iOS In iOS Safari, scrolling inside IFRAME elements may not work when "Async Frame Scrolling" is enabled in Safari. You should disable this option "Settings" → "Safari" → "Advanced" → "Experimental Features" → "Async Frame Scrolling". ![iOS Experimental WebKit Features list with Async Frame Scrolling highlighted and switched off]() # 12\. Turn off notifications and calls It is recommended to turn off notifications and incoming calls when passing proctoring on mobile devices or when connecting a mobile camera. To do this, follow the steps below. ## 12.1. iOS Safari Go to "Settings" → "Do not disturb" → enable "do not disturb" at the top, "Silence" → always, "Phone" → allow calls from → no one, Remove flag in "repeated calls". ![iOS Settings with Do Not Disturb highlighted]() ![iOS Do Not Disturb options with the required settings highlighted]() ## 12.2. Android Chrome Go to "Settings" → "Sound" → "Do not disturb" → "Switch off now". ![Android Settings, Sound and Do not disturb screens with Enable now switched on]() # 13\. Error "Session blocked" The error "Session blocked: This page was opened elsewhere, close this tab" means that the proctoring is opened in a separate page, browser, PC, mobile. You may pass the assessment only in one browser tab with the proctoring. In such cases, close all additional tabs and pass the assessment within your first window. ![Assessment is blocked message saying the page is already open in another tab]() # OctoProctor Features List ## 1\. Technical parameters | **No.** | **Name** | **Description** | | --- | --- | --- | | 1.1 | Load scaling | 5000 online participants in the cloud version. | | 1.2 | Supported operating systems | Windows 7+, macOS 10.13+, Linux, Chrome OS | | 1.3 | Work in browsers without installing a browser extension | Chrome 92+, Opera 90+, Firefox 85+, Edge 90+, Safari 14.1+, SEB 3.3.2.413+ | | 1.4 | Mobile support | Android 12+ (Chrome), iOS 13+ (Safari) | | 1.5 | Additional camera connection | Support for smartphone camera connection. | | 1.6 | Work via mobile Internet | Minimum network connection speed of 256 Kbps. | | 1.7 | Two-factor authentication | Support for 2FA by TOTP codes for certain user roles | | 1.8 | In-app browser validation | Automatic check for critical APIs before starting a session in embedded browsers (Slack, Telegram, etc.) | ## 2\. Integration | **No.** | **Name** | **Description** | | --- | --- | --- | | 2.1 | WebSDK | Implementing proctoring on a quiz page (JavaScript-library, "white label", branding). | | 2.2 | Link | Unique link integration with [JWT]() token and [IFRAME]() to open a quiz. | | 2.3 | LTI 1.1 and LTI 1.3 | Integration with LMS supporting [IMS LTI Standard](). | | 2.4 | SCORM | Integration with LMS supporting [SCORM Standard]() or play SCORM content inside a proctoring session. | | 2.5 | REST API\*\* | Flexibly configurable API for accessing proctoring data. | | 2.6 | Safe Exam Browser | [SEB]() browser integration to lock down a workstation for the duration of a monitored assessment. | | 2.7 | Without integration | Manage proctoring sessions and users through the admin interface, along with the ability for test-takers to register for the assessment. | | 2.8 | SCORM player | [SCORM]() packages can be uploaded to OctoProctor and configured via session parameters, allowing them to be launched directly within the proctored interface for the test-taker. The system automatically retrieves and displays the SCORM results in the session properties. For content security, it is possible to set a password on the uploaded SCORM package, which the system automatically uses for access. | | 2.9 | LTI 1.3 Deep Linking | A built-in Content Selector that allows LMS instructors and course administrators to easily choose and assign proctoring assessments directly from the LMS interface. | ## 3\. Test-taker's scenario | **No.** | **Name** | **Description** | | --- | --- | --- | | 3.1 | Self-registration | Self-registration by test-takers allows assessments to be organized without integration. | | 3.2 | Rules of the assessment | The stage with the text that the participant must agree to by checking the box. | | 3.3 | Planning the assessment time | The stage where the participant must select the date and time of the assessment. | | 3.4 | Automatic equipment check | The stage of checking browser compatibility, camera and microphone, screen capture, network connection. | | 3.5 | Participant profile completion | The stage at which a user completes a full name. It can be used without integration, or when the attendee information provided by the integration is insufficient. | | 3.6 | Face photo | The stage of manual facial photography (if this stage is disabled, the face is automatically photographed in the first minutes of the session). | | 3.7 | Passport photo | The step of manually photographing or scan uploading an ID or passport. | | 3.8 | Recording a workspace overview | The stage for capturing an overview of the participant's workspace using a smartphone camera or computer camera. | | 3.9 | Mobile camera connection | The stage of connecting an additional mobile camera (smartphone camera on Android and iOS). | | 3.10 | Video recording | Throughout the session, video is recorded from the webcam, computer screen, and an additional mobile camera. If the internet is unstable, the system retries saving data to minimise loss. | | 3.11 | Image capturing | Throughout the session periodic image snapshots are saved from all three sources: web camera, screen, smartphone camera. The feature is optional as a lightweight proctoring alternative or in addition to the full video recording. | | 3.12 | Chat with proctor | A participant can chat with the proctor when the proctor is watching a session. The chat is also available on the preliminary steps before the session starts. | | 3.13 | Scoring | Throughout the session, the system calculates an assessment of confidence in the outcome based on the collection and analysis of data on a number of indicators in real time. | | 3.14 | Violation notices | The system can notify a participant of problems and violations that are automatically detected by the system. | | 3.15 | Previewing video from the camera | During the session, a participant observes themselves through the camera, which appears as a small circle in the corner of the page. | | 3.16 | Content copy protection | The ability to copy content via the clipboard, to select content, to open the context menu (right-click), to save the content via the print dialog, and to use hotkeys is blocked. Hides the content immediately when focus is lost. Disables spell checking, writing suggestions, and translation. | | 3.17 | Blocking writing assistance | Enabling copy protection automatically deactivates native browser-based features for spell check, text prediction, and page translation for the duration of the exam | | 3.18 | Parallel login protection | Blocks simultaneous entry from multiple locations, including different tabs in the same browser, different browsers, and different devices. | | 3.19 | Screen lock out in the case of violations | The screen (access to an assignment) is locked when violations are detected; access is reinstated when the violation is corrected. | | 3.20 | Virtual camera detection | The ability to use virtual cameras on the computer to replace the image is blocked. | | 3.21 | Virtual machine detection | The system monitors for virtual machine usage to prevent workstation spoofing. If a virtual environment is identified, the system applies protocol flags that can restrict entry to the assessment or serve as evidence of a violation during post-exam analysis. | | 3.22 | Spoofing protection (liveness)\* | The system recognizes attempts to manipulate the live image from the camera or screen. | | 3.23 | Remote control and Overlay window detection | The system monitors pointer movements, clicks, and key presses to detect the use of remote control software or overlay windows during the assessment. | | 3.24 | Unauthorized hotkey tracking and blocking | The system detects the use of unauthorized keyboard shortcuts. Additionally, when the 'content' and 'lock' addons are enabled, it also triggers immediate page content locking upon attempts to use restricted combinations (e.g., Ctrl+any key, F1–F12, Alt+F1–F12, PrintScreen, ScrollLock, Pause, and Alt combinations). | | 3.25 | Whiteboard | A built-in whiteboard where the participant can draw, write formatted text and sketch diagrams without leaving the assessment, on desktop and mobile. The work is saved automatically and restored after a page reload. The content is not stored separately; it can be seen in the screen recording. | ## 4\. Synchronous and asynchronous proctoring *(Proctors observe sessions)* | **No.** | **Name** | **Description** | | --- | --- | --- | | 4.1 | Support a large number of participants simultaneously | Unlimited number of participants per proctor with the possibility of simultaneous online monitoring of up to 25 sessions by each proctor. | | 4.2 | Chat with participants | Correspondence with participants in the chat, file sharing is supported, there is an incident mode to temporarily block access to content. | | 4.3 | Video and audio communication with participants | The proctor can contact participants via voice or video at any time. | | 4.4 | Indication of violations | The system alerts proctors in real time to violations detected by participants. | | 4.5 | Multiple proctors per session | You can connect multiple proctors to each session for increased control (cross-checking, examination board) or to assist users. | | 4.6 | Early termination | A proctor can interrupt and force close a session, in which case a notification is sent to the participant. | | 4.7 | Reporting | Proctors can rate sessions positively or negatively, or mark them as uncertain, and leave a comment at the end of the session. | | 4.8 | Asynchronous proctoring | Proctors can view session logs in a recording, while the system automatically guides participants through a session. | | 4.9 | Conference rooms for proctors | There is a video link feature between proctors (committee members) for verbal assessments or assessments with boards. | | 4.10 | Proctor's work schedule | Proctors can create a schedule of their work to be used by participants when scheduling the assessment. | | 4.11 | Logging proctor's activities | The system includes proctor activity reporting to track and quantify the duration of live supervision. Session reports detail the time spent observing by each proctor, and a general section provides overall statistics on total supervision time and the percentage of session coverage by proctors. | ## 5\. Automated proctoring *(Sessions are evaluated by algorithms)* | **No.** | **Name** | **Description** | | --- | --- | --- | | 5.1 | Automatic confidence assessment (credibility scoring) | Throughout the session, the system continuously collects data on 16 indicators and estimates the level of confidence from 0 to 100 percent. | | 5.2 | Automated identity verification | The system automatically tracks a participant's face throughout the session and assesses the degree of facial similarity to the baseline photo taken right before the session tracking an impersonation. Additionally, during the pre-session face capture step, the system compares the photo with the user's profile picture (if available), and the result is displayed on the session card. | | 5.3 | Voice and noise detection | The system monitors conversations and background noise. | | 5.4 | Automated passport recognition | The system can recognize an identity document (international passport) and verify the photo of the document with the photo of the participant's face. If both photos are present, this verification happens directly within the user profile, where the result is also stored. | | 5.5 | Automatic conclusion | The system can set an automatic conclusion (positive, negative or uncertain) for each session based on predefined criteria. Sessions with an uncertain conclusion are automatically flagged with an "undecided" status for manual review | | 5.6 | Virtual proctor (answering questions) | The system can automatically respond to a participant in a chat room according to a predetermined script. | ## 6\. Getting results | **No.** | **Name** | **Description** | | --- | --- | --- | | 6.1 | Interactive report | It includes video recordings from the camera (additional camera and proctor camera in case of communication) and the participant's screen, chat, camera and screen shots, facial photos, automatic assessment of confidence in results and verification of identity, timeline with video navigation. Accessible from the proctor and administrator dashboards, and link. | | 6.2 | Receive results | Webhooks, CSV, ZIP (video archive with embedded player) | | 6.3 | Print version report | PDF | ## 7\. Delivery options | **No.** | **Name** | **Description** | | --- | --- | --- | | 7.1 | Cloud | Delivered as Software as a Service (SaaS). The proctoring system runs in the cloud with Internet access. Monitoring, maintenance, and updates are provided by the vendor. | | 7.2 | On-premises | The proctoring system is deployed on the customer's servers within their infrastructure. Provides full control over data and can operate within a local network without Internet access. | | 7.3 | License-based feature management | Access to additional modules (add-ons), metrics and features is strictly controlled by the license key parameters. Unsupported or unlicensed features are automatically disabled in the administration interface. | | 7.4 | White label | Allows removing the default "OctoProctor" branding, window titles, and "Powered by OctoProctor" watermarks from the administrator, proctor, and test-taker interfaces. | - \* – this functionality is under development - \*\* – this functionality is deprecated # OctoProctor system installation and upgrade Guide # 1\. System architecture The architecture of the proctoring system is shown in the figure below. ![Architecture diagram: application server connected to S3, MongoDB, recognition API, TURN server and users]() The server part consists of the following components: - Application server — [Node.js]() environment for launching server applications; a web server and the core of the proctoring system are launched in it. - DBMS server — [MongoDB]() database management system server, you can use your own server or cloud service with API support for MongoDB. - File storage — AWS S3 compatible storage of downloaded files to the proctoring system; The bundled on-premise installation uses [Silo](), a community-maintained fork of the open-source MinIO server; you can also use your own S3-compatible server or a cloud service with a compatible API. - TURN server — a server to support the operation of the video communication module via WebRTC, you can use your own server (for example, [coturn]()) - Face and Document Recognition API — facial recognition and document recognition software is part of the proctoring system. Use [the hardware calculator]() to calculate the computing power of the server based on the expected load. The server part of the system requires an operating system (OS) based on a 64-bit Linux distribution. Ubuntu, Debian, CentOS or other similar distributions can be used. The proctoring system requires Docker software (software) or other environment to run Docker containers. However, you can use cloud services for DBMS server (MongoDB-compatible) and file storage (S3-compatible). # 2\. Running the system via Docker Compose This is the preferred way to run the system on a single server. ## 2.1. Server preparation This section of the instructions describes how to run all system components via Docker Compose (see [Docker Compose installation instructions]()). ## 2.2. Preparing a configuration file All settings for running proctoring components (containers) are written in the Docker Compose file (`docker-compose.yml`) and the environment variables file (`.env`). The script for launching containers is designed so that, for the specified domain (the `DOMAIN_NAME` variable), Certbot automatically issues an SSL certificate from Let's Encrypt for 90 days. This is a typical `docker-compose.yml` file for running all containers: ``` services: node: depends_on: mongo: condition: service_healthy silo: condition: service_healthy recognizer: condition: service_healthy image: public.ecr.aws/s8z4o5f0/node:latest restart: always networks: - backend ports: - "0.0.0.0:80:80/tcp" - "0.0.0.0:443:443/tcp" volumes: - cert:/etc/letsencrypt - webroot:/var/www environment: DISTRIB_URL: ${DISTRIB_URL} DISTRIB_KEY: ${DISTRIB_KEY} MONGO_URI: mongodb://admin:${MONGO_SECRET:-secret}@mongo:27017/proctoring?authSource=admin S3_URI: http://minioadmin:${MINIO_SECRET:-minioadmin}@silo:9000/proctoring RECOGNIZER_URI: http://${RECOGNIZER_SECRET:-secret}@recognizer:8080/recognize TURN_URI: turn://webrtc:${TURN_SECRET:-webrtc}@${DOMAIN_NAME:-localhost}:3478?transport=udp+tcp SESSION_KEY: ${SESSION_KEY:-secret} #SSL_KEY: -----BEGIN RSA PRIVATE KEY-----\n... #SSL_CERT: -----BEGIN CERTIFICATE-----\n... SSL_KEY: /etc/letsencrypt/live/${DOMAIN_NAME:-localhost}/privkey.pem SSL_CERT: /etc/letsencrypt/live/${DOMAIN_NAME:-localhost}/cert.pem SSL_CA: /etc/letsencrypt/live/${DOMAIN_NAME:-localhost}/chain.pem PORT: 443 HTTP_PORT: 80 HTTP_WEBROOT: /var/www MANAGER_USERNAME: ${MANAGER_USERNAME:-manager} MANAGER_PASSWORD: ${MANAGER_PASSWORD:-ChangeMe12345} MANAGER_HOST: ${DOMAIN_NAME} PASSWORD_RULE: ${PASSWORD_RULE:-} healthcheck: test: [ "CMD", "curl", "-sS", "-m", "10", "http://127.0.0.1/ping" ] recognizer: image: public.ecr.aws/s8z4o5f0/recognizer:latest restart: always networks: - backend #ports: # - "0.0.0.0:8080:8080/tcp" environment: PORT: 8080 API_KEY: ${RECOGNIZER_SECRET:-secret} healthcheck: test: [ "CMD", "curl", "-sS", "-m", "10", "http://127.0.0.1:8080/ping" ] mongo: image: docker.io/library/mongo:8.0 restart: always networks: - backend #ports: # - "0.0.0.0:27017:27017/tcp" volumes: - db:/data/db - configdb:/data/configdb environment: MONGO_INITDB_ROOT_USERNAME: admin MONGO_INITDB_ROOT_PASSWORD: ${MONGO_SECRET:-secret} #command: mongod --replSet rs0 --keyFile /data/configdb/mongo.keyfile healthcheck: test: [ "CMD", "mongosh", "--eval", "db.adminCommand('ping')" ] silo: image: docker.io/pgsty/silo:latest restart: always networks: - backend #ports: # - "0.0.0.0:9000:9000/tcp" # - "0.0.0.0:9001:9001/tcp" volumes: - storage:/data environment: MINIO_ROOT_USER: minioadmin MINIO_ROOT_PASSWORD: ${MINIO_SECRET:-minioadmin} command: server /data --address ":9000" --console-address ":9001" healthcheck: test: [ "CMD", "curl", "-sS", "-m", "10", "http://127.0.0.1:9000/minio/health/live" ] turn: image: coturn/coturn:latest restart: always network_mode: host volumes: - turn:/var/lib/coturn environment: REAL_EXTERNAL_IP: "" command: --no-cli --log-file=stdout --lt-cred-mech --fingerprint --max-allocate-timeout=60 --listening-port=3478 --min-port=49152 --max-port=65535 --realm=${DOMAIN_NAME:-localhost} --user=webrtc:${TURN_SECRET:-webrtc} --external-ip=$(detect-external-ip) certbot: image: certbot/certbot:latest network_mode: host depends_on: node: condition: service_healthy volumes: - cert:/etc/letsencrypt - webroot:/var/www command: certonly --agree-tos --keep-until-expiring --webroot --webroot-path=/var/www --email=admin@${DOMAIN_NAME:-localhost} --no-eff-email --domains=${DOMAIN_NAME:-localhost} networks: backend: volumes: db: configdb: storage: turn: cert: webroot: ``` The `.env` file contains environment variables in the format `VARIABLE=VALUE`, which are described in the table below: | **Parameter** | **Description** | | --- | --- | | `DISTRIB_URL` | Distribution archive URL (issued by supplier) | | `DISTRIB_KEY` | Distribution archive password (issued by supplier) | | `DOMAIN_NAME` | Server public domain | | `MONGO_SECRET` | MongoDB database password for admin | | `MINIO_SECRET` | Silo storage password | | `TURN_SECRET` | Password to connect to the TURN server | | `RECOGNIZER_SECRET` | Recognition API access key | | `SESSION_KEY` | Session secret key | | `MANAGER_USERNAME` | Manager username | | `MANAGER_PASSWORD` | Manager user password | | `PASSWORD_RULE` | `'^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z]).{12,}$'` | > **WARNING:** Environment variables `MONGO_SECRET`, `MINIO_SECRET`, `TURN_SECRET` and `RECOGNIZER_SECRET` must not contain special characters, only the following characters are allowed: `a-zA-Z0-9` > > All user passwords must follow `PASSWORD_RULE`: at least 12 characters, including at least one uppercase letter, one lowercase letter, and one number. ## 2.3. Launching containers You can create and run all containers at once with the following command from the directory where the `docker-compose.yml` file is located: ``` docker compose up -d ``` ## 2.4. Stopping containers You can stop and remove all containers at once with the following command from the directory where the `docker-compose.yml` file is located: ``` docker compose down ``` # 3\. Running the system via Docker CLI You can use this method to manage Docker containers more flexibly without using Docker Compose. ## 3.1. Server preparation This section of the manual describes how to run all system components in Docker (see [Docker installation instructions]()). ## 3.2. MongoDB server ### 3.2.1. Single server Create a volume on the host where the database files will be stored: ``` docker volume create db docker volume create configdb ``` Run container `mongo`: ``` docker run -d --name mongo --network host --restart always \ -v db:/data/db \ -v configdb:/data/configdb \ -e "MONGO_INITDB_ROOT_USERNAME=admin" \ -e "MONGO_INITDB_ROOT_PASSWORD=secret" \ mongo:8.0 ``` Environment variables (set in the `-e` parameter): ``` # database administrator login MONGO_INITDB_ROOT_USERNAME=admin # database administrator password MONGO_INITDB_ROOT_PASSWORD=secret ``` DB connection string: ``` mongodb://admin:secret@127.0.0.1:27017/proctoring?authSource=admin ``` ### 3.2.2. Cluster configuration Create volumes on the host in which the database files and configs will be stored: ``` docker volume create db docker volume create configdb ``` For MongoDB, the cluster configuration is configured using the [Replica Set]() as one Primary node and one or more Secondary nodes. In order for the nodes of the MongoDB cluster to communicate with each other, the same key must be registered on all cluster nodes. You can [generate a key]() with the command: ``` KEYFILE=/var/lib/docker/volumes/configdb/_data/mongo.keyfile if [ ! -e "$KEYFILE" ] then openssl rand -base64 756 | tee $KEYFILE chmod 400 $KEYFILE fi ``` Run a "mongo" container on a replica named "rs0" on each host (for example, "mongodb01" and "mongodb02"): ``` docker run -d --name mongo --network host --restart always \ -v db:/data/db \ -v configdb:/data/configdb \ -e "MONGO_INITDB_ROOT_USERNAME=admin" \ -e "MONGO_INITDB_ROOT_PASSWORD=secret" \ mongo:8.0 \ mongod --replSet rs0 --keyFile /data/configdb/mongo.keyfile ``` Environment variables (set in the `-e` parameter): ``` # database administrator login MONGO_INITDB_ROOT_USERNAME=admin # database administrator password MONGO_INITDB_ROOT_PASSWORD=secret ``` Command parameters: ``` # name of replica set --replSet rs0 # path to the replica key file --keyFile /data/configdb/mongo.keyfile ``` Initialize the cluster with the command: ``` docker exec -it mongo mongosh -u admin -p secret --authenticationDatabase admin > rs.initiate( { _id: "rs0", version: 1, members: [ { _id: 0, host: "mongodb01:27017" }, { _id: 1, host: "mongodb02:27017" } ] } ) ``` DB connection string: ``` mongodb://admin:secret@mongodb01:27017,mongodb02:27017/proctoring?authSource=admin&replicaSet=rs0 ``` ## 3.3. File storage ### 3.3.1. Local storage Silo Create a volume on the host where the repository files will be stored: ``` docker volume create storage ``` Run container `minio`: ``` docker run -d --name silo --network host --restart always \ -v "storage:/data" \ -e "MINIO_ROOT_USER=minioadmin" \ -e "MINIO_ROOT_PASSWORD=minioadmin" \ docker.io/pgsty/silo:latest \ server /data --address ":9000" --console-address ":9001" ``` Environment variables (set in the `-e` parameter): ``` # login to access the storage MINIO_ROOT_USER=minioadmin # password to access the storage MINIO_ROOT_PASSWORD=minioadmin ``` Command parameters: ``` # listening port --address ":9000" # port for console --console-address ":9001" ``` Storage connection string: ``` http://minioadmin:minioadmin@127.0.0.1:9000/proctoring ``` ### 3.3.2. Silo storage tiers When storing large amounts of data, in some cases it may be worthwhile to configure two data storage tiers: "hot" storage and "cold" storage. This allows you to use a small amount of "hot" storage with fast disks to ensure correct operation of the system under heavy load, and store archived data in "cold" storage on slower and cheaper disks. At the same time, set up a rule for automatically moving data from "hot" storage to "cold" storage, for example, after 1 day, without losing access to this data through the proctoring system. Below are step-by-step instructions on how to configure two Silo servers with automatic data transition according to the rule from one server to another: 1. Launch two Silo servers. Let it be minio1 (port 9000, on fast disks) and minio2 (port 9100, on slow disks). 2. Download [Silo Client]() (mc). 3. Configure **mc** to interact with the minio1 server: ``` mc alias set minio1 http://127.0.0.1:9000 mc alias set minio2 http://127.0.0.1:9100 ``` where `` and `` are storage access keys. 4. Create buckets on both hot and cold storage: ``` mc mb minio1/proctoring mc mb minio2/proctoring ``` 5. Create Lifecycle and Tier Management Policy: ``` cat > lifecycle-policy.json << 'EOF' { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetLifecycleConfiguration", "s3:PutLifecycleConfiguration", "s3:ListBucket" ], "Resource": ["arn:aws:s3:::proctoring"] }, { "Effect": "Allow", "Action": [ "admin:SetTier", "admin:ListTier" ], "Resource": ["arn:aws:s3:::proctoring"] } ] } EOF ``` 6. Configure Lifecycle and Tier Management Policy: ``` mc admin policy create minio1 LifecycleAdminPolicy lifecycle-policy.json mc admin user add minio1 mc admin policy attach minio1 LifecycleAdminPolicy --user=minio1LifecycleAdmin ``` where `` is the policy administrator login, `` is the policy administrator password. 7. Configure remote storage tier: ``` mc ilm tier add minio minio1 MINIO_COLD_TIER \ --endpoint http://127.0.0.1:9100 \ --access-key \ --secret-key \ --bucket proctoring \ --storage-class STANDARD ``` where `` and `` are access keys to the second MinIO server, `proctoring` is the name of the bucket, `http://127.0.0.1:9100` is the address of the second MinIO server. 8. Create and apply the transition rule (1 day after files are uploaded) with the name "MINIO\_COLD\_TIER": ``` mc ilm rule add minio1/proctoring \ --transition-tier MINIO_COLD_TIER \ --transition-days 1 \ --noncurrent-transition-tier MINIO_COLD_TIER \ --noncurrent-transition-days 1 ``` 9. Check the transition rule: ``` mc ilm rule ls minio1/proctoring --transition ``` You can read more about setting up storage levels and transfer rules in [the official Silo documentation](). ### 3.3.3. Amazon S3 You can use [Amazon S3]() as storage, you don't need to install anything extra for this. Storage connection string ("proctoring" bucket): ``` https://access_key_id:secret_key@s3.eu-west-1.amazonaws.com/proctoring?region=eu-west-1 ``` > **NOTE:** > > - `eu-west-1` should be your S3 region that you really use; > - `access_key_id` and `secret_key` can only be uppercase or lowercase Latin characters and numbers, if not regenerate it; > - `proctoring` is a bucket name in S3 that must be created before. ## 3.4. Face and Document Recognition API Run container `recognizer`: ``` docker run -d --name recognizer \ --network host --restart always \ -e "API_KEY=secret" \ public.ecr.aws/s8z4o5f0/recognizer:latest ``` Environment variables (set in the `-e` parameter): ``` # server IP HOST=0.0.0.0 # server port PORT=8080 # number of workers (auto if not set) THREADS=4 # API access key API_KEY=secret # flag for rebuilding if the processor # does not support AVX instructions DLIB_REBUILD=1 ``` Recognition API connection string: ``` http://secret@127.0.0.1:8080/recognize ``` Recognition API connection string for multiple servers (for example "recognizer01" and "recognizer02"): ``` http://secret@recognizer01:8080,recognizer02:8080/recognize ``` ## 3.5. TURN server Run container `turn`: ``` docker run -d --name turn --network host --restart always \ coturn/coturn:latest \ --no-cli --log-file=stdout --lt-cred-mech --fingerprint \ --max-allocate-timeout=60 --listening-port=3478 --min-port=49152 --max-port=65535 \ --user=webrtc:webrtc --realm=proctoring --external-ip='$(detect-external-ip)' ``` Ports used (should be available from clients): - `3478/tcp` - `3478/udp` - `49152-65535/udp` (optional) Command parameters: ``` # TURN server port --listening-port=3478 # range of UDP ports --min-port=49152 --max-port=65535 # user credentials as : --user=webrtc:webrtc # external IP address (or determine automatically) --external-ip='$(detect-external-ip)' ``` TURN connection string: ``` turn://webrtc:webrtc@:3478?transport=tcp+udp ``` where `` is the external IP address of TURN server, if there are several servers, their addresses should be separated by comma; `webrtc:webrtc` is the default username and password to connect to TURN; `3478` is the port of TURN server; transport is the used transport `tcp` or `udp`, `tcp+udp` indicates the need to use both transports. To check the operation of the TURN server in the browser we can use [the Trickle ICE page](). To do this you need to enter the connection parameters to the server on this page: - TURN URI: `turn::3478?transport=udp` - TURN username: `webrtc` - TURN password: `webrtc` Then click on "Add Server" and "Gather candidates". As a result, the table on this page should list the following connection types in the "Component Type" field: - `host` — client's local IP address; - `srflx` — external IP address of the client; - `relay` — external IP address of the TURN server, must match ``. If at least one type is not on the list, the access to the TURN server is configured incorrectly. Check if the connections are not blocked by the firewall or intermediate routers in the network. If the TURN check fails, then the reason may be blocking UDP traffic between the client and the server. You can check the transmission of UDP traffic between clients and the server on a specific port using the following commands: *Server* ``` nc -u -l -p ``` *Client* ``` echo -n "ping" | nc -u -w 5 ``` ## 3.6. Application server ### 3.6.1. Let's Encrypt SSL certificate The system requires a valid SSL certificate for the domain. You can issue a free [Let's Encrypt]() SSL certificate valid for 3 months. To do this, just use the [Certbot]() tool: ``` docker volume create cert docker volume create webroot docker run --network host \ -v "cert:/etc/letsencrypt" \ -v "webroot:/var/www" \ certbot/certbot:latest \ certonly --agree-tos --keep-until-expiring \ --webroot --webroot-path=/var/www \ --email=admin@ --no-eff-email \ --domains= ``` After successful execution of the command, the certificate will be available in the `/etc/letsencrypt/live//` directory: - certificate: `cert.pem` - chain: `chain.pem` - private key: `privkey.pem` In this example, Certbot uses a webroot directory to share the files required for the HTTP challenge. This means that you need to start the application server first. Alternatively, you can run Certbot in standalone mode (use `--standalone` parameter instead of `--webroot`), which runs an internal web server. ### 3.6.2. Running instance The application server instance must be bound to a single domain, and a license will be issued for that domain. The application server can be run on one node or multiple nodes (horizontal scaling). When running the application server on multiple nodes, all instances must have the same parameters specified in the environment variables. Start the container `node`: ``` docker run -d --name node --network host --restart always \ --tmpfs /tmp \ -v "cert:/etc/letsencrypt" \ -v "webroot:/var/www" \ -e "DISTRIB_URL=https://files.proctoring.app/dist/proctoring-vXYZ.zip" \ -e "DISTRIB_KEY=secret" \ -e "MONGO_URI=mongodb://admin:secret@127.0.0.1:27017/proctoring?authSource=admin" \ -e "S3_URI=http://minioadmin:minioadmin@127.0.0.1:9000/proctoring" \ -e "RECOGNIZER_URI=http://secret@127.0.0.1:8080/recognize" \ -e "TURN_URI=turn://webrtc:webrtc@:3478?transport=tcp+udp" \ -e "SESSION_KEY=secret" \ -e "SSL_KEY=/etc/letsencrypt/live//privkey.pem" \ -e "SSL_CERT=/etc/letsencrypt/live//cert.pem" \ -e "SSL_CA=/etc/letsencrypt/live//chain.pem" \ -e "PORT=443" \ -e "HTTP_PORT=80" \ -e "HTTP_WEBROOT=/var/www" \ -e "MANAGER_USERNAME=manager" \ -e "MANAGER_PASSWORD=ChangeMe12345" \ -e "MANAGER_HOST=" \ public.ecr.aws/s8z4o5f0/node:latest ``` Environment variables (set in the `-e` parameter): ``` # proctoring system distribution kit URL DISTRIB_URL=https://files.proctoring.app/dist/proctoring-vX_Y_Z.zip # distribution kit password (issued separately) DISTRIB_KEY=secret # server IP HOST=0.0.0.0 # server port PORT=443 # port forwarding from http to https HTTP_PORT=80 # server response timeout HTTP_TIMEOUT=60 # directory for /.well-known/acme-challenge HTTP_WEBROOT=/var/www # number of threads, by default equal to the number of vCPUs THREADS=4 # MongoDB connection string MONGO_URI=mongodb://admin:secret@127.0.0.1:27017/proctoring?authSource=admin # S3 storage connection string S3_URI=http://minioadmin:minioadmin@127.0.0.1:9000/proctoring # recognition API connection string RECOGNIZER_URI=http://secret@127.0.0.1:8080/recognize # TURN Server connection string TURN_URI=turn://webrtc:webrtc@:3478?transport=tcp+udp # secret key for sessions (random character set) SESSION_KEY=secret # session lifetime in minutes SESSION_EXPIRES=180 # private key (content or file path) SSL_KEY=/etc/letsencrypt/live//privkey.pem # SSL certificate (content or file path) SSL_CERT=/etc/letsencrypt/live//cert.pem # certification authority bundle (content or file path) SSL_CA=/etc/letsencrypt/live//chain.pem # limit on the size of uploaded files in MiB UPLOAD_LIMIT=100 # storage time of unused downloaded files in minutes UPLOAD_EXPIRES=60 # time of caching statics on the client in minutes STATIC_EXPIRES=60 # directory of static files STATIC_DIR=/path/to/dir # manager login MANAGER_USERNAME=manager # manager password MANAGER_PASSWORD=ChangeMe12345 # host (and port, if non-standard) to login under the manager role MANAGER_HOST= # password complexity with a regular expression # minimum 12 chars, at least one uppercase, one lowercase, one number PASSWORD_RULE=^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z]).{12,}$ # number of unsuccessful authentication attempts PASSWORD_ATTEMPTS=5 # lock account after maximum login attempts for N minutes PASSWORD_HOLDOFF=5 # maximum depth of old password history for checking used passwords PASSWORD_HISTORY=5 ``` Note that you should replace the `` string with your actual domain name. # 4\. Setting up a reverse proxy Usually the following settings are not required. However, if you are already using a reverse proxy server, you may need to configure the proctoring system to work through it. ## 4.1. Installing and configuring Nginx Access to the system from the Internet can be configured through the proxy server [Nginx](), you can install it in Ubuntu as follows: ``` sudo apt-get install -y nginx ``` Virtual host configuration in nginx: ``` location / { client_max_body_size 100m; proxy_pass http://127.0.0.1:3000; proxy_redirect off; proxy_http_version 1.1; proxy_pass_request_headers on; proxy_set_header Host $host; proxy_set_header Origin $http_origin; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Authorization $http_authorization; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-By $server_addr:$server_port; proxy_set_header X-Forwarded-Proto $scheme; } ``` ## 4.2. Installing and configuring Apache Installing [Apache Web Server]() on Ubuntu: ``` sudo apt-get install -y apache2 ``` Apache 2.4 virtual host configuration: ``` RewriteEngine On RewriteCond %{REQUEST_URI} ^/ws [NC] RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L] # RequestHeader set Host "your-proctoring-domain" ProxyPreserveHost On ProxyPass "http://127.0.0.1:3000/" ProxyPassReverse "http://127.0.0.1:3000/" ``` Apache must have [mod\_proxy](), [mod\_proxy\_http](), [mod\_proxy\_wstunnel](), and [mod\_rewrite]() modules enabled. # 5\. System upgrade Below are the actions that you have to perform consistently to update the version of the proctoring system. It is not always necessary to update all components. If only the application server has been updated, then it is sufficient to update only the "node" container. ## 5.1. Upgrade notes Keep in mind that upgrading individual system components may require additional migration actions. ### 5.1.1. Upgrade MongoDB Before upgrading to the next version of MongoDB, you should change the compatibility version in your database: - Connect to database by client (e.g. `mongosh`) ``` docker exec -it mongo mongosh -u admin -p secret --authenticationDatabase admin ``` - To set or update "featureCompatibilityVersion", run the following command: ``` db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } ) ``` See more details in [the official upgrade guide](). ### 5.1.2. Switching file storage to Silo (OctoProctor v. 5.13.0) This applies only to installations created before version 5.13.0, which use the `minio/minio` image for file storage. These images have been removed from Docker Hub, so such an installation cannot be reinstalled or upgraded with its old configuration. To switch to Silo, replace your `docker-compose.yml` with the file from Section 2.2: 1. Make sure that all passwords and keys are set in the `.env` file. If your current `docker-compose.yml` contains them directly, move them to `.env` first. 2. Place the new `docker-compose.yml` in the same directory as the old one. This keeps your existing data volumes. 3. Transfer any changes you made to the old file yourself, such as additional ports or environment variables. 4. Start the new version with the `--remove-orphans` parameter (see Section 5.5) to remove the old `minio` container. Silo is a community-maintained fork of MinIO: it serves your existing storage volume in place, so no data migration is required. ### 5.1.3. Upgrade Recognizer You should use the "latest" tag of the Recognizer Docker image `public.ecr.aws/s8z4o5f0/recognizer:latest` with the proctoring system v4.13 and higher. For older versions you should use the "old" tag. ## 5.2. Database backup To back up the database: ``` docker exec mongodump -u -p \ --authenticationDatabase admin -d --archive --gzip > /path/to/backup/db.dump ``` where `` is the name of the "mongo" container, which can be viewed using the command `docker ps`; `` is the username of the database user; `` is the DB user password; `` is the name of the database ("proctoring" by default); `/path/to/backup/db.dump` is the dump file. If the `mongo` image has not been updated, then this step is not necessary. ## 5.3. File storage backup To back up the file storage: ``` wget -qO- | tar -xz -O mcli > /usr/local/bin/mc chmod +x /usr/local/bin/mc mc alias set local http://127.0.0.1:9000 mc mirror local/proctoring /path/to/backup/s3 ``` where `` is the link to the latest client archive for your platform (for example, `mcli_..._linux_amd64.tar.gz`) from the [Silo Client releases page](); `` is the storage access key; `` is the storage access password; `proctoring` is the name of the proctoring bucket; `/path/to/backup/s3` is the directory for saving the storage backup. ## 5.4. Uninstalling a previous version Stop and remove all containers, remove all images: ``` docker compose down ``` ## 5.5. Installing a new version Start a new installation: ``` docker compose up -d --force-recreate --pull always --remove-orphans ``` ## 5.6. Reading logs Read the specified container log: ``` docker logs -f ``` where `` is the name of the container, which can be viewed using the command `docker ps`. ## 5.7. Database recovery To restore the database: ``` cat /path/to/backup/db.dump | docker exec -i mongorestore \ -u -p --authenticationDatabase admin --archive --gzip ``` where `` is the name of the "mongo" container, which can be viewed using the command `docker ps`; `` is the DB user login; `` is the DB user password; `/path/to/backup/db.dump` is the dump file. If you have not made a backup copy of the database, then this step should be skipped. ## 5.8. File storage recovery To restore the file storage data: ``` mc alias set local http://127.0.0.1:9000 mc mirror /path/to/backup/s3/ local/proctoring ``` where `` is the storage access key; `` is the storage access password; `proctoring` is the name of the proctoring bucket; `/path/to/backup/s3/` is the directory for saving the storage backup. If you have not made a backup copy of the file storage, then this step should be skipped. # 6\. Log in The system can be accessed at the address specified during deployment (for example, `https://your-domain`). Authorization parameters for the manager by default are as follows: - login: `manager` - password: `ChangeMe12345` After the first login under the manager, you need to add a host configuration based on a license key that is issued by supplier for a specific domain, term and volume. # Use cases # Use case for Google Forms and Microsoft Forms # 1\. Using Google Forms To open Google Form with proctoring follow these steps: - Open the form in edit mode, then press the "Send" button: ![Google Forms editor with the Send button highlighted]() - Then copy the link that appears in the `<>` tab: ![Google Forms Send form dialog with the Embed HTML tab and iframe code]() You will receive a code like the one below (see the "src" attribute): ``` ``` - Paste the copied link into the "URL" field in the session card: ![Session card with the URL field highlighted]() # 2\. Using Microsoft Forms To open Microsoft Form with proctoring, follow these steps: - Open the form in edit mode, then press the "Send" button: ![Microsoft Forms editor with the Send button highlighted]() - Then copy the link that appears in the `` button: ![Microsoft Forms Send panel with the embed code button and Copy button]() You will receive a code like the one below (see after the "src" attribute): ``` ``` - Paste the copied link into the "URL" field in the session card: ![Session card with the URL field highlighted]() # Safe Exam Browser implementation Guide # 1\. Safe Exam Browser installation Safe Exam Browser (SEB) is an educational and reference software designed for desktop and mobile devices. It is used for educational and training purposes, allowing you to temporarily turn any computer into a secure workstation that operates seamlessly within a web browser environment. SEB enables control over access to resources such as system functions, third-party websites, and applications, preventing the use of unauthorized resources during an assessment. The full user manual for Safe Exam Browser for Windows is available at [this link](). The installation procedure is straightforward. Follow these steps: 1. Download and install Safe Exam Browser from [the official website](). 2. Select the latest version of SEB Exam Browser (available for macOS or Windows). 3. You will be redirected to sourceforge.net, where the download of the setup file will begin after a few seconds. In some cases, you may need to grant your browser permission to download. 4. **Run the installation file `setup.exe` as an administrator.** Check the box to agree to the license terms and conditions, then start the installation. Wait for it to complete. 5. Two shortcuts will appear on your device: Safe Exam Browser and SEB Configuration Tool. ![Start menu showing Safe Exam Browser and SEB Configuration Tool shortcuts]() # 2\. Proctoring template configuration To use Safe Exam Browser, you need to configure specific settings for templates or sessions in the OctoProctor proctoring system. Go to the "Addons" tab of your template or session and enable the "seb" addon: Allow launching only from SEB (Safe Exam Browser). > **NOTE:** Some add-ons related to the participant interface may not function properly in Safe Exam Browser, including: > > - calculator widget (`calculator`) > - chat with the proctor (`chat`) > - allow uploading files to chat (`upload`) > - allow participants to finish the session (`finish`) So in order for these elements to appear, please make sure the following add-on is enabled: Webcam preview and toolbar (`preview`) ![Session card Addons tab with the Webcam preview and toolbar add-on enabled]() ![Participant toolbar with calculator, chat and finish buttons above the webcam preview]() As a result of these actions, a preview window with a toolbar (`preview`) will be available on the participant's interface side. # 3\. SEB Configuration Tool settings > **NOTE:** To ensure SEB functions correctly with the screen-sharing required by OctoProctor, please verify that the following settings are configured under the **Security** tab. > > **Windows:** > > - Enable 'Allow remote session/screen sharing' > - Enable 'Kiosk Mode - Create new desktop' > - Enable 'Allow screen capturing and recording' > - Disable 'SEB Service - Ignore SEB service' > - Choose 'allow to use SEB only with service' > > **macOS:** > > - Enable 'System lockdown -\> Kiosk Mode (win) - create new desktop' > - Enable 'Allow screen capture/recording' > - Enable 'Allow window capture (screen shots)' > - Disable 'Prefer Assessment Mode (AAC)' > - Disable 'SEB Service - Ignore SEB service' > - Choose 'allow to use SEB only with service' Before starting an assessment with proctoring, configure SEB using the SEB Configuration Tool. Follow these steps: 1. Launch the SEB Configuration Tool. 2. In the "General" menu, insert the link to the assessment page in the "Start URL" field. ![SEB Configuration Tool General tab with the Start URL field highlighted]() 3. In the "Exam" menu, check the "Use Browser Exam Key and Configuration Key" option to avoid an error about an unsupported browser during the equipment check. Also, insert the assessment page link in the "Back to Start Button" field. ![SEB Configuration Tool Exam tab with Browser Exam Key option and Back to Start Button highlighted]() 4. In the "Application" tab, add applications (executable `.exe` files) to block during the session. Click "Choose application" and select each application to block. Unlisted applications will remain accessible during the assessment. ![SEB Configuration Tool Applications tab with the Choose Application button highlighted]() 5. To apply the settings, click "Use Settings" → "Configure Client". ![Use Settings menu with Configure Client highlighted]() This completes the basic setup. # 4\. SEB video playback Safe Exam Browser does not support some video formats. If your assessment includes an embedded MP4 video, it will not play. A solution is to convert the video to a supported format, such as `.webm`. # 5\. SEB file saving To standardize browser settings across all test-takers' devices, save the settings file and distribute it to participants. Save the file via "File" → "Save Settings As...": ![File menu of the SEB Configuration Tool with Save Settings As highlighted]() ![Saved SEB settings file icon]() Participants must then upload the settings file into their browser instances using "File" → "Open Settings...". # 6\. User cases Real-world examples of current system users: ### Case 1: Conducting Professional Online Certifications **Requirements**: The Company conducting online certifications must comply with government agency requirements. A key requirement is implementing a comprehensive monitoring system to record the assessment, check the background for foreign objects or people, and restrict the use of additional software and internet resources. **Solution**: Integrating the OctoProctor proctoring system with Safe Exam Browser enabled the Company to maintain a full media protocol of the assessment, conduct online observation, record webcam and browser activity, and use AI-proctoring metrics (e.g., the b2 metric for tab changes) to detect rule violations. SEB blocked prohibited applications on participants' devices. **Result**: The Company received permission to conduct certifications. During inspections, it can provide protocols with noted violations. Participants receive valid qualification documents from an authorized company. ### Case 2: Conducting Entrance Assessments to a Private Educational Institution **Requirements**: Prohibit use of unauthorized programs on the PC while allowing specific internet resources, enable direct communication with the teacher during the assessment, and monitor dozens of participants with limited administrative resources. **Solution**: Using OctoProctor with Safe Exam Browser, one teacher (proctor) can monitor up to 30 participants simultaneously with automated notifications and communicate via text, video, or audio. SEB's "Exam" and "Network" settings block third-party applications while permitting access to approved resources, and it can restrict keyboard shortcuts and file uploads/downloads. **Result**: Controlled selection ensures test-takers meet the institution's standards and have verified knowledge levels. Test-takers' success in regional and national competitions enhances the institution's reputation, attracting sponsors and applicants. # Use case without integration # 1\. How it works Normally, the proctoring system is integrated with the learning management system (LMS) to enable data transfer between them. On one side, the parameters of the assessment (exam or test) are transferred from the LMS to the proctoring system, and users and sessions are generated in the proctoring system based on this data. On the other side, after the proctoring sessions are passed, the results of the sessions are transmitted back to the LMS. This interaction allows for an explicit match between the LMS user and the proctoring user, and aggregates all assessment results in the LMS, both assessment and proctoring scores. However, for low profile assessments or where there is no option to make changes to the configuration or code of the LMS, it may be necessary to have a way of running assessments with proctoring without any integration. In such cases, the proctoring system provides a way of setting up assessments when no integration with the LMS is used. In this case assessments and proctoring sessions are set up independently, and results are saved separately. The following scenario describes the use of proctoring without integration with the LMS. # 2\. Setting the assessment parameters Each [assessment](), whether it is an assessment with proctoring, is configured through the proctoring administrator's interface. This is done using the session template functionality. To set up a session template (assessment parameters) you need to follow the steps below: 1. Log in to your proctoring server as an administrator. 2. Go to "Sessions" (opens by default). 3. On the toolbar, click the "+" (Add) button. 4. In the session card that opens, fill in the fields: - Identifier – the assessment identifier to be given to the participants. It can only consist of Latin letters of any case (`a-z`), numbers (`0-9`), an underscore (`_`) and a hyphen (`-`). - Student – leave blank, not filled in templates. - URL – a link to the assessment page that will open in the IFRAME immediately after the start of the proctoring session. - Members – a list of proctor logins that will have access to the sessions of this template. - Fill in the remaining fields according to the [administrator's]() [guide](). 5. Once you have filled in all the required fields, you need to save the settings. # 3\. Passing the assessment To take the proctoring assessment, the participant should go to the homepage of your proctoring server. On the page that opens, click on the "Sign Up" button. Alternatively, enter your login, password and click "Log In" if participants have been previously created in the proctoring system. ![Proctoring login window with Username and Password fields and the Sign Up button]() Once you have clicked on the "Sign Up" button, the assessment registration dialogue will open. ![Registration for the event dialog with login and event identifier fields]() A login is a unique and unchangeable identifier for a member. The login can be a telephone number, a time card number or other similar unique identifiers. If the login was done using the login and password, the login field will already be populated and cannot be changed. Each activity has a unique identifier (see previous section, referring to the session template identifier). Each proctored assessment can only be completed once by a participant, unless additional attempts are specified in the template settings. All participants need to be told in advance what to use as a login and what assessment identifier to use. This can be done on one of the LMS pages, by post or in any other way. For example: - **Login**: - your phone number – format 1234567890 - **Assessment identifier**: - Mathematics – maths - Physics – physics - IT – informatics When you have completed the fields, press the "OK" button. If you fill in the fields incorrectly, an error will be displayed. ![Registration dialog with a red error message about incorrect parameters]() If the parameters are correct, an interface should open with the steps to connect to the proctoring session according to the settings of the specified assessment. Once the proctoring session has started, the assessment page will open in IFRAME and you can proceed with the assessment. Once the assessment has been completed, the participant needs to end the proctoring session themselves by using the "Finish" button in the top right corner of the screen, or the end button that appears when clicking on the camera preview in the bottom left corner. If a participant simply closes the proctoring page without ending it, the proctoring session will end automatically after the timeout specified in the template settings. # 4\. Monitoring and reviewing the results Real-time monitoring and viewing of session logs can be done from both the administrator interface and the proctor interface. Administrators see all sessions with no restrictions. Proctors only see the sessions to which they have been assigned in the template via the "Members" field. You may search for attendees by login or full name (filled in by attendee when the "profile" add-on is enabled) and for sessions by assessment identifier (template). For more information on how to use the interface, see the [proctor's]() and [administrator's]() guides. # 5\. Setting up an assessment page to open inside IFRAME The assessment page is normally opened in the proctoring system's IFRAME and its address is taken from the URL field. In order for the page to open correctly in IFRAME on the LMS web server, it requires HTTPS support with a valid SSL certificate, as well as properly configured headers [Content-Security-Policy]() and [X-Frame-Options]() on the assessment pages (or don't transmit these headers at all). Also [changes made in Chrome 80+]() in the cookie policy [Set-Cookie](), which for cross-domain cookies requires adding the two options `SameSite=None; Secure`. Here is an example of response header options which allow opening a third-party page in IFRAME on the proctoring system page and using cookies in IFRAME: | **HTTP Response Headers** | | --- | | `Set-Cookie: =; SameSite=None; Secure`
`Content-Security-Policy: frame-src https://*.proctoring.app` | # Integrations # Blackboard LMS Integration Guide # 1\. LMS configuration The integration of OctoProctor's proctoring system with Blackboard LMS is carried out using [IMS LTI]() technology. ## 1.1. SSL-certificate A valid SSL certificate is required to be installed on the Blackboard LMS web server for the LMS pages to open over HTTPS. You can check the validity of the certificate on the server using [SSLChecker.com](). This is a requirement of browser security policy, which prevents access to the camera and microphone over an unsecured HTTP protocol. You can issue a free [Let's Encrypt]() SSL certificate. ## 1.2. Installing the proctoring script In order for Blackboard LMS proctoring to work properly, a page with the proctoring launch code must be placed on the LMS domain. This is necessary to get around the cross-domain policy that prevents Blackboard LMS pages from opening in IFRAME from another domain. You can use the standard Blackboard LMS tool to upload content to post a code page. The following steps are required: ![Blackboard sidebar with the Admin entry highlighted]() 1. Login as a Blackboard LMS administrator to "Administrator Panel" (Admin) → "Content Management" → "Manage Content". 2. Select the "Institution" collection to upload the files. 3. Create a "proctoring.html" file on the computer with the following content in Unicode encoding (UTF-8): ``` Proctoring

There is nothing here. This is a service page for proctoring.

``` > **NOTE:** "demo.proctoring.app" given as an example, it needs to be replaced with the domain of your proctoring server. 4. Load the file "proctoring.html" into the Blackboard LMS: ![Institution Content page with Upload Files highlighted and proctoring.html listed]() 5. Save the link to the file, right-click on the file and select "Copy link address" from the menu. The link must be of the form: `https://your-lms-domain/bbcswebdav/institution/proctoring.html` 6. All LMS test-takers should have access rights to the file. ## 1.3. Enabling the LTI tool Transferring data from the Blackboard LMS to the proctoring system and transferring the trust score from the proctoring system to the LMS is done according to the LTI standard. It needs to be included in the LMS as follows: 1. Go as the Blackboard LMS administrator to "Administrator Tools" (Admin) → "Tools and Utilities" → "Tools". 2. Turn LTI (Course Tool) on, off and on again. The result should be: ON (New and existing courses). ![Blackboard Tools list with LTI Course Tool ON for new and existing courses]() ## 1.4. Adding an LTI provider Next you need to configure a new LTI provider which will be linked to your proctoring server. To do this you will need to: 1. Login as a Blackboard LMS administrator to "Administrator Tools" (Admin) → "Integrations" → "LTI Tool Providers" 2. Go to the global settings by pressing the "Manage Global Properties" button: ![LTI Tool Providers page with the Manage Global Properties button highlighted]() 3. Switch on the following options in the "FEATURE AVAILABILITY" block: "FEATURE AVAILABILITY" block configuration: | **Parameter** | **Value** | | --- | --- | | Enabled in Courses | Yes | | Creation of Tool Provider Links | Allow only links to approved tool providers | | Allow configured tool providers to post grades | Yes | ![Global properties with the Feature Availability options configured]() 4. Navigate to the new LTI 1.1 provider registration dialogue using the button "Register LTI 1.1 Provider": ![LTI Tool Providers page with the Register LTI 1.1 Provider button highlighted]() 5. In the "PROVIDER DOMAIN STATUS" section, enter the domain of your proctoring server (Provider Domain): ![Provider Domain Status section with the proctoring server domain entered]() 6. In the "DEFAULT CONFIGURATION" section, fill in the fields "Tool Provider Key" and "Tool Provider Secret", these keys are issued by the proctoring system manager. ![Default Configuration section with the Tool Provider Key and Secret fields]() 7. In the "INSTITUTION POLICIES" section, fill in the fields: "INSTITUTION POLICIES" settings: | **Parameter** | **Value** | | --- | --- | | Send User Data | Send user data only over SSL | | User Fields to Send | Role in Course
Name
Email Address | ![Institution Policies section with user data sending options set]() ## 1.5. Adding a placeholder for a tool In order for course authors to have the opportunity to add a proctoring element to the course, a new placement must be added for the previously created LTI provider. To do so, follow the steps below: 1. Go to "Administrator Tools" (Admin) → "Integrations" → "LTI Tool Providers". 2. Bring up the drop-down menu next to the name of the previously created LTI provider and select "Manage Placements" from the menu: ![Provider drop-down menu with Manage Placements highlighted]() 3. On the page that opens, click on the "Create Placement" button: ![Placements page with the Create Placement button highlighted]() 4. The following parameters must be specified in the "Add Placement" interface: Placement configuration: | **Parameter** | **Value** | | --- | --- | | Label | Proctoring Link (or any other title) | | Handle | Any string | | Availability | Yes | | Type | Course content tool + Allows grading | | Launch in New Window | Enabled | ![Add Placement interface with label, handle, availability and type filled in]() Tool provider configuration: | **Parameter** | **Value** | | --- | --- | | Tool Provider URL | `https://demo.proctoring.app/api/auth/bb?redirect=https://your-lms-domain/bbcswebdav/institution/proctoring.html` | | Tool Provider Custom Parameters | template=`default`
members=`@`
url=`` | - **demo.proctoring.app** given as an example, it needs to be replaced with the domain of **your proctoring server**, and **your-lms-domain** needs to be replaced by the domain of your Blackboard LMS server (this is the link to the "proctoring.html" file you saved earlier). - the **template** parameter specifies the session template identifier in the proctoring system; - the **members** parameter specifies the method of proctors distribution; - the **url** parameter contains the link to the course containing the test you want to protect with proctoring. Follow to the course page and copy the URL from the address bar; > **NOTE:** before pasting the link to the Tool Provider Custom Parameters please encode it using any online service, for example [here](). ![Tool provider configuration with the provider URL and custom parameters]() You can create several placements with different user parameters if required. # 2\. Proctoring integration ## 2.1. Adding a proctoring link to the course **2.1.1. For Blackboard Original** For participants to be able to use the proctoring, a link to the proctoring element must be added to the course. This can be done as follows: 1. Navigate to the "Content" section of the course. 2. Select a previously created proctoring item from the "Build Content" → "Proctoring Link" list: ![Content menu, Build Content list with Proctoring Link highlighted]() 3. A link to the proctoring will appear in the course content list: ![The course content list showing the new proctoring link]() Each link gives the user one proctoring attempt. **Returning proctoring results:** The proctoring system transmits the result of a proctoring session as a grade from 0.001 to 1 (0.1 to 100 on a hundred-point scale). If the conclusion of the session is positive (set by the proctor, or automatically from the credibility score and the threshold of the session), the grade is 1, or the grade of the quiz when the session uses the quiz player (the `quiz` add-on); otherwise, if the conclusion is negative or there is none, it is the minimum, 0.001. The credibility score itself is not sent. You can enable evaluation of a proctoring item in Blackboard LMS in the following way: 1. Navigate to edit the proctoring item (drop-down menu next to the item name). 2. Enable the option "GRADING" → "Enable Evaluation". 3. Set the maximum points to 100 ![Grading section with Enable Evaluation checked and maximum points set]() **2.1.2. For Blackboard Ultra** Click "+" → Content Market → Choose Proctoring Link → Click "+" ![Blackboard Ultra course content with the add menu open and Content Market highlighted]() ![Content Market with the Proctoring Link institution tool highlighted]() **Returning proctoring results:** For this tool to deliver proctoring results back to Blackboard LMS, click the **three dots** next to the link that appeared in the course → Edit. Enable "Create gradebook entry for this item", and set the grade to maximum **100** Points. ![Proctoring Link settings with gradebook entry enabled and maximum points set to 100]() Save the settings ## 2.2. Restrict access to the assessment without proctoring **2.2.1. For Blackboard Original** Immediately after the beginning of the proctoring session for the proctoring element, the score is set at 0, and after completion, it is always greater than 0 (from 0.1 to 100 with a hundred-point scale). This can be used in the conditions of access restriction of the associated **course element** "Your course" → "Content" → "Test element properties" → "Adaptive release". ![Test item context menu with Adaptive Release highlighted]() Select the "Grade Center" column → Choose your proctoring link. Then choose "Score" → "Equal to" → 0.00, press "Submit". ![Adaptive Release grade rule: Proctoring Link column, score equal to 0.00]() Therefore, the participant will not be able to start the assessment without proctoring. You should also place the link to the assessment item so that the test-taker can open it directly from the portal home page, as the link to the course is blocked in IFRAME due to the way the Blackboard LMS works. **2.2.2. For Blackboard Ultra** Follow to your "Course" → "Content" → "Test element properties" → "Release conditions" ![Course content with the Release conditions option selected for the test item]() On the left side of the window set the content to be **hidden** until the conditions are met, otherwise test-takers will be able to see the content, but still won't be able to access it without the proctoring On the right side check the **Activity** flag. - **Item** → choose your proctoring tool. - **Requirement** → choose **Custom** range. - **Use grading schema** → choose **Points**. - Minimum points = **0**, Maximum points = **0.1** ![Release Conditions panel with an Activity rule requiring 0 to 0.1 points on Proctoring Link]() Save the settings ## 2.3. Use of proctoring The test-taker will now start executing the linked assessment item on the proctoring procedure when the proctoring item is navigated. When the proctor clicks the element, they'll be redirected to the proctoring interface as an "Instructor". There, they can access all sessions created by test-takers who clicked the same element. When the proctoring session is completed, a proctoring grade of 0.001 to 1 will be transmitted to the LMS. Each proctoring session can only be completed once by a test-taker. It is possible to reset the attempt by changing the session ID through the proctoring system administrator interface, or extend the time by specifying 'Closes at' parameter longer than the current time. # 3\. Configuring a self deployed proctoring host To connect the integration API with Blackboard LMS, you need to load the following config with integration parameters under the proctoring system manager: ``` { "id": "", "key": "", "params": { "webhooks": { "bb": { "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 } } } } ``` > **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. # Canvas LMS Integration Guide # 1\. How it works The integration of the proctoring system with the Canvas LMS is done using the [Learning Tools Interoperability (LTI)]() and the Supervisor SDK (JavaScript 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 access proctoring through the LMS. # 2\. Setting up a quiz element Go to your course and open your quiz in preview mode. Copy the quiz URL from your browser's address bar to use later as the `url` custom parameter from Section 4. To prevent the quiz from being opened without proctoring you should set up access restrictions to the quiz by code. To do this, you need to enable the "Access code required" option in the quiz element settings: ![Quiz Restrictions with the access code option enabled and a code entered]() When running an assessment under proctoring, which is limited by an access code, the code will be automatically inserted into the input field and the participant will be able to start the assessment. In addition, you can restrict access to the quiz without proctoring after the access code is entered correctly the first time. To do this, just add the word "proctoring" to the quiz title. Note that this only works if you upload the proctoring script using the Theme Editor (see Section 3.1). *"Only Once After Each Attempt" -* If **left unchecked**, the test-takers will be able to see the Quiz Responses page in a multiple-attempt quiz after each attempt # 3\. Upload the proctoring script For proctoring to work, you need to place the SDK code on the Canvas LMS page with the same domain as the quiz. This is required for opening the quiz in IFRAME within the proctoring session without cross-origin issues. ## 3.1. Using theme editor You can use the Theme Editor in Canvas LMS to inject the proctoring code into all pages in the LMS. This method is described in [this guide](). To do this, follow these steps: 1. Create a `proctoring.js` file on your computer with the following content: ``` (function (host) { // the proctoring server adds "?proctoring=1" to the address of the page where it sends the test-taker var proctoring = new URLSearchParams(location.search).get('proctoring') === '1'; var isQuiz = /^\/courses\/\d+\/quizzes\/\d+/.test(location.pathname); if (window.self === window.parent) { // top-level if (window.ENV && window.ENV.current_user_id && isQuiz) { var title = document.getElementById('quiz_title'); if (title && /proctoring/i.test(title.textContent)) { var block = document.getElementById('quiz-instructions'); if (block) block.innerHTML = '

This quiz requires proctoring. Please use the proctoring link from the course module to start the quiz.

'; } } if (proctoring) { var script = document.createElement('script'); script.setAttribute('src', 'https://' + host + '/sdk/supervisor.js'); script.dataset.supervisor = 'sync'; document.head.appendChild(script); window.addEventListener('message', function (event) { if (event.origin !== location.origin) return; if (event.data && event.data.type === 'supervisor' && event.data.command === 'stop' && window.supervisor) { window.supervisor.stop(); } }); } } else { // iframe if (proctoring) { window.top.location.href = location.href; return; } if (isQuiz && !/\/take/.test(location.pathname)) { window.parent.postMessage({ type: 'supervisor', command: 'stop' }, '*'); } $(document).on('submit', function (e) { var form = e.target; if (/post/i.test(form.method)) { var url = new URL(form.action); if (url.host === host) return; var xhr = new XMLHttpRequest(); xhr.open('POST', form.action); xhr.addEventListener('load', function () { location.href = xhr.responseURL || url.searchParams.get('redirect') || location.href; }); xhr.send(new FormData(form)); e.preventDefault(); } }); } })('demo.proctoring.app'); ``` > **NOTE:** you need to replace "demo.proctoring.app" with the domain of your proctoring server in the script code. > > **NOTE:** the script starts the SDK only when the address has the `proctoring=1` query parameter, so it does nothing on the other Canvas pages. The proctoring server adds this parameter to the `redirect` address (see the `callbackURL` parameter in Section 7), and the SDK takes the session from the address and keeps it for the page reloads, so a reload resumes the session at any stage. The parameter disappears with the page when the session ends, because the SDK redirects the user away. If the user removes it from the address and reloads, the session is not resumed in that tab; the user has to open the proctoring link in Canvas again. > > **NOTE:** the script needs the new `callbackURL` of the provider from Section 7. Update the host configuration first and the script second. An old script keeps working in between only with the token in the `callbackURL`, as described in the next note. > > **NOTE:** a `proctoring.js` from an earlier version of this guide reads the token from the `?token=` query parameter instead. To keep such a script working until you replace it, add the token to the `callbackURL` expression of the provider (see "Support for an earlier `proctoring.js`" in Section 7). Replace the old script with the one above when you can. 2. Enable the ability to load custom JavaScript in "Admin" → "Settings" → "Features" → "Custom CSS/JavaScript overrides". ![Admin Features list with Custom CSS/JavaScript overrides enabled]() 3. Open the current theme in the theme editor "Admin" → "Themes" → "Open in Theme Editor" and upload the file `proctoring.js` (Upload → JavaScript file) ![Theme Editor Upload tab with proctoring.js selected as the JavaScript file]() 4. Save your changes by clicking the "Preview Your Changes", then the "Save theme" and "Apply theme" buttons 5. Use this URL in the Launch URL from Section 4 in the `redirect` parameter: ``` https://demo.proctoring.app/api/auth/canvas?redirect=https://your-canvas-server ``` > **NOTE:** you need to replace `demo.proctoring.app` with the domain of your proctoring server and `your-canvas-server` with your Canvas server domain. ## 3.2. Using file uploading If the previous method does not work, you can upload the proctoring script as an HTML file and use a link to the file in the LTI Tool URL with the redirect parameter. To do this, follow these steps: 1. Create a `proctoring.html` file on your computer with the following content: ``` Proctoring

There is nothing here. This is a service page for proctoring.

``` > **NOTE:** you need to replace `demo.proctoring.app` with the domain of your proctoring server in the script code 2. Go to the "Files" section of your course and upload the `proctoring.html` file. Then click on the uploaded file and copy the URL from your browser's address bar. ![Course Files list with the uploaded proctoring.html marked by an arrow]() Example of the URL: `https://your-canvas-server/courses/1/files?preview=2` 3. Replace the URL from the preview format to the standalone page format: - Source URL: `/courses//files?preview=` - Target URL: `/courses//files//preview` 4. Use this URL in the Launch URL from Section 4 in the `redirect` parameter: ``` https://demo.proctoring.app/api/auth/canvas?redirect=https://your-canvas-server/courses/1/files/2/preview ``` > **NOTE:** you need to replace `demo.proctoring.app` with the domain of your proctoring server and `your-canvas-server` with your Canvas server domain. Sometimes it does not work because the domain for uploading files is different from the quiz domain (e.g. the [Instructure.com]() cloud). In this case, you should try the next method. # 4\. Adding an application ## 4.1 Using LTI 1.1 First, you need to add a new application to your course settings (or entire Canvas instance settings). To do this, go to "Settings" → "Apps" → "Add App" and in the window that opens, fill in the fields according to the following sample: - **Configuration type:** Manual Entry - **Name:** Proctoring - **Consumer key:** `demo` *this key for your proctoring server is issued by the manager* - **Shared secret:** `secret` *this key for your proctoring server is issued by the manager* - **Launch URL:** `https://demo.proctoring.app/api/auth/canvas?redirect=` *the* `demo.proctoring.app` *is used as an example only, please specify the address of your proctoring server instead;* `` *is a page with the proctoring script code, or the Canvas home page if you used the Theme Editor. If the address contains `?`, `&`, `#` or `+`, URL-encode it before inserting it, otherwise the parameter is cut or changed.* - **Domain:** `demo.proctoring.app` *the* `demo.proctoring.app` *is used as an example only, please specify the address of your proctoring server instead* - **Privacy:** Public - **Custom fields:** | **Key** | **Value** | | --- | --- | | `template` | `default` | | `members` | `@` | | `url` | `` | | `code` | `` | Colored fields should be replaced with your values. You can specify additional parameters in the `KEY=VALUE` format in the custom fields, if necessary. These are the parameters that will be sent to the proctoring system when the test-taker starts the application. In the `url` parameter you should specify the URL to the quiz in Canvas LMS in the format `/courses//quizzes//take`. In the `code` parameter you should specify the access code to the quiz. ![Edit App dialog for the Proctoring tool with key, launch URL, domain and custom fields]() ## 4.2 Using LTI 1.3 First, you should create the LTI developer key. Follow Admin → \[your domain\] → + Developer Keys → + Developer Key → **LTI Key** Choose the value **Manual entry** from the **Method** drop-down list and fill in all the following fields: - **Key Name**: A name for your Developer Key, e.g. *Proctoring* - **Title**: A title for your Developer Key, e.g. Proctoring - **Description**: A description for the Developer Key, e.g. OctoProctor Proctoring Key - **Redirect URIs**: `https://demo.proctoring.app/api/auth/canvas_lti13?redirect=` - **Target Link URI**: `https://demo.proctoring.app/api/auth/canvas_lti13?redirect=` - **OpenID Connect Initiation Url**: `https://demo.proctoring.app/api/auth/canvas_lti13?redirect=` - **JWK Method**: Public JWK URL - **Public JWK URL**: `https://demo.proctoring.app/api/auth/canvas_lti13?redirect=` > **NOTE:** the `demo.proctoring.app` is used as an example only, please specify the address of your proctoring server instead; `` is a page with the proctoring script code, or the Canvas home page if you used the Theme Editor. If the address contains `?`, `&`, `#` or `+`, URL-encode it before inserting it, otherwise the parameter is cut or changed. From the **LTI Advantage services** drop-down list choose: - Can create and view assignment data in the gradebook associated with the tool. - Can view assignment data in the gradebook associated with the tool. - Can create and update submission results for assignments associated with the tool. - Can retrieve user data associated with the context the tool is installed in. In **Placements** menu choose: Account navigation, Link Selection and Assignment Selection. Then, fill in the corresponding drop-down menus below: - **Target Link URI:** `https://demo.proctoring.app/api/auth/canvas_lti13?redirect=` - **Text**: Proctoring To enable the **Deep Linking** feature, make sure to select the `LtiDeepLinkingRequest` radio button under the Link Selection drop-down menu. ![Key Settings dialog for an LTI developer key with Manual Entry method and placements]() In the drop-down menu **Additional settings** you can fill in the **Custom Fields** with the following `KEY=VALUE` pairs: - In the **url** parameter you should specify the URL to the quiz in Canvas LMS in the format `/courses//quizzes//take`. - In the **code** parameter you should specify the access code to the quiz. - **Template** parameter should contain a proctoring Assessment identifier. However, if you enabled the **Deep Linking** feature by selecting the `LtiDeepLinkingRequest` option, you **do not** need to fill in these Custom Fields manually. The Content Selector will automatically pass the correct template ID and other necessary parameters during the setup. | **Key** | **Value** | | --- | --- | | `template` | `default` | | `url` | `` | | `code` | `` | | `members` | `@` | For example: ``` template=default url=/courses/1/quizzes/1/take code=12345 ``` ![Additional Settings section with Custom Fields url, code and template]() Save the Key. Enable the created key (State) and copy its Client ID (Details). ![Developer Keys list with the Client ID and enabled State toggle marked by arrows]() # 5\. Adding an external tool ## 5.1. Using LTI 1.1 For grade delivery from OctoProctor to Canvas to work, the external tool must be added specifically to your course's **Assignments** section. Go to **Your course** → **Assignments** → **\+ Assignment** ![Course Assignments page with the + Assignment button marked by an arrow]() Then configure the following: - **Assignment Name** — The name of the tool as it will be displayed in Assignments. - **Points** — 100 - **Display Grade as** — Points - **Submission Type** — External Tool In the **"Enter or find an External Tool URL"** field, type the name of the application you added in Step 4 (the search is flexible). Select your tool from the list, and its address will appear in the URL field. ![Configure External Tool dialog with a tool selected and Load in a new tab checked]() Make sure to check the **"Load in a new tab"** checkbox, then click **"Select"**. Click **"Save and publish"** to publish quiz and the entire module ## 5.2. Using LTI 1.3 Open the course for which proctoring is needed. Choose the **Settings** tab in the lower left part of the menu, then choose the **Apps** tab in the top part of the menu. To Add the app click **\+App** button - **Configuration type**: By Client ID - **Client ID**: Paste the Client ID copied at the step 4.2 - Click Submit → Install ![Add App dialog with By Client ID configuration type and a Client ID entered]() Return to **Your course** → **Assignments** → **\+ Assignment** ![Course Assignments page with the + Assignment button marked by an arrow]() and configure the following: - **Assignment Name** — The name of the tool as it will be displayed in Assignments. - **Points** — 100 - **Display Grade as** — Points - **Submission Type** — External Tool In the **"Enter or find an External Tool URL"** field, type the name of the application you added in Step 4 (the search is flexible). Select your tool from the list, and its address will appear in the URL field. Make sure to check the **"Load in a new tab"** checkbox, then click **"Select"**. Click **"Save and publish"**. If you are using the LTI 1.3 integration with the **Deep Linking** feature enabled, a Content Selector window will open if you click the magnifying glass icon. ![Configure External Tool dialog with the Deep Linking magnifying glass icon marked]() The list of available proctoring templates and other parameters will be displayed, both in format and content entirely corresponding to the **Custom Fields** described in section 4.2. Select the necessary Assessment, then you will be redirected to the LMS with the module item automatically created. ![Select content window listing proctoring templates with exam URL and quiz password fields]() > **NOTE:** The selector will only display those assessments (templates) where the "Candidates" field is empty and the "provider" field matches your configured provider name or is empty. # 6\. Use of proctoring Now, when a test-taker navigates through the proctoring link, they will begin to take an associated quiz according to the proctoring workflow. Clicking on the proctoring link takes an administrator or teacher to the proctoring interface, where they can access all sessions and their reports created by that link. ![Course Modules page with the Proctoring link marked by an arrow]() # 7\. Setting up the proctoring host To connect the integration API with Canvas LMS, you need to load the following config with integration parameters under the proctoring system manager: ``` { "id": "", "key": "", "params": { "webhooks": { "canvas": { "strategy": "lti", "consumerKey": "demo", "consumerSecret": "secret", "callbackURL": "query.redirect && (u => (u.searchParams.set('proctoring', '1'), u.href))(new URL(query.redirect))", "profile": { "username": "payload.user_id", "role": "payload.roles.find(v => /Instructor|Admin/.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": "(query.url || payload.custom_url || payload.launch_presentation_return_url || '').replace(/([/]quizzes[/][0-9]+)[/]take.*$/, '$1')", "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": "query.template || payload.custom_template || 'default'", "subject": "payload.resource_link_title", "members": "payload.custom_members === '@' ? user.group : payload.custom_members", "url": "query.url || payload.custom_url", "tags": "payload.lis_person_contact_email_primary", "code": "payload.custom_code" }, "start": true, "stop": true, "pause": true, "submit": true }, "canvas_lti13": { "strategy": "lti13", "callbackURL": "query.redirect && (u => (u.searchParams.set('proctoring', '1'), u.href))(new URL(query.redirect))", "clientId": "", "issuer": "", "privateKey": "", "publicKeysetURL": "", "accessTokenURL": "", "authRequestURL": "", "profile": { "username": "payload.sub", "role": "payload.roles.find(v => /Instructor|Admin/.test(v)) ? 'proctor' : 'student'", "nickname": "payload.name", "labels": "payload.email", "lang": "(payload.launch_presentation?.locale || '').slice(0, 2)", "group": "['G', payload.context?.id, payload.resource_link?.id].join('-')", "referrer": "(payload.custom?.url || payload.launch_presentation?.return_url || '').replace(/([/]quizzes[/][0-9]+)[/]take.*$/, '$1')" }, "register": { "identifier": "[payload.sub, payload.context?.id, payload.resource_link?.id].join('-')", "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.email", "code": "payload.custom?.code" }, "start": true, "stop": true, "pause": true, "submit": true } } } } ``` > **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. Configuration parameters: ## Both strategies | Parameter | Value | | --- | --- | | `callbackURL` | The page where the test-taker is sent after the sign-in: the address from the `redirect` parameter of the launch URL with `proctoring=1` added to its query. The `proctoring.js` script from Section 3.1 starts the SDK on this page. | ## "lti" strategy only | Parameter | Value | | --- | --- | | `consumerKey` | LTI consumer key. | | `consumerSecret` | LTI shared secret. | ## "lti13" strategy only | Parameter | Value | | --- | --- | | `clientId` | LTI client ID (required for Deep Linking). | | `privateKey` | Private key in PKCS\#8 format. | | `publicKeysetURL` | URL to retrieve the platform's public keys. | | `accessTokenURL` | URL to retrieve the platform's access token. | | `authRequestURL` | URL to perform the authorization request to the platform. | The `clientId` parameter can be found at: Your Canvas domain → Apps → Manage → click the **App Name** field Here's how to create a private key for an LTI 1.3 configuration: 1. Using an online tool: - Navigate to [https://jwkset.com/generate]() - Select RSA with a key length of 2048 bits. - Download the generated private key in PKCS\#8 format (starting with `-----BEGIN PRIVATE KEY-----`). 2. Using OpenSSL (recommended for security): - Generate a private key: `openssl genrsa -out private.pem 2048` - Convert it to PKCS\#8 format: `openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.pem -out private.pk8` ## Support for an earlier `proctoring.js` A `proctoring.js` installed from an earlier version of this guide reads the session token from the `?token=` query parameter. The proctoring server no longer puts the token in the query, but the `callbackURL` expression can add it: it can read the session token from the `token` variable. For such a script, use this `callbackURL` in the `canvas` and `canvas_lti13` providers instead of the one from the configuration above: ``` "callbackURL": "query.redirect && (u => (u.searchParams.set('proctoring', '1'), u.searchParams.set('token', token), u.href))(new URL(query.redirect))" ``` With the new `proctoring.js` from Section 3.1, you do not need `u.searchParams.set('token', token)`, and you should remove it: the token in the query address is visible to the LMS server logs and is sent in the `Referer` header. # 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)]() 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 & 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 & Conditions]() 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]() # 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: ``` Proctoring

There is nothing here. This is a service page for proctoring.

``` > **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]() 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]() 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]() # 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]() 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=`
where `` 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`
\- members = `@`
\- url = ``
\- code = ``
where `` should be changed to the full URL of the quiz and `` 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]() In the dialog that opens, select the previously created LTI Link: ![Add Activity dialog listing the Proctoring LTI link]() 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]() # 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]() 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": "", "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. # iSpring Learn LMS Integration Guide # 1\. How it works The integration is supported on cloud and on-premise versions of iSpring Learn. On-premise software is installed and runs on a company's own hardware infrastructure and is hosted locally, whereas cloud software is stored and managed on the provider's servers and accessed through a web browser or other interface. OctoProctor is a solution for online monitoring, recording, and evaluating user behavior throughout online assessments. OctoProctor allows you to track user activity and verify their identity, so you can ensure accurate and valid assessment results. **Proctoring** is the procedure for monitoring the progress of a remote assessment. **A proctor** is an observer who monitors compliance with the rules. # 2\. How to Create a Proctor Role To create a proctor role: 1. Go to the "Users" section and click the "Add" icon. ![Users list with the Add icon highlighted]() 2. In the user profile, fill in the required fields and create a username and password. ![User card with the username, role and password fields and the save icon highlighted]() 3. Save the profile. Done! You've added a proctor. # 3\. How to Create a Proctoring Template A template in OctoProctor defines the settings that sessions will be based on. To create one: 1. Go to the *Assessments* section and click the "Add" icon. ![Assessments list with the Add icon highlighted]() 2. Enter the name of the template in the "Identifier" field. Later, you'll use this name when enabling the integration in iSpring Learn. 3. Go to the "Add-ons" tab and select what the user should check and provide before the assessment, such as a photo of their passport. ![Assessment card Add-ons tab with a list of selectable checks]() 4. In the "Members" section, add a proctor. In the search field, enter the proctor's login and click the add icon. When everything is filled in, click the save icon ![Session card Members tab with the add and save icons highlighted]() Perfect! You've created a proctoring template. # 4\. How to Enable and configure Integration with OctoProctor To enable and set up the integration: 1. Go to "User profile (top right)" → "Administrator Portal" → "Services (bottom left)" → "Connected Apps" and click "Learn more". ![iSpring Connected Apps page with the OctoProctor card switched on]() 2. Read the description of the integration and leave a request to enable it. 3. Fill in the required fields in iSpring Learn: - **URL:** You'll receive the URL when purchasing your OctoProctor account. - **JWT Secret Key:** You'll receive the JWT Secret Key when purchasing your OctoProctor account. - **X-API-Key:** You'll receive it when purchasing your OctoProctor account. ![Integration form with URL, JWT Secret Key and X-API-Key fields filled in]() 4. Once completed, click *Enable*. The integration is enabled. > **NOTE:** Proctoring does not work in the iSpring Learn mobile app. # 5\. How to Set Up Proctoring for a Quiz Proctoring works only for standalone quizzes. This can be an online quiz or a quiz created with QuizMaker. To set up proctoring for a quiz: 1. Open the quiz and go to the "Availability" section. 2. Scroll to the *Proctoring* section and check the *Enable OctoProctor monitoring* box. ![iSpring quiz Availability tab with the Enable OctoProctor monitoring box and template ID field marked]() 3. Specify the template "Identifier" from clause 3. 4. Save the settings Done! Now you can control the reliability of online assessments. If the quiz has linked copies, proctoring will work for them as well. # 6\. Configuring a self deployed proctoring host To connect the integration API with your LMS, you need to load the following configuration with integration parameters under the proctoring system manager: ``` { "id": "", "key": "", "params": { "webhooks": { "jwt": { "strategy": "jwt", "secretOrKey": "your-256-bit-secret", "callbackURL": "query.redirect", "profile": { "username": "payload.username", "role": "payload.role === 'proctor' ? 'proctor' : 'student'", "nickname": "payload.nickname", "lang": "payload.lang", "group": "payload.group", "referrer": "payload.referrer", "labels": "payload.labels" }, "register": { "identifier": "payload.identifier", "template": "payload.template", "subject": "payload.subject", "members": "payload.members", "tags": "payload.tags", "code": "payload.code", "timeout": "payload.timeout", "lifetime": "payload.lifetime", "metrics": "payload.metrics", "weights": "payload.weights", "addons": "payload.addons", "threshold": "payload.threshold", "locale": "payload.locale", "timezone": "payload.timezone", "rules": "payload.rules", "url": "payload.url" }, "submit": { "uri": "payload.api", "method": "POST", "headers": { "x-api-key": "your-256-bit-secret" }, "body": { "identifier": "room.identifier", "link": "`https://${room.host}/api/report/${room.identifier}`", "status": "room.status", "duration": "room.duration", "startedAt": "room.startedAt", "stoppedAt": "room.stoppedAt", "score": "room.score", "student": "room.student.username", "proctor": "room.proctor.username", "comment": "room.comment", "signedAt": "room.signedAt", "conclusion": "room.conclusion", "averages": "room.violations", "verified": "room.student.verified" } } } } } } ``` > **NOTE:** You should replace `secretOrKey` and `x-api-key` with a randomly generated sequence (Latin letters, mixed case, numbers; recommended length: 24 characters). `id` is the host's internal identifier (omit to create a new host). `key` is the host's license key. # LearnDash LMS Integration Guide # 1\. How it works The integration of the proctoring system with the LearnDash LMS is done using the Supervisor SDK (JavaScript proctoring library) along with a custom script that hides the quiz element until the proctoring session starts. You need to place the custom SDK code on the quiz page using a Custom HTML element in LearnDash LMS. # 2\. Add a custom HTML element to a quiz Navigate to a quiz section and either create a custom quiz or modify predefined. ![LearnDash admin menu with Quizzes underlined under LearnDash LMS]() As an example, we'll use the first quiz (Doing more with LearnDash Quiz): ![LearnDash Quizzes list with the Doing more with LearnDash Quiz first]() Access to the quiz can be configured via the settings menu, where associated courses can be populated, along with the quiz schedule, registration requirement, other quiz dependencies, etc. For example purposes we have removed any requirements as demonstrated on the screenshot below: ![Quiz Access Settings with course, prerequisites and registration requirements underlined]() On the quiz page ensure that you are in the edit mode: ![Quiz page toolbar with the Edit tool selected]() Add a block for a custom HTML element using a dropdown menu (right-click on the quiz page): ![Quiz page with numbered steps: Quiz page tab, Edit tool and block menu Add before]() Once a block has been added, click on the "+" icon and search for a Custom HTML element using the search bar: ![Block inserter with plus icon, search field and Custom HTML result numbered 1 to 3]() # 3\. Upload the proctoring script Now you need to add a custom JS script in the newly added custom HTML block which will prevent accessing a quiz until proctoring is successfully started and click the **"Save"** button. ``` ``` > **NOTE:** You need to replace "demo.proctoring.app" with the domain of your proctoring server in the script code. # 4\. Use of proctoring On your proctoring server, create an [assessment]() (the session template) with the following parameters: - Identifier – the session template identifier that your test-takers must enter. Allowed characters: A-Za-z0-9\_-. - Provider – the integration provider, it should specify "signup" or an empty string. Now, when a test-taker opens the page with the quiz, the proctoring session begins to initialize and the registration dialog opens. The test-taker fills in the fields: - Login – the user's unique identifier (**allows only "a-zA-Z0-9\_-" characters**). - Assessment identifier – the session template identifier from the assessment above. Then the test-taker passes the preliminary stages of the session. When the session starts, the quiz content is displayed within the proctoring interface according to the proctoring workflow. After a reload of the page, the session of the test-taker is resumed. > **NOTE:** The registration through this dialog creates test-takers only. Teachers and administrators open the sessions in the proctoring system itself, according to the [Proctor's Guide](). # LearnWorlds LMS Integration Guide # 1\. How it works The OctoProctor's proctoring system supports integration with LearnWorlds LMS. The proctoring system integrates directly with an assessment added to a course module section. The general principle of integration is to insert an "Embed Code" widget into the first question of the assessment, which allows you to place the proctoring code within it. As a result, a proctoring session starts from the question where this widget with code was added. A proctoring session termination is implemented in the "Ending screen" section. In the code you can enter the name of the template used for this assessment, this option allows you to use different templates for diverse assessments. In the course settings you must disable the ability to view the correct answers after passing the assessment. If necessary, you can add a "Retake" button if you want to give this opportunity to test-takers. In this case, you need to change the template settings by adding the number of attempts to retake the assessment. It is also necessary to limit the number of attempts to pass the assessment in the LMS itself. # 2\. Configuring course elements The interface and content of the assessment can be customized at your own discretion. > **NOTE:** The proctoring session starts from the first question in the assessment. Since the proctoring session starts after a question is uploaded, the question may remain visible to the test-taker for a short while. 1. In order to integrate the OctoProctor's proctoring system with the LearnWorlds LMS you need to add the "Blank exam" activity to the course module. ![Course module with the Add activity button highlighted]() ![Add learning activity dialog with the Exams category and Blank exam highlighted]() 2. Then you should go to the question editing panel. ![Exam activity row with the Edit questions button highlighted]() 3. In the opened menu you can add the necessary questions. ![Questions panel with the Add/Import question button highlighted]() 4. Then the "Embed Code" widget should be added into the first question in an assessment. ![First question with the plus button for adding a widget highlighted]() ![Add widget dialog with the Embed Code widget highlighted]() 5. After adding this widget, you will be able to insert code into the "Embeddable script" field. ![Embed widget settings with the empty Embeddable script field highlighted]() 6. Paste the following code. Note that it is needed to replace the links with ones that are relevant for your application: ``` ``` > **NOTE:** You need to replace "demo.proctoring.app" with the address of **your proctoring server** in the code and "default" with **your session template.** 7. Click the "Update" button, then the "Save" button: ![Embeddable script filled in, with the Update and Save buttons highlighted]() 8. You should go to the "Ending screen" section. It is needed to add the "Embed Code" widget and to insert the following code: ``` ``` 9. Click the "Update" button, then the "Save" button: ![Ending screen with an Embed Code widget and the Update and Save buttons highlighted]() # 3\. Configuring a self deployed proctoring host To connect the integration API with LearnWorlds LMS, you need to load the following configuration with integration parameters under the proctoring system manager: ``` { "id": "", "key": "", "params": { "webhooks": { "learnworlds": { "strategy": "plain", "callbackURL": "query.redirect", "profile": { "username": "payload.username", "nickname": "payload.nickname" }, "register": { "identifier": "payload.identifier", "template": "payload.template || 'default'", "subject": "payload.subject", "tags": "payload.tags" } } } } } ``` > **NOTE:** The field "id" is the ID of the host (if you do not specify it, a new host will be created); the field "key" is the license key of this host. # LTI-compliant LMS Integration Guide # 1\. Proctoring scenario The scenario of a test-taker's interaction with the proctoring system and the LTI-compliant LMS in the general case is as follows: 1. A test-taker logs in to the LMS and opens their course; 2. Goes to the LTI link or element configured with the proctoring system; 3. Next opens the page with the proctoring script (Supervisor SDK); 4. The process of surveillance begins; 5. The test-taker will see the quiz in IFRAME mode; 6. The proctoring script opens access to the quiz by password; 7. The test-taker passes the quiz; 8. After the quiz, the test-taker is redirected to the course page; 9. After a while, the proctoring system sends the results to the LMS. ![Flow diagram of the LTI scenario between the LMS, Supervisor SDK and proctoring system]() # 2\. How to integrate The integration of the proctoring system with your LMS is done using [Learning Tools Interoperability (LTI)]() and Supervisor SDK (JavaScript proctoring library) in three steps: 1. Upload the script code in your LMS that: 1. starts the proctoring session 2. injects the password to access the quiz 3. stops the proctoring session after the quiz is completed 2. Set up your quiz, such as: 1. protect the quiz by password 2. get the quiz URL 3. Configure LTI in your course to access proctoring, such as: 1. set up an LTI external tool; 2. add an LTI element to your course with custom parameters. # 3\. Upload the script code Save the code below in the "proctoring.html" file on your computer, and then upload it to your LMS or its web server with the same domain as quizzes: ``` Proctoring

There is nothing here. This is a service page for proctoring.

``` > **NOTE:** you need to replace `demo.proctoring.app` with the domain of your proctoring server in the code. After you do this, save the full URL to the page for future reference. # 4\. Set up the quiz Go to your quiz settings and set up a password to restrict access to this quiz. Your LMS must support this, otherwise your quiz can still be taken without the proctoring guard. You should also copy the full quiz URL. You may need to open this quiz as a test-taker to do this. Save the URL for future reference. # 5\. Configure LTI external tool You should set up the LTI external tool for the proctoring service in your LMS and insert the LTI link into your course. Use the following parameters to set up the LTI: - Tool URL: `https://demo.proctoring.app/api/auth/lti?redirect=` where `` 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. - Custom Parameters (key=value on separate lines): | **Key** | **Value** | | --- | --- | | `template` | `default` | | `members` | `@` | | `url` | `#/path/to/submit` | | `code` | `` | where `` should be replaced with the full quiz URL and `` with the quiz password from section 4; optionally, you can replace `/path/to/submit` with the end of the quiz completion URL or just remove it. # 6\. Set up the proctoring host To enable the LTI integration, you need to load the following configuration with integration parameters under the proctoring system manager if you use the on-premises version. ``` { "id": "", "key": "", "params": { "webhooks": { "lti": { "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 }, "lti13": { "strategy": "lti13", "callbackURL": "query.redirect", "clientId": "", "issuer": "", "privateKey": "", "publicKeysetURL": "", "accessTokenURL": "", "authRequestURL": "", "profile": { "username": "payload.sub", "role": "payload.roles.find(v => /Instructor/.test(v)) ? 'proctor' : 'student'", "nickname": "payload.name", "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.email" }, "register": { "identifier": "[payload.sub, payload.context?.id, payload.resource_link?.id].join('-')", "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", "code": "payload.custom?.code" }, "start": true, "stop": true, "pause": true, "submit": true } } } } ``` > **NOTE:** the `id` field is the ID of the host (if you do not specify it, a new host will be created); the `key` field is the license key of this host. Configuration parameters: ## "lti" strategy only | **Parameter** | **Value** | | --- | --- | | `consumerKey` | LTI consumer key. | | `consumerSecret` | LTI secret key. | ## "lti13" strategy only | **Parameter** | **Value** | | --- | --- | | `clientId` | LTI client ID (optional). | | `privateKey` | Private key in PKCS\#8 format. | | `publicKeysetURL` | URL to retrieve the platform's public keys. | | `accessTokenURL` | URL to retrieve the platform's access token. | | `authRequestURL` | URL to perform the authorization request to the platform. | Here's how to create a private key for an LTI 1.3 configuration: 1. Using an online tool: - Navigate to [https://jwkset.com/generate]() - Select RSA with a key length of 2048 bits. - Download the generated private key in PKCS\#8 format (starting with "`-----BEGIN PRIVATE KEY-----`"). 2. Using OpenSSL (recommended for security): - Generate a private key: `openssl genrsa -out private.pem 2048` - Convert it to PKCS\#8 format: `openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.pem -out private.pk8` # Moodle LMS Integration Guide # 1\. Integration scenario The OctoProctor system is integrated with [Moodle LMS]() versions 3.8.2 and higher using [IMS LTI]() standard. The integration requires setting up an external tool, adding the tool to a course, and setting up some custom parameters. Proctoring starts via the LTI link in the course, and a quiz loads in an iFrame during the session. Teachers and administrators can access proctoring online observation and reports via the LTI link as well. Each proctoring session returns results to Moodle via the LTI outcome service. The scenario of a test-taker's interaction with the proctoring system and Moodle in the common case is as follows: 1. A test-taker logs in to Moodle and opens their course; 2. Goes to the LTI element configured with the proctoring system; 3. Redirects to the proctoring system, where the proctoring session starts; 4. The test-taker passes the quiz that opens in iFrame (the proctoring grade manages access); 5. After the quiz ends, the test-taker is redirected back to the course page; 6. After a while, the proctoring system sends the outcomes to Moodle. ![LTI integration with Moodle]() # 2\. Setting up Moodle ## 2.1. Allow frame embedding Since the proctoring system uses an iFrame to display quizzes, you should allow it in your Moodle settings. In order to display the Moodle page in an iFrame, the option "Administration" → "Security" → "HTTP Security" → "Allow frame embedding" must be enabled by a user with the "Administrator" role: ![Moodle HTTP security options with Allow frame embedding enabled]() ## 2.2. Add auto-session closure HTML By default, the proctoring session is terminated by using the "Finish" button in the proctoring menu when the "finish" add-on is enabled. This termination is not associated with the completion of the quiz. However, you can set up a proctoring session that ends automatically when a quiz is completed in Moodle. To set up automatic session termination, add the following code to the "Administration" → "Appearance" → "Additional HTML" → "When BODY is opened (or closed)" field in the Moodle setting: ![Empty "When BODY is opened" field in the Moodle Additional HTML settings]() ``` ``` This code will automatically terminate the proctoring session once the attempt view page opens after the quiz is finished. This page must be enabled in the quiz element settings: "Review options" → "Immediately after the attempt" → "The attempt". ## 2.3. Set up the external tool A user with the "Administrator" role should add a new external tool. You will use this tool to add the proctoring procedure to the quizzes in your course. There are several ways you can do it, but you should choose only one. **2.3.1. Using LTI 1.0/1.1** You need to go to the "configure a tool manually" link in the "Site administration" → "Plugins" → "Activity modules" → "External tool" → "Manage tools" section. The following parameters need to be specified there: | **Parameter** | **Value** | | --- | --- | | Tool name | Proctoring | | Tool URL | `https://demo.proctoring.app/api/auth/moodle`
*the "demo.proctoring.app" domain is used as an example only, please specify the address of your proctoring host instead* | | LTI version | LTI 1.0/1.1 | | Consumer key | **demo**
*this key for your proctoring host is issued by the manager* | | Shared secret | **secret**
*this key for your proctoring host is issued by the manager* | | Tool configuration usage | Show in activity chooser and as a preconfigured tool | | Default launch container | Existing window | | LTI Assignment and Grade Services | Use this service for grade sync only | | Privacy → Share launcher's name with tool | Always | ![Moodle external tool configuration form filled in with the proctoring tool parameters]() **2.3.2. Using LTI 1.3** First, the manager must create the integration provider on your proctoring server (see Section 5) with the `lti13` strategy, the `issuer` parameter set to the address of your Moodle site (the platform ID) and the `clientId` parameter left empty: the dynamic registration works only for such a provider. Then you need to get the URL for the tool related to this provider. This link should look like: `https://demo.proctoring.app/api/auth/moodle_lti13`. In this example, "demo.proctoring.app" represents your proctoring server domain, and "moodle\_lti13" represents the provider name for this integration. Next, you should put this link in the "Site administration" → "Plugins" → "Activity modules" → "External tool" → "Manage tools" section: ![Manage tools page with the Tool URL field and Add LTI Advantage button]() Then, follow these steps: 1. Click **"Add LTI Advantage"**. If prompted, select **"Register as a new external tool"**. 2. Once the tool appears in the list under the name "Proctoring" with an "Activate" button, click **the pencil icon** to edit the tool settings. 3. Change the following parameters: - **Tool configuration usage:** Select "Show in activity chooser and as a preconfigured tool" - **Default launch container:** Select "Existing window" 4. Click **"Save changes"**. 5. Click the **"Activate"** button on the tool's card to complete the registration. After completing these steps, click the **magnifying glass** icon on the tool card to view the tool configuration details: ![Proctoring tool card and its configuration details: platform ID, client ID, keyset and token URLs]() The registration saves the client ID into the `clientId` parameter of the provider automatically. You should use the other parameters (the keyset, token and authentication URLs) to complete the integration provider on your proctoring host by the manager. If you need to register the tool again, the manager must clear the `clientId` parameter first. # 3\. Setting up course elements ## 3.1. Create a quiz element First, create a new quiz or move an existing one to a separate section of your course. This requires switching on edit mode in the course. ![Moodle course page with the quiz element in a separate section]() ## 3.2. Set up the quiz element In the settings of the quiz element find "Extra restrictions on attempts" → "Browser security". Set it to "None". Otherwise, Moodle will open the quiz in a new window, which is blocked by iFrame. ![Quiz settings with the Browser security option set to None]() You can set up the proctoring session to end automatically when the quiz is finished. To do so, enable this option in the quiz element settings: "Review options" → "Immediately after the attempt" → "The attempt". ![Quiz Review options with The attempt checked under Immediately after the attempt]() ## 3.3. Hide the quiz element To prevent participants from opening the quiz in any way other than via a proctoring session, hide the quiz element from the course page while still allowing access to it. To do so, hide the section containing the quiz: ![Quiz section menu with the Hide option highlighted]() Then, make the quiz available via a direct link that opens the quiz during the proctoring session: ![Quiz availability menu with Make available but don't show on course page selected]() > **NOTE:** If there is no 'Make available but don't show on course page' option, go to Site administration → Advanced features and enable 'Allow stealth activities (allowstealth)' To hide this section completely, select the following: "Course settings" → "Course format" → "Hidden sections" → "Hidden sections are completely invisible": ![Course settings with Hidden sections set to completely invisible]() ## 3.4. Get a link to the quiz element You should find the quiz element in the course, right-click on it and select "Copy link address". This link will be necessary when setting up the proctoring element. ![Browser context menu on the quiz element with Copy link address highlighted]() ## 3.5. Add a proctoring element **3.5.1 Using LTI 1.0/1.1** For each quiz element for which you want to enable proctoring, you need to add a new "Proctoring" element, which was created by the administrator beforehand. To do that, create a separate section and click the "Add an activity or resource" link: ![Course section with the Add an activity or resource link]() In the shown dialog, select the "Proctoring" tool from the list: ![Activity chooser dialog with the Proctoring external tool selected]() After selecting an external tool, you will be prompted to enter the name of the course element. This name will appear in both Moodle and the proctoring system. ![New External tool form with the activity name field]() Click the "Save and return to course" button to save your changes. **3.5.2 Using LTI 1.3** If your integration utilizes **LTI 1.3** standard, you can use the **Deep Linking** feature to configure the proctoring element. To do so, instead of saving immediately, use the "Select content" button. ![New External tool form with the Select content button highlighted]() A Content Selector window will open, displaying the list of available proctoring templates and other parameters. ![Select content dialog with an Exam URL field and a list of proctoring templates]() Specify quiz URL, select the necessary template, and you will be redirected to the course. The activity will be created automatically, and you **do not** need to manually fill in any custom parameters in section 3.6. > **NOTE:** The selector will only display assessments (templates) where the "Candidates" list is empty and the "Provider" field matches the provider name used in step 2.3.2 (by default it is **moodle\_lti13**). ## 3.6. Set up the proctoring element (LTI 1.0/1.1 only) Edit the proctoring element to change its settings. In the general session, click the "Show more..." link to display the "Custom parameters" field: ![Proctoring element settings with the Custom parameters field]() Configure the proctoring element by specifying the relevant parameters in the "Custom parameters" field in the format `KEY=VALUE`: 1. `url=https://your-moodle-domain/mod/quiz/view.php?id=ID` This URL is a link to the quiz element that the proctoring system will open in an iFrame as soon as the session begins. If not specified, the course page where the proctoring element is located will open in an iFrame. 2. `template=default` You need to specify an [assessment]() (template) identifier from the "Identifier" field when creating proctoring sessions. If you do not specify a template, the template with the "default" identifier will be used. The settings in the specified template will be used to create an individual session for each test-taker. The template must be created in advance in the proctoring system by a user with the "Administrator" role. 3. `members=@` This is a list of proctor usernames (or user groups), delimited by commas. If the "@" symbol is specified, clicking on the proctoring element link will give the proctor access to all sessions created and passed through by participants on the same link. You can manage the assignment of proctors to sessions through the "members" parameter in three ways: 1. `members=@` Moodle users with the "Teacher" role who are assigned to a course can log in to the proctoring system as proctors via the external tool in the course. These proctors can only observe or access session reports for participants who started a proctoring session through the same link. 2. `members=id1,id2,...` Only proctors with the listed usernames will have access to sessions started through this external tool in the course. The list of proctor usernames in the proctoring system is separated by commas. Proctors can be created either through the admin panel of the proctoring system or by selecting them as Moodle users with the "Teacher" role. In the latter case, the proctor's login will be their Moodle user ID. 3. the "members" parameter is not specified The rules for assigning proctors to sessions are configured in the session template via the proctoring system's admin panel. You can specify a list of proctor usernames on the Members tab or define rules for assigning proctors from a list on the Invitations tab. To display proctoring results in the Moodle gradebook, configure the grade settings for the proctoring element. Enable the "Allow \[…\] to add grades in the gradebook" flag. If necessary, specify "Point" as the type and "100" as the maximum grade: ![Grade settings with the Allow Proctoring to add grades in the gradebook flag highlighted]() PLEASE NOTE: 1. The keys are "url", "template" and "members" and the values are "https://your-moodle-domain/mod/quiz/view.php?id=ID", "default" and "@". All user parameters are optional; the proctoring session will run regardless of whether they are specified. 2. If the preconfigured tool does not work properly, it is recommended that you delete it and set it up again. 3. To test an external tool using a test-taker account, select the option in the top right corner: "Switch role to…" → "Student". Switch back to the admin account: "Return to my normal role". ## 3.7. Limit access to the quiz The grade for the proctoring element is set at 0 immediately after the beginning of the proctoring session, and after completion, it is always greater than 0 (from 0.1 to 100 on a hundred-point scale). This can be used for access restrictions on the associated quiz element. Open the quiz element settings and navigate to the "Restrict access" section. Add a new restriction by grade. Select the quiz and add the condition "must be \< 0.1 %". ![Restrict access to the quiz unless proctoring is used]() If you skip this step, the test-taker will be able to access the quiz through the direct link in their Moodle schedule without proctoring. ## 3.8. Outcomes and grades When a test-taker navigates to the proctoring element, they will begin taking the associated quiz according to the proctoring procedure. Clicking on a proctoring element takes the teacher or administrator to the proctor interface, where they can access all sessions created when the element was clicked. After the proctoring session ends, the outcomes for each test-taker will be shown in the Moodle gradebook (see the Grades section). When the session conclusion is positive (set by the proctor, or automatically from the credibility score and the threshold of the session), the proctoring system sends a score of 100, or the grade of the quiz when the session uses the quiz player (the `quiz` add-on). Otherwise, if the conclusion is negative or there is none, it sends the minimum score of 0.1. The credibility score itself is not sent to Moodle. ![Grader report with the demo quiz, proctoring quiz and course total grades]() ## 3.9. Additional attempts In order to allow test-takers to take the quiz multiple times until they pass, you need to: 1. In Moodle, you can select the number of attempts in the quiz settings (up to the required number). To do so, go to the quiz settings and specify the number of attempts in the "Settings" → "Grade" → "Attempts allowed" field. You may also select "Unlimited" to allow an unlimited number of attempts to pass the quiz. It is also important to select "Last attempt" as the grading method for a better match with proctoring results. As shown in the screenshot below, each test-taker has three attempts at the quiz: ![Quiz Grade settings with Attempts allowed set to 3 and Last attempt grading method]() 2. From the proctoring side, the administrator must assign a specific number of additional attempts. If this number is not defined, a test-taker will have one attempt to pass the quiz. As for the screenshot, a test-taker has three attempts (one main and two additional): ![Proctoring session card with the Attempts field set to 2]() This setting is required on both the Moodle and proctoring sides. If "Unlimited" is selected in Moodle, you must define the number of attempts in the proctoring settings. If a test-taker exceeds the allowed number of attempts during proctoring, you should update the test-taker's session created the first time rather than the template. This is because all changes made to a template are applied to newly created sessions, not current ones. There are three options that allow the test-taker to take the session one more time: 1. Add more attempts to the proctored session. 2. Change the proctored session identifier. 3. Delete the proctored session. # 4\. Troubleshooting ## 4.1. Invalid SSL certificate In order for the system pages to open using the HTTPS protocol, a valid SSL certificate must be installed on the Moodle web server. You can verify the certificate's validity on your server using the [SSLChecker.com]() service. This is a browser security policy requirement that prevents you from accessing the camera and microphone via an unprotected HTTP protocol. You can also issue a free [Let's Encrypt]() SSL certificate. ## 4.2. Unsupported Moodle version Since Chrome 80, the [SameSite]() browser security policy has tightened, so by default, cookies are not sent when the page is opened in an IFRAME. Therefore, Moodle must be updated to version 3.5.11+, 3.6.9+, 3.7.5+, or 3.8.2 or higher, as the [MDL-67175]() correction was only made in these versions. A preconfigured version of the latest Moodle release is available on [the Bitnami resource page](). If updating the Moodle version is not possible, you need to add a block of settings to the `.htaccess` file in the Moodle root directory on the server. These settings will change [the web server's response headers]() through the mod\_headers module for Apache: ``` Header edit Set-Cookie (.*) "$1; Secure; SameSite=none" ``` The "headers" module must be included in Apache. To do so, use the `a2enmod headers` command. ## 4.3. Incorrect web server settings A "Message signature not valid" or "Missing or invalid consumer key or access token" error may sometimes occur when submitting proctoring results to Moodle via the LTI outcome service. These errors are due to an incorrectly configured server. It is important to set the time on the Moodle server correctly. Otherwise, OAuth authorization in LTI will not work. This error may also be due to an inability to read the "Authorization" header in PHP. To resolve the issue, add the following rule to the Apache configuration file within the `` section associated with Moodle: *httpd.conf* ``` SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 ``` If this does not work, the [Moodle forum]() recommends adding the following Apache mod\_rewrite rule to the `.htaccess` file in the root Moodle directory of the server: ``` RewriteEngine On RewriteCond %{HTTP:Authorization} ^(.+) RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}] ``` The "rewrite" module must be enabled in Apache. You can use the `a2enmod rewrite` command to do so. The Moodle directory must also support parameter overrides from the `.htaccess` file: ``` AllowOverride All Options FollowSymLinks ``` ## 4.4. Problems with the cross-domain policy If you have trouble opening the quiz page in an iFrame during the proctoring session, place the WebSDK code on the Moodle domain and set up a redirect to the page after authorization via LTI. Once logged in, the user will be redirected to the Moodle page where the proctoring session will start using the WebSDK code. The proctoring-related quiz element will open in an iFrame. You need to add a special JavaScript script to the "Administration" → "Appearance" → "Additional HTML" → "When BODY is opened (or closed)" field in the Moodle setting: ``` ``` where "**demo.proctoring.app**" is the domain of your proctoring server. You also need to change the external tool setting by adding the "redirect" parameter to the tool URL so that it looks like this: ``` https://demo.proctoring.app/api/auth/moodle?redirect=https://your-moodle-domain/ ``` Instead of "**your-moodle-domain**", use the actual domain of your Moodle server. Make sure that this page does not trigger any additional redirects. In some versions of Moodle, the homepage automatically forwards to `https://your-moodle-domain/my/`. If so, use this exact URL as the "redirect" parameter. For LTI 1.3 integration, you should add the URL to all fields: Tool URL, Public keyset, Initiate login URL, and Redirection URI(s). Also, for LTI 1.3, use the "**moodle\_lti13**" provider name or the provider name configured on your proctoring host instead of the "**moodle**" provider name. # 5\. Configuring the proctoring host If you use the on-premises version of the OctoProctor system, you need to load the following configuration with integration parameters under the proctoring system manager to enable the LTI integration with Moodle. ``` { "id": "", "key": "", "params": { "webhooks": { "moodle": { "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 }, "moodle_lti13": { "strategy": "lti13", "callbackURL": "query.redirect", "clientId": "", "issuer": "", "privateKey": "", "publicKeysetURL": "", "accessTokenURL": "", "authRequestURL": "", "profile": { "username": "payload.sub", "role": "payload.roles.find(v => /Instructor/.test(v)) ? 'proctor' : 'student'", "nickname": "payload.name", "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.email" }, "register": { "identifier": "[payload.sub, payload.context?.id, payload.resource_link?.id].join('-')", "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", "code": "payload.custom?.code" }, "start": true, "stop": true, "pause": true, "submit": true } } } } ``` > **NOTE:** the "**id**" field is the ID of the host (if you do not specify it, a new host will be created); the "**key**" field is the license key of this host. Configuration parameters: ## "lti" strategy only | **Parameter** | **Value** | | --- | --- | | `consumerKey` | LTI consumer key. | | `consumerSecret` | LTI shared secret. | ## "lti13" strategy only | **Parameter** | **Value** | | --- | --- | | `issuer` | The address of the Moodle site (the platform ID). Required for the dynamic registration; if set, a launch from another issuer is refused. | | `clientId` | LTI client ID. Leave it empty before the dynamic registration, which fills it in; enter it by hand for a manual registration. Optional: if set, it is checked against the launch. | | `privateKey` | Private key in PKCS\#8 format. | | `publicKeysetURL` | URL to retrieve the platform's public keys. | | `accessTokenURL` | URL to retrieve the platform's access token. | | `authRequestURL` | URL to perform the authorization request to the platform. | Here's how to create a private key for an LTI 1.3 configuration: 1. Using an online tool: - Navigate to https://jwkset.com/generate - Select RSA with a key length of 2048 bits. - Download the generated private key in PKCS\#8 format (starting with "`-----BEGIN PRIVATE KEY-----`"). 2. Using OpenSSL (recommended for security): - Generate a private key: `openssl genrsa -out private.pem 2048` - Convert it to PKCS\#8 format: `openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.pem -out private.pk8` # Open edX LMS Integration Guide # 1\. Configuring Open edX The integration of OctoProctor's proctoring system with Open edX is carried out using [IMS LTI]() technology. ## 1.1. SSL certificate *A valid SSL certificate must be installed on the web server* for Open edX pages to open over HTTPS. This is a requirement of the browser security policy, which does not allow access to the camera and microphone over an unsecured HTTP protocol. A free [Let's Encrypt]() SSL certificate can be issued. You can check the validity of the certificate on the server using [SSLChecker.com](). ## 1.2. Opening pages in IFRAME The assessment page opens in the proctoring system's IFRAME after a proctoring session is started. In order for the page to open correctly in IFRAME on the Open edX web server, the [Content-Security-Policy]() and [X-Frame-Options]() headers on the assessment pages must be properly configured (or not passed at all). [Chrome 80+ also made changes]() to the [Set-Cookie policy](), which for cross-domain cookies requires the addition of two parameters `SameSite=None` and `Secure`. In this tutorial, the browser's cross-domain security policy restriction is bypassed by placing the SDK code on the Open edX course page. It is therefore not necessary to change the web server settings. # 2\. Setting up course elements ## 2.1. LTI tools configuration Before using the LTI proctoring tool in a course, the LTI tools must be enabled in Open edX Studio. A full description of LTI settings can be found in the [edX documentation](). To enable LTI tools in Studio, you need to do the following: 1. In the main menu open "Settings" → "Advanced Settings". ![Studio Settings menu with Advanced Settings highlighted]() 2. In the field "Advanced Module List" add an element `lti_consumer`, if you have multiple elements please separate them using comma symbols. ![Advanced Module List field containing lti\_consumer]() 3. Save your settings using the button "Save Changes". ## 2.2. LTI keys configuration Proctoring requires the transmission of authentication data (client key and secret key). These data are issued for each proctoring server where LTI integration is used and must be specified in the Studio settings. *The authentication parameters of the external LTI tool are specified as follows:* 1. From the main menu, go to "Settings" → "Advanced Settings". 2. In the field "LTI Passports" specify your LTI keys using the format `["your_lti_id:client_key:client_secret"]`, where: - `your_lti_id` — passport identifier (for example, `octoproctor_lti`, which is required to be specified when you add an LTI instrument to a course); - `client_key` — customer key (this is issued for a proctoring server separately); - `client_secret` — customer secret (this is issued for each proctoring server separately). 3. Example: `["octoproctor_lti:demo:secret"]` ![LTI Passports field with an example passport value]() 4. Save your settings using the button "Save Changes". ## 2.3. Placing the SDK on the course page The proctoring system opens course pages in IFRAME after launching a proctoring session. To get around the browser security policy restrictions (cross-domain policy) associated with opening Open edX pages in IFRAME within proctoring, the page that starts proctoring must be on the same domain as Open edX; the proctoring server itself stays on its own domain. To do this, you need to place the proctoring startup code (SDK) on one of the course pages. This can be done as follows: 1. From the main menu, go to "Content" → "Pages & Resources". ![Content menu in Studio with Pages & Resources selected]() 2. On the "Pages & Resources" view, press the "Custom pages" button to add a new page. ![Pages & Resources view with the Custom pages card highlighted]() 3. Open the page editor with the "EDIT" button. 4. Go to the editor settings with the "SETTINGS" button and specify the following values: ![Custom page settings with Display Name, Editor and Hide Page From Learners]() - Display Name – the name of the page to be displayed, you can name it "Proctoring". - Editor – the editor mode, select "Raw" to be able to insert HTML markup. - Hide Page From Learners – to hide the page from the course menu for learners, however the page will be accessible via a direct link, you must select "True". 5. Save the settings with the "Save" button. 6. In the page editor, insert the code to connect the proctoring SDK: ``` ``` > **NOTE:** You need to replace "demo.proctoring.app" with the domain of your proctoring server. 7. Save the changes to the page with the "Save" button. 8. Save the direct link to the page you have created, you will need it when setting up the LTI tool. To do this, switch to "View Live" mode (Staff role), open the "Proctoring" page and copy the link from the address bar of your browser. ![View Live mode as Staff with an arrow pointing to the Proctoring tab]() 9. Convert this link to URL Encoding, you can do this [online here](). The result should be a string like this: ``` Original link: https://your-edx-server/courses/course-v1:edX+DemoX+Demo_Course/f282cfc230d04a14b31ac42df22daa1b/ ``` ``` Encoded link: https%3A%2F%2Fyour-edx-server%2Fcourses%2Fcourse-v1%3AedX%2BDemoX%2BDemo_Course%2Ff282cfc230d04a14b31ac42df22daa1b%2F ``` ## 2.4. Setting up the proctoring element 1. Add a new element to the course that will use the LTI proctoring tool. ![Course outline with a Proctoring element subsection containing one unit]() 2. Select "Advanced" from the options in the new component selection menu. ![Add New Component panel with the Advanced option]() 3. Select "LTI Consumer" from the options provided. ![Advanced component list with LTI Consumer highlighted]() 4. Press "EDIT" on the settings panel of the LTI Consumer unit. ![LTI Consumer unit card with the EDIT button in the top right]() 5. Next, in the component editor, fill in the fields as described: ![Editing LTI Consumer dialog showing the LTI ID and LTI URL fields]() - LTI Version — LTI version, select "LTI 1.1/1.2". - LTI ID — previously specified identifier in "LTI Passports", e.g: `octoproctor_lti`. - LTI URL — LTI tool page using the format below, where `demo.proctoring.app` is your proctoring server domain name and `` is the encoded link to the SDK code page that was previously created: ``` https://demo.proctoring.app/api/auth/edx?redirect= ``` - Custom Parameters — the proctoring session parameters in "KEY=VALUE" format (separated by commas if there are several parameters): ``` ["url=https://your-edx-server/path/to/quiz","template=default"] ``` - `url` — the address of the assessment page (test), which can be found by going into View Live mode (Learner role) to the desired section of the course and copying the link from the browser address bar; (this parameter can be omitted if the URL is specified in the proctoring session template); - `template` — the proctoring session [template identifier](), which can be configured via the proctoring admin panel. - LTI Launch Target — the way LTI content is displayed, you need to select "New Window". - Scored — to receive an LTI rating for an instrument, you must select "True". 6. When you have finished making the settings, press "Save". 7. Publish the changes with the "Publish" button. ## 2.5. Restrict access to the assessment item It is usually necessary to limit the availability of the assessment item until the proctoring session is started. So that the participant cannot open the contents of the assessment item before the start of the proctoring session. ![Locked content message requiring the Proctoring prerequisite to be completed]() To do this, the following settings must be made in Studio (see [documentation]() for a full description of the settings): 1. Include Subsection Prerequisites: - Go to the main menu, "Settings" → "Advanced Settings". - Set the "Enable Subsection Prerequisites" field to `true`. - Save the settings with the "Save Changes" button. 2. Place the proctoring element (LTI tool) in the same section as the assessment item, placing it in front of it. 3. Go to the proctoring element settings (LTI tool). ![Proctoring element settings, Advanced tab, with the prerequisite option enabled]() 4. Enable the option "Make this subsection available as a prerequisite for other content" in the "Advanced" tab. 5. Save the settings with the "Save" button. 6. Go to the "Advanced" tab in the assessment item settings. ![Test settings, Advanced tab, with Proctoring element as prerequisite and 100% minimums]() 7. Specify the following parameters: - Select the name of the proctoring item from the "Prerequisite" drop-down list. - Specify in the "Minimum Score" field: `100%` - Specify in the "Minimum Completion" field: `100%` 8. Save the settings with the "Save" button. ## 2.6. Using proctoring On the page of the proctoring item (LTI tool), users will see a button which, when clicked, will open the proctoring system page in the adjacent tab. ![Proctoring unit page with the View resource in a new window button]() Users with the test-taker role will enter the proctoring session, where the assessment item page that was specified in the LTI tool settings in the `url` parameter (or specified in the session template through the proctoring admin) will open in IFRAME. Users with the role of instructor or administrator will enter the proctor's interface, where they can observe sessions of a given assessment and view protocols. # 3\. Configuring a self deployed proctoring host *To connect the integration API with Open edX, you need to load the following config* with integration parameters under the proctoring system manager: ``` { "id": "", "key": "", "params": { "webhooks": { "edx": { "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": { "score": "1" }, "stop": { "score": "0" }, "pause": { "score": "0" }, "submit": { "score": "room.conclusion?(room.conclusion==='positive'?0.999:0):Math.min((room.score||0)/100, 0.999)" } } } } } ``` > **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. # Sakai LMS Integration Guide # 1\. How it works The integration of the proctoring system with the Sakai LMS is done using the [Learning Tools Interoperability (LTI)]() and the Supervisor SDK (JavaScript 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 access 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. 1. Open the "Tests and Quizzes" page and the "Assessment List" tab. Go to the settings of your quiz and open the "Security and Proctoring" section: ![Sakai quiz settings with the Security and Proctoring section open and the password field highlighted]() 2. Enter a quiz password in the "Add a password to access the assessment" field and click the "Save" button. 3. Then return to the "Assessment List" tab and copy the URL from your browser's address bar: ![Sakai Assessment List tab with the browser address bar URL highlighted]() 4. Save the URL for future reference. # 3\. Upload the proctoring script Next step is to place the proctoring launch script on the course page. A test-taker is going to be redirected to this page after successful user authorization via LTI and may see a service message "There is nothing here. This is a service page for proctoring". The displayed message can be changed if necessary, by editing it in the code below. 1. Save the code below in the "proctoring.html" file on your computer: ``` Proctoring

There is nothing here. This is a service page for proctoring.

``` > **NOTE:** You need to replace "demo.proctoring.app" with the domain of your proctoring server in the script code. 2. Go to the "Resources" section and click on the "Upload Files" item in the action menu: ![Sakai Site Resources page with Upload Files highlighted in the Actions menu]() 3. Select the "proctoring.html" file from your computer and click on the "Continue" button: ![Sakai Upload Files page with the file drop area and Continue button]() 4. After returning to the previous page, right-click on the "proctoring.html" file name and select "Copy link address": ![Sakai Site Resources list with Copy link address in the context menu for proctoring.html]() 5. Save the URL for future reference. # 4\. Set up an external tool Go to the "Site Info" → "External Tools" section and click on the "Install LTI 1.x Tool" link. Fill in the following fields: - Tool Title: any name of the external tool; - Button Text: any name of the external tool run button; - Launch URL: a link to the proctoring tool, e.g. `https://demo.proctoring.app/api/auth/sakai?redirect=` where `` 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; - Launch Key: `sakai` use the **consumer key** for your proctoring server; - Launch Secret: `secret` use the **secret key** for your proctoring server; - Privacy Settings: check all items; - Services: check all items; - Indicate where in the Sakai User interface that these tools should appear: check all items; - The launch URL for this tool must support at least one launch message type: "The tool URL supports a single LTI tool (Resource Link launch)"; - Launch in Popup: Always launch in Popup; - Debug Launch: Never launch in debug mode; - Custom Parameters (key=value on separate lines): leave blank. After you complete this step, you will see the tool as shown below: ![Sakai installed external tools list with the new Proctoring tool highlighted]() # 5\. Add a link to the external tool In order to create a link to the external tool in your course you need to go to the "Site Info" → "External Tools" section and the "Tool Links" tab. Click on the "Create Tool Link" button. In the new window fill in the following fields: - Select Tool: your proctoring tool - Custom Parameters (key=value on separate lines): | **Key** | **Value** | | --- | --- | | `template` | `default` | | `members` | `@` | | `url` | `` | | `code` | `` | - Add Site Link: checked > **NOTE:** `` should be changed to the full URL of the quiz and `` to the quiz password from section 2. ![Sakai Update Tool Link form with Proctoring selected and custom parameters filled in]() # 6\. Use of proctoring Now, when a test-taker navigates through the proctoring link, they will begin to take an associated quiz according to the proctoring workflow. Clicking on the proctoring link takes an administrator or teacher to the proctoring interface, where they can access all sessions and their reports created by that link. ![Sakai course menu with the Proctoring link (1) and Open tool in a new window button (2) marked]() # 7\. Setting up a self deployed proctoring host To connect the integration API with Sakai, you need to load the following configuration with integration parameters under the proctoring system manager: ``` { "id": "", "key": "", "params": { "webhooks": { "sakai": { "strategy": "lti", "consumerKey": "sakai", "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 } } } } ``` > **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. # SCORM LMS Integration Guide This guide shows how to inject the OctoProctor proctoring SDK into a SCORM package and run it in your own LMS. To play SCORM packages as-is inside OctoProctor without changing them, see the [SCORM Player Guide](). # 1\. How it works You can integrate the OctoProctor proctoring system with any SCORM package and upload it to your LMS for use. There can be two variants: 1. You create an assessment with a third-party quiz maker, export it to the SCORM package, and inject the proctoring script into it. 2. You create an empty SCORM package and inject the proctoring script into it. This will open your assessment contents in an IFRAME on the proctoring side. However, your assessment content should support restricting access by password, otherwise a test-taker may open the assessment without proctoring. # 2\. Create a SCORM package First of all you should create a SCORM package with your assessment content or without it if the content will be opened in IFRAME by URL from a third party resource e.g. LMS. ## 2.1. Create and export quiz content using Lumi App [Lumi]() is a free application for creating a quiz and exporting it to SCORM version 1.2 package. 1. Download [Lumi Desktop Editor]() for Windows, macOS or Linux. 2. Create a new H5P project and select content type e.g. [Questionnaire](). ![Lumi App content type selection with Questionnaire chosen]() 3. Add question elements and set up question logic and scoring. ![Lumi App editor with a Simple Multi Choice question element]() 4. Export the quiz to a SCORM package (File → Export). ![Lumi export settings with SCORM package format and mastery score]() ## 2.2. Create and export quiz content using LearningApps.org [LearningApps.org]() is a non-commercial online platform with authoring tools for creating and playing quiz content. It has a huge library of ready-to-use apps. You can also create your own apps using our own content. You can export any SCORM 1.2 packaged app that is ready to load into LMS. ![LearningApps.org app page with the SCORM embed option highlighted]() ## 2.3. Create and export quiz content using iSpring QuizMaker [iSpring QuizMaker]() is a commercial application for creating a good looking quiz and exporting it to a SCORM package (versions 1.2 and 2004 are supported). 1. Download [iSpring QuizMaker]() for Windows (14-day trial) 2. Create a graded quiz, see [the tutorial]() on how to do this ![iSpring QuizMaker start screen with the Graded Quiz option]() 3. Add question elements and set up question logic and scoring. ![iSpring QuizMaker editor with a multiple choice question and scoring]() 4. Export the quiz to a SCORM package (Menu → Publish → LMS). ![iSpring QuizMaker Publish for LMS dialog with SCORM 1.2 profile]() ## 2.4. Create an empty SCORM package You can create an empty SCORM package for integration with proctoring if your content will be opened in IFRAME by URL (e.g. from LMS) on the proctoring side. > **NOTE:** The LMS SCORM player should use the same origin (domain) as the quiz. Otherwise, your assessment will not open in IFRAME because of [the cross-origin policy](). In addition, the assessment must support password access restrictions to prevent access to the assessment without proctoring. You can download SCORM manifest XML schema definition files: [1.2 version]() or [2004 4th edition](). For other SCORM versions, you can find files [here](). Unpack the ZIP archive, add the "index.html" file, and pack it back into the ZIP archive. Use the following code for the "index.html" file: ``` Proctoring

There is nothing here. This is a service page for proctoring.

``` # 3\. Inject the proctoring script into a SCORM package You should do the following steps: 1. Unpack the ZIP archive of the SCORM package. 2. Add the proctoring script to the "index.html" file at the end of the "body" section of it. There is the proctoring script code to insert: ``` ``` > **NOTE:** You need to replace "demo.proctoring.app" with the domain of your proctoring server in the code. > > **NOTE:** The proctoring script starts in the top window of the LMS page, so the SCORM package must have the same origin (domain) as the top window. Otherwise, the script cannot reach it, and the content of the package stays hidden. 3. Pack the ZIP archive again. This is the SCORM package that is integrated with your proctoring server. # 4\. Upload the SCORM package in your LMS Next, you need to upload the SCORM package to your LMS that supports the version of SCORM you specified. How this is done depends on your LMS, so you should follow the LMS guides for this. Before loading the SCORM package into your LMS, you can debug the SCORM package on [SCORM Cloud](). # 5\. Set up your proctoring server When a test-taker opens the SCORM unit in your LMS, the proctoring session begins to initialize. This will prompt your test-takers to fill in the fields: - Login – the user's unique identifier (**allows only "a-zA-Z0-9\_-" characters**). - Assessment identifier – the session template identifier. ![Registration for the assessment dialog with login and assessment identifier fields]() On your proctoring server you should create the [session template]() (Assessment) with the following parameters: - Identifier – the session template identifier that your test-takers must fill in. - Provider – the integration provider, it should specify "signup" or an empty string. - Content URL (optional) – the assessment URL in your LMS if you are using an empty SCORM package with the proctoring script for integration. - Access code (optional) – the password to access the assessment in IFRAME. # SCORM Player Guide This guide shows how to play custom SCORM packages as-is inside OctoProctor. To inject proctoring into a SCORM package and run it in your own LMS, see the [SCORM LMS Integration Guide](). This guide provides a step-by-step walkthrough for integrating and configuring your SCORM packages within the OctoProctor proctoring system. Say goodbye to complex integrations or LMS limitations. You can seamlessly display your SCORM content directly within the proctoring. Simply create your SCORM package (any supported version) using your preferred editor. Upload it to OctoProctor and lock it to ensure the test taker cannot open it without the proctoring session. Voilà! Upon completion, the OctoProctor dashboard will immediately display the test taker's grade and final passing status, in addition to all standard proctoring data. # 1\. Create Your SCORM Package While you may choose any authoring tool, all SCORM packages adhere to the same [industry standards](). For clarity, we will demonstrate the process using two industry-leading tools: [Articulate 360]() and [iSpring QuizMaker](). You can apply these configuration principles to any other SCORM authoring tool. # 2\. Configure and Export Quiz Content ## 2.1. Configuration using Articulate 360 Articulate 360 is a powerful and user-friendly tool for creating high-quality SCORM packages. 1. Log in to your Articulate account: https://www.articulate.com/ 2. Create a new course from a template or select an existing one under the Rise 360 tab. 3. When editing your quiz, set the required "Passing Score" by clicking the gear icon. If the test taker's score meets or exceeds the "Passing Score" the quiz is flagged as passed. This status is immediately transmitted to OctoProctor as the `passed` parameter, displayed as a green checkmark (or true/false in bulk exports). 4. Export the completed assessment to a supported SCORM version (1.2, 2004 2nd, 3rd, or 4th edition). To export: Navigate to your course in **Rise 360 -\> 'Private'**, click the three dots, and select **Publish -\> LMS**. ![Rise 360 course menu with Publish and LMS options highlighted]() In the publishing window, configure the following: **Export** | **Field** | **Configuration** | **Notes** | | --- | --- | --- | | LMS | Select SCORM 1.2 or SCORM 2004. | This choice does not impact the core functionality within OctoProctor. | | Edition | Select the required edition (for SCORM 2004). | This choice does not impact the core functionality within OctoProctor. | **Tracking** | **Option** | **Rationale** | **Recommendation** | | --- | --- | --- | | Track using course completion | Use this when tracking content consumption (e.g., safety training, where viewing all slides is mandatory) over a test score. | Used for non-graded content. | | Track using quiz result | Use this when the primary goal is to verify mastery of the material through a graded quiz. | Recommended for Assessments. The final result (Passed/Failed) is automatically determined by comparing the test taker's score against the pre-set 'Passing Score'. | **Reporting Options** | **Option** | **Recommendation** | | --- | --- | | Reporting **\- Passed/Failed** | **RECOMMENDED for Quizzes**. This sends the most accurate pass/fail status to OctoProctor. | | Reporting - Passed/Incomplete or Complete/Incomplete | Only these options are available for "Track using course completion."
**NOTE:** The test taker must manually end the proctoring session upon assessment completion. | **Exit Course Link - On:** This provides the test taker with a convenient button that simultaneously ends both the assessment and the proctoring session. **Only Load in LMS - OFF:** Since OctoProctor can lock SCORM packages so that they open only inside a proctoring session, this additional layer of protection is not required for successful deployment. ![Rise 360 LMS publish settings with SCORM edition, quiz tracking and Passed/Failed reporting]() 1. Click the 'Publish' button to receive the SCORM package ready for upload. ## 2.2. Configuration using iSpring QuizMaker iSpring QuizMaker is one of the most popular SCORM editors with flexible settings. 1. Open the iSpring QuizMaker application: https://www.ispringsolutions.com/ispring-quizmaker 2. Create a new assessment or open an existing one. 3. When editing, set the "Passing Score". This is done by clicking the 'properties' gear icon in the 'Home' panel and selecting 'Quiz Scoring'. If the test taker's score meets or exceeds the "Passing Score," the quiz is flagged as passed, and the `passed` parameter is sent to OctoProctor. ![iSpring QuizMaker Quiz Properties with Quiz Scoring and the Passing score field highlighted]() 4. Export the completed assessment to a supported SCORM version (1.2, 2004 2nd, 3rd, or 4th edition). To export: Click the '**Publish**' button in the top menu **'Home' -\> 'LMS'**. When selecting SCORM 1.2: The field 'Report status to LMS as' is available. We recommend selecting Passed/Failed. This ensures SCORM sends two clear signals: Completion (Complete) and Success (Passed/Failed). 5. Click the 'Publish' button and receive the SCORM package ready for upload. # 3\. Upload the SCORM Package to OctoProctor This step describes uploading of the created SCORM package (as a ZIP archive) directly to OctoProctor. This ensures the proctoring service can open the content from its domain within our system. ## 3.1. Log in to the proctoring system as an administrator Your OctoProctor manager will provide you with login information (server URL and admin credentials). Paste the URL into your browser and enter your admin credentials. ## 3.2. Upload and Secure the Content 1. Navigate to the 'Files' section. 2. Click the 'Upload files' button to select your SCORM package (in .zip format), or 'Upload folder' to select a folder containing multiple packages. ![OctoProctor Files section with the Upload files button highlighted]() 3. Secure your content: To further protect your content, lock the uploaded SCORM package. Select the file in the 'Files' interface and click the 'Lock selected items' button. > **NOTE:** No password is needed. A locked file can be opened only by an administrator and by a test-taker whose session has the link to this file in the 'Content URL' field of the assessment (see Section 4). Click the button again ('Unlock selected items') to remove the lock. ![Files section with the Lock selected items button]() 4. Select the file and copy the link to it by clicking the 'Copy the link to the selected file' button. > **NOTE:** This link is required when configuring the assessment. ![Files toolbar with the Copy the link to the selected file button highlighted]() # 4\. Create a New Assessment In the [**Assessments**]() tab, create a new assessment by clicking on the plus sign in the upper right corner. | **Field name** | **Description** | **Example** | | --- | --- | --- | | Identifier | The unique assessment ID students will enter upon login. Make it descriptive and easy to remember. (allowed characters: A-Za-z0-9\_-) | `MathExamJan2026` | | Subject | The full title of the assessment. This helps you filter sessions and provides a full description of the event. | Final Exam: Mathematics for Engineers, January 2026 | | Content URL | The link to the SCORM package copied from Section 3.2, step 4. | `https://demo.proctoring.app/api/files/OctoQuiz-SCORM2004.zip` | ![Assessment card with Identifier, Subject and Content URL fields highlighted]() > **NOTE:** The assessment with basic parameters satisfies most needs. However, if you require more flexible customization (e.g., Session management), please consult our public [Administrator's Guide]() > > **IMPORTANT:** In the Add-ons tab, please make sure to select the **Use quiz player (`quiz`)** add-on from the [Add-ons]() tab so the file can be correctly embedded. # 5\. Create a list of candidates The 'Candidates' tab in the assessment properties allows you to control who can participate in the event. - If the list is empty: Anyone can enter. - If at least 1 entry exists: Only the listed test takers can participate. If your event requires a finite list of test takers who do not yet have an account, follow these steps: 1. Create a list of unique usernames (e.g., phone numbers are recommended for uniqueness). Separate them with a comma and a space. Example: `personA`, `personB`, `personC`. > **NOTE:** Allowed characters: A-Z, a-z, 0-9, `_`, `-`. 2. Open the created 'Assessment' for editing (double-click on empty part of the line or use the pencil icon). 3. Paste the list of usernames into the 'Enter candidate name...' field and click the plus sign on the right. ![Candidates tab with a comma-separated list of usernames and the plus button highlighted]() 4. The usernames are added. Click "save". ![Candidates tab listing three added usernames with the save button highlighted]() # 6\. Share credentials with the test takers Test takers need to receive the following essential data: 1. **URL**: Link to your proctoring server (e.g., `https://demo.proctoring.app`) 2. **Assessment Identifier:** The unique assessment name created in Section 4. 3. **Username**: The unique name of the test taker created in Section 5. Example email: > Dear candidate, > > To take the proctored economics exam, please enter `https://demo.proctoring.app` into your browser's address bar. Select **'Sign Up'** and enter the following information: > > Your **login**: `personA` > > **Assessment identifier**: `economyFall2026stage1` ![Proctoring login form with the Sign Up button highlighted]() ![Registration for the assessment dialog with login and assessment identifier fields]() # 7\. Analysis of the results obtained When the test taker completes a session, the proctoring administrator can access all standard session metrics (video, logs, events) plus two dedicated SCORM parameters received from the course package itself. These SCORM-specific results are visible in the Sessions tab, in the *Passed* and *Grade* columns: 1. **☑** or **☒**: This is the `passed` parameter. It indicates whether the test taker met the required "Passing Score" (discussed in Section 2). If the quiz score meets or exceeds the "Passing Score," the result is **☑**; otherwise, it is **☒**. 2. **Grade** (0% to 100%): This is the score the test taker achieved based on the content in SCORM. (e.g., if there were two questions, each worth 50 points, and only one was answered correctly, this field displays 50%). Do not confuse the *Grade* with the *Credibility score* column: the credibility score is the result of the proctoring itself (violations of the rules during the session), and it does not depend on the answers. This data is also available in the Session card, the .csv export, and within the filter in the Sessions view for bulk analysis. (Please consult the public [Administrator's Guide]() for more details on export and filtering.) # WebSDK-based Integration Guide The Supervisor SDK is a JavaScript library that can be injected into the page of any Learning Management System (LMS) to implement seamless integration with the OctoProctor proctoring system. Full documentation for the WebSDK is available at [https://demo.proctoring.app/docs/](). LMS Requirements: - Proctoring pages in the LMS must be opened using the HTTPS protocol, with a valid SSL certificate installed on the web server. You can verify the validity of the certificate on your server using an [SSL checker service]() or issue a free [Let's Encrypt certificate](). - Assessment pages should not be completely reloaded when switching between questions. The WebSDK code should be launched at the beginning of the assessment and remain loaded until the end. The page can be reloaded by the user. > **NOTE:** The following integration parameters may change: > > - **Server address**: `demo.proctoring.app` is used as an example only. In production, always use the address of your proctoring server. > - **Authorization provider**: `jwt` is the default name, but it can be changed. > - **JWT secret key**: `your-256-bit-secret`, used to sign the JWT token. > - **Webhooks API key**: `your-256-bit-secret`, specified in the `X-Api-Key` header of the webhook to authenticate the request. # 1\. Proctoring scenario The scenario of interaction of the test-taker and the proctor with the proctoring system and LMS in the general case is as follows: 1. The test-taker logs in to the LMS, opens the assessment, and initiates the start of the proctoring session. 2. Before the session, the test-taker completes several steps: agrees to the rules of the assessment, checks equipment, takes a photo of their face and passport, connects a mobile camera, and others. 3. The test-taker starts the proctoring session and the assessment in parallel. 4. During the assessment, video recordings of the webcam (with sound) and the computer screen are captured, violations are automatically tracked, and the test-taker is continuously verified and identified. 5. During the session, the proctor can observe test-takers, and the system indicates in real time which test-takers need attention. 6. The proctor can interact with test-takers via chat or through video and audio communication and can prematurely end the proctoring session in case of gross violations. 7. After the assessment is completed, an assessment of the confidence level in the assessment results and a video protocol with detailed violations records are generated. 8. Results are sent to the LMS via a webhook. Technical implementation of the scenario: - **Server-Side (LMS)**: Implement an API to generate a JWT token and pass it to the front-end, where the proctoring session will be initialized using the Supervisor SDK's `start()` function with this token. - **Token Structure** (see sections 2.1 and 2.2): - **Header**: Specifies the HS256 algorithm and JWT type. - **Payload**: Contains user and session parameters in JSON format. - **Signature**: Formed based on the payload data and the secret key. - **Front-End (LMS)**: Implement a mechanism to receive a token for the current user and assessment via the API. Pass the received JWT token to the `token` field in the `start()` function of the WebSDK (see section 2.3) - **Proctoring System**: When the proctoring session is initialized, a user and proctoring session are created (or updated) with parameters from the JWT payload. The test-taker sees preliminary steps before starting the session, after which tracking and recording begin. - **Test Display**: Display assessment content to the test-taker only after successfully executing the `start()` function (see section 2.3). Otherwise, the test-taker could access the assessment without proctoring. - **Session Termination**: When the assessment is finished, call the `stop()` function to end the proctoring session (see section 2.3). Use the `stop` event to handle this. - **Results Delivery**: After processing on the proctoring server, results are sent to the LMS via a webhook, using the URL specified in the `api` field (in the JWT payload), as a POST request in `application/json` or `multipart/form-data` format. Below is a visualization of the scenario. ![Proctoring session lifecycle from initialization to report generation, with SDK calls, events and webhooks]() Before starting the session, each user completes preconfigured steps to meet proctoring requirements (each step can be enabled or disabled via add-ons). These include agreeing to assessment rules, accepting the agreement of the host if one is assigned (the session starts only after the test-taker accepts it and is allowed at their location), checking equipment, capturing facial and passport photos, connecting a mobile camera, and others. The following interfaces may be displayed to the user before starting a proctoring session. The SDK user interfaces appear at the top of the current page and require no special preparation: ![Rules of the assessment dialog with an instructional video and a Next button]() ![Equipment check dialog listing browser, webcam, microphone, screen, network and WebRTC checks]() ![Facial capture dialog with a webcam preview in an oval frame and a Take Photo button]() ![ID capture dialog with an ID card in the frame and Take a Picture and Upload buttons]() ![Connect mobile camera dialog with a QR code to scan with the smartphone]() The computer equipment check includes verifying the browser, webcam, microphone, network, and screen capture. If no issues are found, the check passes automatically; otherwise, the user receives a message with a description of the problem and resolution options. If all stages are successful, the proctoring session begins, observing the user. In this mode, the user can view video from their camera (preview), receive notifications of issues (violations are automatically detected), and access a chat to contact the proctor. A proctor can contact the user via chat, video, or audio and may end the session prematurely with a conclusion (positive or negative) and a comment, displaying a message to the user. The session page should be opened in a single instance; the system monitors this independently. If the session is opened in multiple tabs, browsers, or computers, previous pages are automatically locked, and proctoring stops in those pages without terminating the session. The session can only resume in the last opened tab. ![Assessment page with the webcam preview in a circle and the proctor chat panel open]() ![Content blocking screen with a lock icon and a Loading, please wait status]() ![Session is completed dialog saying the session was terminated by the proctor]() ![Session is blocked dialog telling the user the page was opened elsewhere]() Notifications of problems (irregularities) are automatically displayed to the user, giving them the opportunity to correct the situation if the problem was unintentional. If the user does not respond to messages within a minute, then access to the content is automatically blocked until the problem is resolved (this behavior is controlled by the `lock` add-on). ![Violation notification next to the webcam preview: focus changed to a different window]() Content copy protection mode prohibits copying text and images from the page using the clipboard and context menu, and also prohibits saving the page using the print dialog. When the assessment is complete, the proctoring session should be stopped and all interfaces are hidden. The proctoring results are transferred to the LMS by webhook from the proctoring server. # 2\. Implementing integration ## 2.1. JSON Web Token (RFC 7519) For secure transmission of parameters for a proctoring session with protection from changes on the part of the user, tokens are used according to the [JSON Web Token (RFC 7519)](). The integration consists in implementing the JWT generation mechanism on the side of your LMS and using the WebSDK functions to manage the proctoring session. [JSON Web Token (JWT)]() is a JSON object that is defined in the open standard RFC 7519. It is considered one of the safest ways to transfer information between two participants. To create it, you need to define a header with general information on the token, payload data, such as the user name, his role, etc. and signature. The diagram below shows the principle of user interaction with assessment and proctoring systems using JWT. ![JWT flow between the user, the LMS and the proctoring system in four numbered steps]() The general interaction scenario is as follows: 1. The user of the LMS is authorized in it using the authorization mechanisms provided by the system. 2. Before the start of each individual proctoring session, the LMS generates a JWT using a predefined secret key that should not be accessible to users. The key storage method is selected by the LMS itself. 3. The JWT is transmitted to the user on the front-end, and the user initiates a session in the proctoring system via the WebSDK using the token received from the LMS. The JWT payload stores the user identifier (the `username` field), the proctoring session identifier (the `identifier` field), and other session parameters. 4. The proctoring system server receives the JWT, checks its validity, and then starts the proctoring session for this user. ## 2.2. Token generation Token generation should be performed on the server, and only the token string should be transmitted to the client. To create a token: 1. Generate payload data in JSON format that describes the user and a specific session of this user in the following format: ``` { "username": "a34c1a1a-53ef-4728-8dc5-9c4779a8586e", "nickname": "John Doe", "identifier": "565b30b8-5cfb-42e2-a292-478d20630d1b", "template": "default", "subject": "Tutorial: proctoring", "tags": [ "male" ] } ``` 2. Generate a token on the LMS server based on the payload data using a library (see the information on the [jwt.io]() website). The encryption algorithm is HS256 and the token type is JWT. For the `demo.proctoring.app` server, the secret key used to generate tokens is `your-256-bit-secret`. Using the payload above should produce the following token: ``` eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImEzNGMxYTFhLTUzZWYtNDcyOC04ZGM1LTljNDc3OWE4NTg2ZSIsIm5pY2tuYW1lIjoiSm9obiBEb2UiLCJpZGVudGlmaWVyIjoiNTY1YjMwYjgtNWNmYi00MmUyLWEyOTItNDc4ZDIwNjMwZDFiIiwidGVtcGxhdGUiOiJkZWZhdWx0Iiwic3ViamVjdCI6IlR1dG9yaWFsOiBwcm9jdG9yaW5nIiwidGFncyI6WyJtYWxlIl19.1sHajdMz3n82hQEsfJTE3bii6mV3nOtTLkxTe6qwzuI ``` A description of the parameters that can be used in the JWT payload is given in table below. Please try to use the required minimum of parameters, usually these are: `exp`, `username`, `nickname`, `template`, `identifier`, `subject`, `tags`, `api`. It is advisable to use the rest of the parameters only if their change is foreseen by the LMS. If you need to specify different session parameters for different cases, it is better to use session templates. **Description of parameters** ### JWT Validation | **Parameter** | **Type** | **Description** | | --- | --- | --- | | `iat` | Number | UNIX time (in seconds) when the token was issued | | `exp` | Number | UNIX time (in seconds), after which the token becomes invalid | ### User Profile | **Parameter** | **Type** | **Description** | | --- | --- | --- | | `username`\* | String | unique user id, use of characters is allowed: A-Za-z0-9\_-, there should be only one ID for each user | | `role` | String | user's role ("student" or "proctor"), by default is "student" | | `nickname` | String | user's visible name | | `group` | String | user's group (for the "proctor" role only) | | `labels` | String\[\] | tags for search the user | | `lang` | String | UI language (e.g. "en"), by default is the browser language | | `referrer` | String | redirection page after logging out of the proctoring system | ### Proctoring Session | **Parameter** | **Type** | **Description** | | --- | --- | --- | | `identifier`\* | String | unique proctoring session identifier, use of characters is allowed: A-Za-z0-9\_-, each individual session must have its own ID | | `template` | String | template identifier for the proctoring session, use of characters is allowed: A-Za-z0-9\_- | | `subject` | String | title of the session | | `timeout` | Number | session timeout in minutes (integer): the session is stopped when it has had no update for that long (inactivity) | | `lifetime` | Number | session lifetime in minutes (integer): the longest the session may run, counted from its start, whatever the activity | | `members` | String\[\] | list of proctor's logins to add to the members in the session | | `metrics` | String\[\] | list of metrics in the session (e.g. `b2`, `c2`) | | `weights` | Number\[\] | list of weights for the metrics | | `addons` | String\[\] | list of add-ons in the session | | `threshold` | Number | threshold value of the credibility for automatic conclusion and notification of the participant | | `locale` | String | PDF report language (e.g. "en") | | `timezone` | String | PDF report time zone (e.g. "Europe/Berlin") | | `rules` | String | URL of a page with the rules of the event, shown as the first stage; with no page there is no such stage | | `url` | String | URL of an assessment page to be opened in IFRAME; with the `quiz` add-on, the URL of the quiz package (ZIP) for the quiz player | | `code` | String | access code to inject into an assessment page in IFRAME | | `api` | String | API address to send results for this session to another server via webhooks | | `tags` | String\[\] | tags for search the session | \* — required parameters ## 2.3. Integration code Below is a sample of the WebSDK integration code: ``` ``` First of all, you should add the `supervisor.js` script to the page where you want to use the proctoring service: ``` ``` In general, working with the WebSDK for a user in the "student" role means inserting a small piece of JavaScript code on each page where proctoring is required. After loading the script, you should create an instance of the `Supervisor` class: ``` var supervisor = new Supervisor({ url: 'https://demo.proctoring.app', }); ``` It is important that the `supervisor.js` script is loaded from the same proctoring server as specified in the `url` field. Otherwise, after the proctoring server has been updated, a WebSDK version and a server version may be different, which will cause problems in the functioning of the proctoring service. It is also recommended to use only one instance on a page. Next, you should call the `start()` function with parameters to initialize and start the proctoring session. It is necessary to pass the JWT string to the client to the browser and use it in the `start()` function in the `token` field: ``` supervisor.start({ // set your provider name provider: 'jwt', // get JWT string from your server token: fetch('/api/token').then(function (response) { if (response.ok) return response.text(); else throw Error('Failed to get JWT'); }) }); ``` The `provider` may have a different name, so you should make arrangements to change it. Note that the `start()` function with parameters is a shortcut for sequential calls to the `init()` and `start()` functions: ``` supervisor.init({ ...payload }).then(function () { // start the session return supervisor.start(); }); ``` If the `start()` function is called without parameters, the proctoring session starts in self-registration mode: ``` supervisor.start(); ``` In most cases, such as when the page is refreshed in the browser, the session can be resumed. In this case, use the same identifier and username in the JWT payload and call the `start()` function again. When the session is successfully started by the `start()` function, the `start` event is invoked, which can be subscribed to using the following script: ``` supervisor.on('start', function () { console.log('started'); }); ``` While the session is initializing and starting, a critical error may have occurred, interrupting the process. You should handle this error by subscribing to the `fail` event. For example, you can redirect the user to another page when the error occurs: The promise returned by `start()` is rejected with the same error, so add a `catch` handler to it if your code does not use the promise. ``` supervisor.on('fail', function () { // log out of the session with redirection to home page supervisor.logout({ redirect: '/' }); }); ``` When an assessment is completed, it is also necessary to call the `stop()` function to terminate the proctoring session. Otherwise, the last minute may not be saved and the session will not be automatically terminated until the time specified by the timeout has elapsed. ``` supervisor.stop(); ``` When the session is finished (the session can be finished by a participant, a proctor, or automatically by timeout or deadline), the `stop` event is invoked, which can be subscribed to as follows: ``` supervisor.on('stop', function () { // log out of the session with redirection to home page supervisor.logout({ redirect: '/' }); }); ``` If you do not subscribe to the `stop` event, the redirect to the referrer page will occur automatically after the session is stopped by the `stop()` function or the "Finish" button, by a proctor, when the lifetime has expired, or when the deadline has exceeded. By the way, you can subscribe to multiple events at once, just pass an array of event names to the `on()` function: ``` supervisor.on(['stop', 'fail'], function () { // log out of the session with redirection to referrer page supervisor.logout({ redirect: true }); }); ``` The `logout()` function is used to log out of the current session and redirect to the specified page if the `redirect` parameter is filled. You can specify a page URL or pass `true` to redirect to the referrer page, which is automatically determined or passed by the `referrer` field in the JWT payload. ## 2.4. Data-attributes for session initialization For simple WebSDK use cases, there is an automatic initialization and session startup, as well as a payload transfer using the data attributes of the script. Table below lists the supported data-attributes. Data-attributes for automatic session initialization | **Parameter** | **Description** | | --- | --- | | `data-supervisor` | If this parameter is set up it indicates that automatic WebSDK initialization is required. Two values are supported:
\- `sync` to start the proctoring session with the session token from the `#token=` fragment of the page address, or, after a page reload, with the stored token;
\- `init` to start the proctoring session with the token from the fragment, else, if the script has no other `data-*` attributes, with the stored token, else with a payload from the `data-*` attributes, or in self-registration mode if there are none.

The values `start` and `auto` are deprecated aliases of `sync`. | | `data-allowed-origins` | Origins of other windows (separated by spaces or commas) that may control the session by messages, in addition to the frame with the assessment. It is not a part of the payload. | | `data-*` | Other possible fields for a payload that can be used for the specified provider. | This initialization method can be used in conjunction with other integrations, such as LTI or JWT links. In this case, an additional parameter `redirect` is specified in the authorization link, which must contain the address of the page (`/api/auth/?redirect=https://your-lms/path/to/sdk`, a full URL that starts with `https://`; a relative path is not accepted) that hosts the code with automatic WebSDK initialization with one single data attribute `data-supervisor`. A code sample: ``` ``` The `"data-supervisor"` attribute with the value `"init"` can be used to start a proctoring session on the LMS side with self-registration or with a payload. A code sample: ``` ``` ### Script instance and commands from the assessment The script starts only in the top window of the page. The instance of `Supervisor` that it creates is also available as the global variable `window.supervisor`, so the scripts of the page can subscribe to its events or call its methods without creating a second instance, for example `supervisor.on('stop', function () { ... })`. The page with the assessment, opened in the frame, can control the session by messages to the top window. The `command` field is a method name or a list of them, where a method with parameters is a pair of the name and the parameters: ``` window.parent.postMessage({ type: 'supervisor', command: 'stop' }, '*'); window.parent.postMessage({ type: 'supervisor', command: [['stop', {}], 'logout'] }, '*'); ``` The commands `init`, `sync`, `start`, `stop`, `close` and `logout` are accepted. Messages from other windows are ignored, unless the origin of the sender is listed in the `data-allowed-origins` attribute. ### Session token and page reload After authorization via `/api/auth/?redirect=`, the proctoring server redirects the user to the page with the session token in the URL fragment: `https://your-lms/proctoring.html#token=`. The WebSDK handles this token automatically: 1. It reads the token from the fragment and immediately removes it from the page address, so the token does not remain in the browser history or in a copied link. 2. It saves the token in the browser's `localStorage`, on the origin of the page that hosts the script, and renews it while the session is running. 3. After a page reload, there is no token in the address anymore, so the WebSDK takes the saved one and resumes the session. 4. When the session ends, the saved token is deleted: by `stop()` if there is no `stop` event handler (see section 2.3), otherwise by `logout()`, which your handler should call. The two values differ in what happens when there is no token in the address and no saved token: | **Value** | **Token in the address** | **Saved token only** | **No token** | | --- | --- | --- | --- | | `sync` | Starts the session | Resumes the session | Does nothing | | `init` | Starts the session | Resumes the session, unless the script has other `data-*` attributes | Self-registration, or a payload from `data-*` attributes | Because `sync` does nothing without a token, it is safe to place on pages where a proctoring session may not be running, for example in a common page template of the LMS. The `init` value shows the self-registration dialog to every visitor without a token, so use it only on the dedicated proctoring pages. If the token is not accepted by the server (it is expired or the session is finished), the WebSDK deletes it and redirects the user to the home page (`/`) of the site: the referrer from the JWT is not known yet, because the session has not been loaded. > **NOTE:** The token is saved only if the browser allows access to `localStorage`. If the storage is blocked (for example, in a private window with site data disabled), the session cannot be resumed after a reload, and the user has to open the proctoring link again. ## 2.5. Logging Module (Diagnostics & Troubleshooting) The Logging Module is a specialized tool designed primarily for diagnostics and resolving technical issues. It records internal events occurring within the supervisor and outputs them directly to the browser console. By default, these logs are silent to ensure zero performance overhead during standard operations. They are intended to **only** be enabled when gathering data for the OctoProctor customer success team. ### 2.5.1. How to Enable Logging The setting is the `proctoring:debug` key of the browser's `localStorage`. Its value is a list of patterns separated by commas, in the form `proctoring:`. A `*` matches any characters, and a pattern with `-` in front excludes a namespace, for example `proctoring:*,-proctoring:session`. The key is read at each log call, so a page refresh is not needed. There are two ways to activate the module depending on your workflow: **Option 1: Via the Browser Console (Manual)** This method is ideal for quick on-the-spot testing. 1. Open the browser console and run: `localStorage.setItem('proctoring:debug', 'proctoring:*')` 2. Start the proctoring session; all modules will now be logged. The messages appear in the console as `[proctoring:]`. 3. **To stop logging:** Run `localStorage.removeItem('proctoring:debug')`. **Option 2: Via Page Code (Automatic)** If you need to capture logs from the very first second without user intervention, place this script **before** the supervisor script loads: ``` ``` > **NOTE:** The key stays in the browser's storage until it is removed, so remove the script from the page, and the key with `localStorage.removeItem('proctoring:debug')`, when the diagnostics are no longer needed. ### 2.5.2. Targeted Logging If you only need to monitor a specific module to reduce console "noise," you can enable modules individually: - `localStorage.setItem('proctoring:debug', 'proctoring:recorder')` — the video recording process; - `localStorage.setItem('proctoring:debug', 'proctoring:dispatcher')` — the task queue that sends the recorded data to the server; - `localStorage.setItem('proctoring:debug', 'proctoring:session')` — the calls to the proctoring server and the renewal of the session token. # 3\. Real-time observation and access to reports A user with the "proctor" role can log in to real-time sessions and view reports by logging in to the proctoring system with a JWT token, or with a username and password. In the observation interface, a proctor sees only those sessions of which he or she is a member. A proctor can log into the proctoring system using a username and password. To do this, proctor accounts must be created in advance through the admin panel, and their logins must be added to the appropriate sessions (the `members` field of the JWT payload, or the `invites` field of the session template). You can create specific links to go to a particular session report. A link opens the report in the proctoring interface, and only for a signed-in proctor or administrator: a report cannot be opened without authorization, so the user is asked to log in first. A link to a report is formed as follows: ``` https://demo.proctoring.app/api/report/ ``` Variables to replace: - `demo.proctoring.app` is your proctoring server domain, - `` is the session identifier. Add `?format=pdf` to the link to open the PDF report of the session, if it has been generated. You can authorize a specific proctor with automatic account creation in the proctoring system using a link with a JWT string. Here is an example of how to fill in the JWT payload fields to authorize a proctor: ``` { "username": "proctor1", "role": "proctor" } ``` Here is an example of a link with authorization by JWT string: ``` https://demo.proctoring.app/api/auth/jwt?token= ``` Variables to replace: - `demo.proctoring.app` is your proctoring server domain, - `jwt` is the name of the authorization provider, - `` is the generated token string. If you specify the `identifier` field, the specified report will be opened immediately after authorization. # 4\. Retrieve proctoring results via webhooks The proctoring system can use webhooks in JSON format to send the results of proctored sessions to the LMS. This is useful if you want to combine assessment results and proctoring results directly on your side. Results are sent within about a minute after the test-taker or proctor finishes the session or the session is automatically terminated by a timeout, and again when the proctor's conclusion is issued (or changed) after reviewing the report for some time after the session ends. The results are sent from the proctoring system server to the LMS server via an HTTP request by the POST method using the URL specified in the `api` field of each session. The content type (the `Content-Type` header) is `application/json`. Access to the API should be restricted by the key passed in the header of the HTTP request (by default, this is the `X-Api-Key` header). A request with one `identifier` can be executed several times with different data, therefore it is necessary to provide for its update in the LMS when data is received again from the proctoring system. If all goes well, the response code should be 2xx (usually 200), the content of the response body is not taken into account and is usually left blank. In the case of an error, the API should return a response code other than 2xx; a response that takes more than 60 seconds is also an error. A failed request is not repeated by default. To repeat it, set the `retryCount` parameter in the `submit` block of the provider (see section 5): the total number of attempts, the first one included, with a pause that grows by a minute after each error. Table below shows all the JSON fields in the response. Fields description | **Field** | **Type** | **Description** | | --- | --- | --- | | `identifier`\* | String | Session ID | | `link` | String | URL to the session report | | `status` | String | Session status:
`started` - In progress
`paused` - Started, but inactive
`skipped` - Not started before deadline
`stopped` - Completed, not rated
`accepted` - Positively rated
`rejected` - Negatively rated
`undecided` - Rated as uncertain | | `duration` | Number | Actual duration of the session (in minutes) | | `startedAt` | Date | Date and time of the actual start of the session | | `stoppedAt` | Date | Date and time of the actual end of the session | | `score` | Number | Automatic session scoring (0-100) | | `student` | String | Test-taker's username | | `proctor` | String | Proctor's username who rated the session | | `comment` | String | Proctor's comment on the session | | `signedAt` | Date | Date and time of proctor submission | | `conclusion` | String | Conclusion on the session: `positive`, `negative` or `uncertain` | | `violations` | Object | Metric violations per session, in `{ "metric": "value" }` format | | `verified` | Boolean | Identity check of the test-taker: `true` if the face matched, `false` if a check failed, `null` if none was made | \* — required fields, other fields may not be sent or may take a "null" value. Optionally, you can include additional files in the webhook request (in the host configuration by manager role): - photo of the participant's face (JPEG); - photo of the participant's document (JPEG); - PDF report file for the session. To attach them, add the `attach` field to the `submit` block of the provider (a file name in the request → the file of the session): ``` "attach": { "pdf": "room.pdf", "face": "room.student.face", "passport": "room.student.passport" } ``` In this case, the `Content-Type` header changes to `multipart/form-data`, containing a JSON file with results and additional binary files. ![Webhook.site request details with the JSON results payload sent by the proctoring server]() The [webhook.site]() service can be used to test the webhook results API. To do this, specify the URL listed on the service page in the `api` field of the session created via JWT. Then start and stop the session, and a few minutes after the session ends, a request will be made to the specified URL. You can see the request parameters in the interface of this service. # 5\. Setting up the proctoring host To connect the integration API with your LMS, you need to load the following configuration with integration parameters under the proctoring system manager: ``` { "id": "", "key": "", "params": { "webhooks": { "jwt": { "strategy": "jwt", "secretOrKey": "your-256-bit-secret", "callbackURL": "query.redirect", "profile": { "username": "payload.username", "role": "payload.role === 'proctor' ? 'proctor' : 'student'", "nickname": "payload.nickname", "lang": "payload.lang", "group": "payload.group", "referrer": "payload.referrer", "labels": "payload.labels" }, "register": { "identifier": "payload.identifier", "template": "payload.template", "subject": "payload.subject", "members": "payload.members", "tags": "payload.tags", "code": "payload.code", "timeout": "payload.timeout", "lifetime": "payload.lifetime", "metrics": "payload.metrics", "weights": "payload.weights", "addons": "payload.addons", "threshold": "payload.threshold", "locale": "payload.locale", "timezone": "payload.timezone", "rules": "payload.rules", "url": "payload.url" }, "submit": { "uri": "payload.api", "method": "POST", "headers": { "x-api-key": "your-256-bit-secret" }, "body": { "identifier": "room.identifier", "link": "`https://${room.host}/api/report/${room.identifier}`", "status": "room.status", "duration": "room.duration", "startedAt": "room.startedAt", "stoppedAt": "room.stoppedAt", "score": "room.score", "student": "room.student.username", "proctor": "room.proctor.username", "comment": "room.comment", "signedAt": "room.signedAt", "conclusion": "room.conclusion", "violations": "room.violations", "verified": "room.student.verified" } } } } } } ``` > **NOTE:** You should replace `secretOrKey` and `x-api-key` with a randomly generated sequence (Latin letters, mixed case, numbers; recommended length: 24 characters). `id` is the host's internal identifier (omit to create a new host). `key` is the host's license key. # 6\. Integration checklist To verify that the WebSDK integration is correct, use the following checklist: 1. The `supervisor.js` script must be downloaded by the client-side from the same server it connects to, to avoid version mismatches causing errors. Make sure to replace `demo.proctoring.app` with your proctoring host. 2. Proctoring starting with the `start()` function is usually performed just before assessment with proctoring. During the initialization process, the user will see interfaces with preliminary steps (assessment rules, equipment check, take photos, connect mobile camera, and others). The `start()` function may return an error, in which case the assessment cannot be started. 3. After successful proctoring starts, the assessment should appear to the user. Training or some preliminary actions should not be included in the proctoring session, only the assessment itself (with a time limit), otherwise it may negatively affect the proctoring scoring. 4. When the page is refreshed (F5 or closing and reopening), the assessment and proctoring session should be restored in the same way as the first run through the `start()` function, in which case the session identifier (the `identifier` field) and the user (the `username` field) should not change. 5. After the assessment is completed, the proctoring session should be terminated with the `stop()` function. 6. The `start()` and `stop()` functions can crash with a critical error. But you should handle this by subscribing to the `fail` event. You can use the `logout()` function within this handler to redirect to another page. 7. When a proctoring session ends, access to the assessment should be closed. A proctoring session can be terminated by a participant, a proctor, or automatically by timeout and deadline. The `stop` event subscription can be used to handle this. You can use the `logout()` function within this handler to redirect to another page. 8. You can use the [webhook.site]() service to test receiving results via webhooks.