# [LON-CAPA-cvs] cvs: doc /help course.manual.texxml /loncapafiles loncapafiles.lpml loncom/html/adm/help/png slots_change_confirm.png slots_change_resv.png slots_creation.png slots_instructor_assigned.png slots_manager.png slots_navmaps.png slots_params.png slots_proctor_validate.png slots_student_reserve.png slots_summary_cc.png slots_timeline.png slots_uniqueness.png loncom/html/adm/help/tex Slot_CommaDelimited.tex Slot_Use.tex

raeburn raeburn at source.lon-capa.org
Sun Jan 17 17:19:51 EST 2021

raeburn		Sun Jan 17 22:19:51 2021 EDT

slots_instructor_assigned.png
slots_params.png slots_summary_cc.png
slots_timeline.png slots_uniqueness.png
slots_proctor_validate.png
slots_navmaps.png
slots_student_reserve.png
slots_change_resv.png
slots_change_confirm.png

Modified files:
/doc/loncapafiles	loncapafiles.lpml
/doc/help	course.manual.texxml
Log:
- Document use of slots to support reservation by students (in advance) to
content at a particular time and/or place.
- Expand information about formatting in slot attributes CSV file.

-------------- next part --------------
@@ -1,8 +1,8 @@

-	 Another way of entering slot information is by uploading a comma separated (CSV) file. An easy way to create this type of file is to use a spreadsheet application such as Microsoft Excel, and save the file as a comma separated value (CSV) file.
+If you will be creating several slots you may prefer to create them by uploading a comma separated value (CSV) file containing slot configuration information with one line of data per slot. An easy way to create this type of file is to use a spreadsheet application such as Microsoft Excel, and save the file as a Text (CSV) file.  If you use a text editor directly to create the file, you should use double quotes around any values which themselves contain a comma (e.g., lit of proctor ids).

-	 To upload a file press the \textbf{Upload Slot List} button on top of the page. On the first page, select the file with the slot data to upload by pressing the \textbf{Browse button}. There is an option to ignore the first line. This is useful when the first line of your comma delimited file consists of headers for each field. You can also upload space and tab delimited file by changing the type combo box. Press \textbf{Upload} to upload the file.
+To upload a file press the \textbf{Upload Slot List} button on top of the page. On the first page, select the file with the slot data to upload by pressing the \textbf{Browse button}. There is an option to ignore the first line. This is useful when the first line of your comma delimited file consists of headers for each field. You can also upload space and tab delimited file by changing the type combo box. Press \textbf{Upload} to upload the file.

Once uploaded, you will be prompted to identify the contents of each column in your CSV data. The following fields are supported:
\begin{itemize}
@@ -25,9 +25,32 @@
\item Users slot is restricted to
\end{itemize}

-The following fields: Slot name'', Type of slot'', Start Time of slot'' and End Time of slot'' are required.
+\\The following fields: Slot name'', Type of slot'', Start Time of slot'' and End Time of slot'' are required.\\

-A Slot name may only contain letters, numbers and underscores.
-The Type of slot must be either preassigned or schedulable\_student.
-The four Time fields:  Start Time, End Time, Reservation Start Time, Reservation End Time permit a variety of formats.
-For example, the following formats are permitted: YYYYMMDDHHMMSS'' and MM/DD/YYYY HH:MM:SS''
+\begin{itemize}
+\item A Slot name may only contain letters, numbers and underscores.
+\item The Type of slot must be either preassigned or schedulable\_student.
+\item The four Time fields: Start Time, End Time, Reservation Start Time, Reservation End Time permit a variety of formats (for example: YYYYMMDDHHMMSS and MM/DD/YYYY HH:MM:SS)
+\end{itemize}
+End Time must be later than Start time. If no Reservation Start Time is specified, the slot can be reserved after the open date.  If no Reservation End Time is specified, the slot can be reserved up until the slot start time.\\
+
+\\Format requirements for the optional fields are as follows:
+\begin{itemize}
+\item Message when reservation changed'' can be: only_student, student_and_user_notes_screen or none.
+\item IP or DNS restriction'' is a comma-separated list.  If a particular IP restriction is: deny access from, prepend ! to the item.  Individual IP/DNS items can have one of the following formats:
+\begin{enumerate}
+\item a range, e.g, 35.8.3.[34-56]
+\item partial IP with wildcard, e.g., 35.8.*
+\item domain or subnet: e.g., *.msu.edu
+\item single IP: e.g., 127.0.0.1
+\item single DNS name, e.g., some.name.com
+\end{enumerate}
+\item Unique IP each student'' can be yes
+\item List of proctor ids'' is a comma separated list of username:domain for users who will proctor.
+\item Maximum number of reservations'' is a positive integer
+\item Resource(s)/Map(s) Restriction'' is a comma separated list of unique resource identifiers (aka symbs'). If the symb is for a map (i.e., .sequence or .page) then all resources in that map may use the slot.
+\item Date range of slot exclusion'' contains two dates separated by a comma.  The second date/time must post-date the first date/time. Permitted formats for each date/time are the same as for the four time fields.
+\item Sections slot is restricted to'' is a comma separated list of course sections
+\item Users slot is restricted to'' is a comma separated list of users (each user is in the format username:domain)
+\end{itemize}
Index: doc/loncapafiles/loncapafiles.lpml
diff -u doc/loncapafiles/loncapafiles.lpml:1.1009 doc/loncapafiles/loncapafiles.lpml:1.1010
--- doc/loncapafiles/loncapafiles.lpml:1.1009	Sun Jan  3 17:31:53 2021
+++ doc/loncapafiles/loncapafiles.lpml	Sun Jan 17 22:19:50 2021
@@ -2,7 +2,7 @@
"http://lpml.sourceforge.net/DTD/lpml.dtd">
<!-- loncapafiles.lpml -->

-<!-- $Id: loncapafiles.lpml,v 1.1009 2021/01/03 17:31:53 raeburn Exp$ -->
+<!-- $Id: loncapafiles.lpml,v 1.1010 2021/01/17 22:19:50 raeburn Exp$ -->

<!--

@@ -3204,6 +3204,18 @@
self_enroll.gif;
simple.gif;
simpprob.gif;
+slots_change_confirm.gif;
+slots_change_resv.gif;
+slots_creation.gif;
+slots_instructor_assigned.gif;
+slots_manager.gif;
+slots_navmaps.gif;
+slots_params.gif;
+slots_proctor_validate.gif;
+slots_student_reserve.gif;
+slots_summary.gif;
+slots_timeline.gif;
+slots_uniqueness.gif;
smallHelp.gif;
sprs.gif;
@@ -3398,6 +3410,18 @@
self_enroll.eps;
simple.eps;
simpprob.eps;
+slots_change_confirm.eps;
+slots_change_resv.eps;
+slots_creation.eps;
+slots_instructor_assigned.eps;
+slots_manager.eps;
+slots_navmaps.eps;
+slots_params.eps;
+slots_proctor_validate.eps;
+slots_student_reserve.eps;
+slots_summary.eps;
+slots_timeline.eps;
+slots_uniqueness.eps;
smallHelp.eps;
sprs.eps;
@@ -3940,6 +3964,7 @@
Slot_RestrictAvailibility.tex;
Slot_SelectingField.tex;
Slot_SpecifyProctors.tex;
+Slot_Use.tex;
Some_Items_Were_Not_Submitted.tex;
Index: doc/help/course.manual.texxml
diff -u doc/help/course.manual.texxml:1.50 doc/help/course.manual.texxml:1.51
--- doc/help/course.manual.texxml:1.50	Mon Jan 30 18:39:19 2017
+++ doc/help/course.manual.texxml	Sun Jan 17 22:19:51 2021
@@ -536,6 +536,15 @@
<file name="exam_basics.tex" />
</section>

+  <section name="Slots">
+    <subsection name="Using Slots">
+      <file name="Slot_Use.tex" />
+    </subsection>
+    </subsection>
+  </section>
+
<section name="Clickers">
<subsection name="Using Clickers">
<file name="Using_Clickers.tex" />

\label{Slot_Use}

and/or dates, one way to do that would be to use the Client IP/Name Access Control'' parameter
to control access by IP address, and the parameters: Problem Opening Date/Problem Due Date
(for problems), and Content Open Date/Content Close Date (for other types of content) to
control access by date.

LON-CAPA also provides a separate mechanism to restrict access to assessment item(s),
i.e., resource(s) with a file extension of .problem or .Task, or a gradable external tool,
which can be useful in the case where students will reserve access in advance to content
at a particular time and/or place.

One example would be a laboratory which has limited seating, and which is offered multiple
times over a given time period, but for which students should only be able to reserve access
for one particular opportunity.  To support that type of scenario, slots would be used.

Slots can also provide access control in which a proctor either directly, or remotely, must
enter a pre-determined proctor username and passphrase to check-in a student into a slot.
content protected by a slot is the actual owner of the username for whom access is
being granted.

One example would be an online exam in a testing center, in which a proctor would type in
the proctor username and passphrase into the proctor validation screen after verification of
the student's official photo ID.  Another example would be an online exam in which a remote
proctor would temporarily take control of the user's keyboard and enter the proctor username
and passphrase remotely into the user's web browser.

Lastly, slots can also be used as a reservation system, e.g., for office hours, where there
is no need for a student to actually submit anything to the assessment item for which access
is controlled by slots, but the time/date of the reservation itself made by a student to
gain access is of value.

\textbf{Course Coordinator View}

There are two parts to the process of using slots to control access to assessment items.
\begin{enumerate}

\item An instructor will create the slot using the Slot Management utility
\item An instructor will assign use of slots to particular resource(s) in the course using
the Parameter Manager to set the Use slot based access controls'' (useslots) parameter
to one of the three Yes'' options.

\end{enumerate}

The slot management utility can also be used to modify slot settings after a slot has been
created.  Slots can be created in two ways:

\begin{itemize}

\item Interactively, by using the multi-page slot helper'' web form which prompts for the
choices to be made when configuring a slot.

\item By creating a comma-separated-value (CSV) file containing slot attributes and uploading
the file using the Slot Management utility.

\end{itemize}

\begin{figure}
\begin{center}\includegraphics[width=0.70\paperwidth]{slots_creation}\end{center}
\caption{Slot Creation Buttons}
\end{figure}

In both cases an instructor will use the multi-page slot helper'' web form should modifications
be needed to the configuration of a slot after it has been created.

As Course Coordinator use Settings $>$ Slots to access the Slot Management Utility.

\begin{figure}
\begin{center}\includegraphics[width=0.70\paperwidth]{slots_manager}\end{center}
\caption{Slot Management Utility}
\end{figure}

Slots are of two types:
\begin{enumerate}

\item instructor-assigned
\item student-schedulable

\end{enumerate}

In the case of an instructor-assigned slot, after a slot has been created, and the
Use slot based access controls'' (useslots) parameter has been set to yes, the name
of the slot needs to be included in the value set for the Slots of availability'' (available)
parameter. That parameter can contain multiple : separated slot names, if multiple
instructor-assigned opportunities are to be provided to students to access a particular
resource or folder.

\begin{figure}
\begin{center}\includegraphics[width=0.70\paperwidth]{slots_instructor_assigned}\end{center}
\caption{Parameter setting for instructor-assigned slot}
\end{figure}

In the case of a student-schedulable slot, there is no need to set any parameter besides the
Use slot based access controls'' (useslots) parameter.

\begin{figure}
\begin{center}\includegraphics[width=0.70\paperwidth]{slots_params}\end{center}
\caption{Parameter setting for student-schedulable slot}
\end{figure}

Although a Course Coordinator can use parameter management tools to display the Slots of
availability selected by student'' (availablestudent) parameter, those tools only allow it
to be set for the scope of a specific user.  In any event, there is no need to use those tools
because the Slot Management Utility provides a mechanism to view a list of students who have
reserved a slot, and to remove some or all of the reservations, as needed.

For student-schedulable slots, each slot includes a History link below the Edit link in the
reservations changes for the slot, including who made the change, and in what context.

\begin{figure}
\begin{center}\includegraphics[width=0.70\paperwidth]{slots_summary_cc}\end{center}
\caption{Reservation listing for student-schedulable slots}
\end{figure}

The expectation for student-schedulable slots is that each student will use the Reservations'
item included in the inline menu in a course with one or more such slots, in order to add,
change or drop reservations for resources which are using them.

In the case of a student-schedulable slot, the slot will only be selectable by the student
for use for any resources which require a slot (i.e., for which the value in effect for
the useslots parameter is yes), if all of the following are true:

\begin{itemize}

\item The resource is open, i.e., between open date and due date (if set).
\item The slot start date is in the future.
\item Any conditions on slot use based on resource, and/or section, and/or specific users are
met.

\end{itemize}

Further constraints on whether a particular student-schedulable slot will be selectable by
a student are available by setting one or more of:

\begin{enumerate}

\item Period of time when this slot can only be uniquely chosen
\item Time students can start reserving
\item Time students can no longer reserve
\item Maximum number of students allowed in this slot

\end{enumerate}

\begin{figure}
\begin{center}\includegraphics[width=0.80\paperwidth]{slots_timeline}\end{center}
\caption{Reservability and Accessibility Timeline}
\end{figure}

Note: a slot may not be reserved by a student after the open date/time of the slot.

If there are multiple items in a course for which useslots'' is set to yes, a student may
make multiple reservations with a single slot, if resource-use restrictions on the slot
permit it.

If there are multiple student-schedulable slots available in a course, with start times in
the future, more than one slot may be reserved by a particular student for a particular
resource, if uniqueness and/or resource use restrictions permit it.

\begin{figure}
\begin{center}\includegraphics[width=0.80\paperwidth]{slots_uniqueness}\end{center}
\caption{Uniqueness constraints for multiple slots}
\end{figure}

Furthermore, both instructor-assigned slot(s) and student-schedulable slot(s) can be in
effect for a particular student for a particular resource.

On the student's side, information about items in course for which access is restricted
by slot is available from any of the following:

\begin{itemize}

\item The Manage Reservations'' utility accessed via the Reservations'' item in the inline menu.
\item Status information for each resource in the Course Contents listing.
\item Attempted display of the resource itself in the course.

\end{itemize}

In all three cases, if one or more slots have already been selected to apply to a
particular student when accessing that resource, and the end date/time has not yet
been reached, the description of the (selected) slot with the earliest (future) opening
date/time will be displayed alongside the resource name in the contents listing, or
below the message: Access requires reservation to work at specific time/place'',
when displaying the resource.

Prior to the start date/time both the Manage Reservations'' utility, reached via
Reservations'' in the inline menu and the URL for the resource itself, will provide buttons
to Change or Drop an existing reservation, or to Select another reservation.

When a student displays a resource for which a pre-assigned or selected slot is now open,
i.e., the start date/time of the slot is in the past, and the end date/time is in the
future, and any IP-based restrictions included for the slot are satisfied for the student's
current IP address, than either the resource will be displayed, or a Proctor validation
screen will be displayed in the case where check-in by a proctor has not yet occurred for
a slot which needs it.

If the useslots parameter for a resource is set to yes, and it has a slot scope which
applies to the enclosing map/folder, then there are two additional possibilites: either
check-in only applies to the resource itself, or check-in for a resource automatically
propagates the checked-in status to other resources in the same map/folder.

Once checked-in, the resource itself will be displayed, and the countdown icon above the
resource will countdown to the earliest of the following:

\begin{itemize}

\item the due date/time
\item the slot end date/time,
\item the time-limit, for a resource or folder in which the interval (time-limit) parameter
is in use (after the Show Resource'' button has been pushed to start the timer).

\end{itemize}

Once the slot end date/time is reached for the checked-in slot currently in effect for access
to the resource, if there are additional slot(s) which may be used to satisfy the useslots''
requirement for access, those slot(s) will then come into play.

If there is a student-schedulable slot, which is reservable (i.e., both the slot start time
and end reservation time are in the future, and if a cap on number of students, if set, has
not been reached), then a student can reserve the slot in order to resume access to the
resource after the slot start time (which could require new proctor validation).

Conversely, if the student already has a reservation for this second slot for this particular
resource, then assuming IP-based restrictions are met, the student will either be shown a
proctor validation screen if the slot uses a proctor, or if not, will be checked-in
automatically when displaying the resource.

\begin{figure}
\begin{center}\includegraphics[width=0.65\paperwidth]{slots_proctor_validate}\end{center}
\caption{Proctor validation screen}
\end{figure}

\textbf{Student View}

In the case where an open resource has slot-based access, the Course Contents listing will
include information about the current reservation status.

\begin{figure}
\begin{center}\includegraphics[width=0.60\paperwidth]{slots_navmaps}\end{center}
\caption{Contents Listing with Reservation Status}
\end{figure}

The expectation for student-schedulable slots is that each student will use the Reservations'
item included in the inline menu in a course with one or more such slots, in order to add
change or drop reservations for resources in a course which use them.

\begin{figure}
\begin{center}\includegraphics[width=0.70\paperwidth]{slots_student_reserve}\end{center}
\caption{Interface for Initial Reservation}
\end{figure}

If there is no uniquely-chosen' restriction in force, then Select button(s) will be available
for additional slots after making a reservation. If, however, slots can only be selected one at
a time then the other Select button(s) will become Change reservation' button(s) after a reservation
has been made.  If a student wants to display just a single resource for which student-schedulable slots
are available then if the resource itself is accessed before the slot start time the same Select'
button(s) will be shown for applicable slot(s).

\begin{figure}
\begin{center}\includegraphics[width=0.70\paperwidth]{slots_change_resv}\end{center}
\end{figure}

If the Change Reservation' button is pushed then a confirmation page will be displayed
which includes a Process the change' button to push to complete the switch of reservation
(with uniquely-chosen' restriction) from one slot to another.

\begin{figure}
\begin{center}\includegraphics[width=0.70\paperwidth]{slots_change_confirm}\end{center}
\caption{Reservation switch confirmation}
\end{figure}

Once the slot start time is reached, when a student accesses the particular assignment either
the resource will be displayed immediately (assuming any location-based conditions are met),
or if proctor validation is required, a web form will be displayed which requires entry of
the proctor's username and the secret word used for check-in, as set in the particular slot's
configuration.