Wed, 23 Jul 2008 02:41:59 -0000

This is a MIME encoded message

--raeburn1216780919
Content-Type: text/plain

raeburn		Tue Jul 22 22:41:59 2008 EDT

  Added files:                 
    /loncom/html/adm/help/tex	Domain_Configuration_Auto_Enrollment.tex 
                             	Domain_Configuration_Auto_Updates.tex 
                             	Domain_Configuration_Cataloging_Courses.tex 
                             	Domain_Configuration_Color_Schemes.tex 
                             	Domain_Configuration_Contact_Info.tex 
                             	Domain_Configuration_InstDirectory_Search.tex 
                             	Domain_Configuration_LangTZAuth.tex 
                             	Domain_Configuration_Quotas.tex 
                             	Domain_Configuration_Scantron_Format.tex 
                             	Domain_Configuration_User_Creation.tex 
                             	Domain_Configuration_User_Modification.tex 
                             	Domain_Configuration_Login_Page.tex 
  Log:
  - Help files for Domain configuration (new file names better for online manual).

--raeburn1216780919
Content-Type: text/plain
Content-Disposition: attachment; filename="raeburn-20080722224159.txt"

Index: loncom/html/adm/help/tex/Domain_Configuration_Auto_Enrollment.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_Auto_Enrollment.tex
\label{Domain_Configuration_Auto_Enrollment}
If your institution can provide access to roster information for courses
using LON-CAPA then your domain can offer automated enrollment once
localenroll.pm has been customized on each of the library servers
in your domain which serves as a home server for one or more courses.
The required customization is the creation of connections to rosters
for institutional course sections providing enrollment to each LON-CAPA
course. These connections can involve queries of database tables,
in real time, or can involve retrieval from a data source which is
only updated periodically.

There are two configuration options: 

\begin{itemize}
\item Set auto-enrollment as active or inactive in the domain. 
\item Set the username:domain used in the notification messages sent when
changes in enrollment occur as a result of auto-enrollment updates.
By setting these to a specific user (you might create one for this
purpose), you can view all auto-enrollment change messages for the
entire domain by viewing the contents of the sent messages folder for that user.
\end{itemize}
Auto-enrollment settings for each course consist of items set by a
Domain Coordinator within the \char`\"{}Modify Course\char`\"{} area,
and those items set in a course context from the \char`\"{}\underbar{Automated
Enrollment Manager}\char`\"{} link in the \char`\"{}Manage Users\char`\"{}
menu. This link is only displayed if auto-enrollment has been set
to be active in the domain.

The items which must be set by a Domain Coordinator include: 

\begin{itemize}
\item institutional code (used in mapping institutional rosters to LON-CAPA
courses)
\item default authentication
\item course owner
\end{itemize}
Your institution may have policies in place to control who may have
access to student information contained within course rosters. In
such cases, assignment of an appropriate course owner in LON-CAPA
may facilitate access to institutional rosters. When a course is first
created the initial Course Coordinator chosen will be identified as
the course owner. If, instead a course is created using an uploaded
XML course description file, the XML file will include tags to define
the username and domain of the course owner.

Settings which control auto-enrollment which are modifiable by a Course
Coordinator are described in the \underbar{Automated Enrollment help page}.

The auto-enrollment process will update user information (name, e-mail
address, studentID etc.) for any student who is being added to the
course, but will not change it in other case (i.e., drops, section
switches) should there be a difference between the values in the institutional
roster and the values in the LON-CAPA classlist. To change user information
for students already in the course, the Auto-update process must be run
(see below).

Warnings will be written to the Auto-enrollment log file found in
/home/httpd/perl/logs if a possible username change is detected. Although
the username is the unique identifier in LON-CAPA, the studentID operates
as an additional, mostly unique identifier. The same studentID may
not be assigned to more than one user - if an existing studentID is
assigned to adifferent user, the change will not occur, unless forced
(there's a checkbox for that). A blank studentID can be assigned,
and in this case multiple users can share the same studentID. StudentIDs
are used for LON-CAPA grading of scantron sheets, and are also used
to detect changes in username by the auto-enrollment and auto-update
processes.

At present LON-CAPA does not support username changes, although this
functionality will be supported in the future. In the meantime, what
you must do for users who switch username mid-semester (assuming institutional
authentication will no longer authenticate the user's old username)
is to convert the authentication type in LON-CAPA for the user to
\char`\"{}internal\char`\"{}, set an initial password, make sure that
permanent e-mail is set for the user, then e-mail the user the initial
password, and ask them to use the \char`\"{}\underbar{Forgot password?}\char`\"{}
link on the log-in page to change the password to something secure.

Index: loncom/html/adm/help/tex/Domain_Configuration_Auto_Updates.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_Auto_Updates.tex
\label{Domain_Configuration_Auto_Updates}
An auto-update, run as a regular process, can update user information
stored in LON-CAPA for all users in a domain, for whom institutional
directory information is available. Which user records are updated
can be controlled by institutional status (e.g., Faculty, Staff, Student
etc.). If a user is affiliated with more than group, then the attributes
which can be updated will be the cumulative set for the different
groups to which the user belongs.

If users are not affilliated with any institutional group, they can
be accommodated within the default \char`\"{}Other users\char`\"{}
group which is provided automatically. If no status types are defined
for your domain, this default group is entitled \char`\"{}All users\char`\"{}. 

Settings for auto-update are:

\begin{itemize}
\item Set auto-enrollment as active or inactive in the domain. 
\item Set whether user information changes should propagate to data stored
in classlist database files for the separate courses in which the
user has an active student role. 
\item Set which of the following attributes: first name, middle name, last
name, generation, e-mail address, student/employee ID should be updated
within LON-CAPA if a different version to the one currently stored
is retrieved from the institutional directory.
\end{itemize}
In order for Autoupdate to work, the \&allusers\_info() routine in
localenroll.pm needs to be customized and a conduit established to
institutional data. In addition, if you wish to differentiate between
institutional user types in your LON-CAPA domain the \&inst\_usertypes()
routine in localenroll.pm will need to be customized to correspond
with the types used at your institution. These types are then used
to populate the \char`\"{}User population\char`\"{} column in each
of the \char`\"{}Updateable user information\char`\"{} row(s) in the
Auto-update data table in \char`\"{}Domain Configuration\char`\"{}.

Warnings will be written to the Auto-update log file found in /home/httpd/perl/logs
if a possible username change is detected. Although the username is
the unique identifier in LON-CAPA, the student/employee ID operates
as an additional, mostly unique identifier. At present LON-CAPA does
not support username changes. For users who switch username (assuming
institutional authentication will no longer authenticate the user's
old username) is to convert the authentication type in LON-CAPA for
the user to \char`\"{}internal\char`\"{}, set an initial password,
make sure that permanent e-mail is set for the user, then e-mail the
user the initial password, and ask them to use the \char`\"{}\underbar{Forgot
password?}\char`\"{} link on the log-in page to change the password
to something secure. 

Index: loncom/html/adm/help/tex/Domain_Configuration_Cataloging_Courses.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_Cataloging_Courses.tex
\label{Domain_Configuration_Cataloging_Courses}
LON-CAPA courses can be both self-cataloging, and also manually cataloged.

Self-cataloging uses the institutional course code assigned to the
course when it is first created, or when the course is modified by
a Domain Coordinator via \char`\"{}Modify a course\char`\"{}. If a
course has no institutional code it will not appear in the category:
Official courses (with institutional codes).

A hierarchy of categories and sub-categories can be defined which
are independent of institutional course codes. These categories might
be used to catalog courses in the domain to which the \char`\"{}official
courses\char`\"{} designation does not apply, or they might be used
to provide alternative ways of cataloging official courses.

Besides definition of the hierarchy of categories and sub-categories,
the \char`\"{}cataloging of courses\char`\"{} screen provides two
options to be set for the domain by a Domain Coordinator, which control:

\begin{itemize}
\item Who may hide a course from the course catalog, if the course would
ordinarily appear by virtue of having an institutional course code,
or having been assigned to a custom category/sub-category.
\item Who may assign a custom category/subcategory to a course
\end{itemize}
In both cases, the choice is between a Domain Coordinator and a Course
Coordinator. For the former, hiding of courses and assignment of categories
will be via \char`\"{}Modify Course\char`\"{}, while for the latter
these operations will be via \char`\"{}Modify Parameters\char`\"{}
(\char`\"{}Set Course Environment\char`\"{} option in sub-menu).

Definition of custom categories is by the Domain Coordinator. The
\char`\"{}Cataloging of courses\char`\"{} interface allows custom
categories and sub-categories to be defined and reordered. There is
one category listed at the top level in the hierarchy which behaves
differently to the others - the category: \char`\"{}Official courses
(with institutional codes)\char`\"{}. This is the category which is
used for self-cataloged courses: the option is to either display or
not display.

Although sub-categories can not be defined via this interface for
this \char`\"{}system\char`\"{} category (unlike the other \char`\"{}custom\char`\"{}
categories), customization of two routines in localenroll.pm - \&instcode\_defaults()
and \&instcode\_format() are used to automatically generate linked
select boxes which will be displayed when the course catalog is shown
to allow users to include limits to their searches for official courses.
If these routines have not been customized, the catalog for official
courses will display all courses with institutional codes, which have
not been specifically hidden.

When \&instcode\_format() has been customized it will populate perl
structures (hashes and arrays) which LON-CAPA will use to generate
the Javascript code embedded in the course catalog page which is used
in the functioning of the linked select boxes. The contents of the
hashes and arrays are determined from the complete list of institutional
course codes used in the domain. For example at MSU, the following
linked select boxes are displayed for the official courses catalog:
Year, Semester, Department, Number.

The course catalog is useful in domains where Course Coordinators
have opted to allow self-enrollment in their courses. In such cases,
students can include a flag to only display courses allowing self
enrollment when they display courses from the catalog. Course Coordinators
will be advised, when enabling self-enrollment, if a courses is currently
unlisted in the course catalog (and therefore difficult for students
to locate), and the action to take to rectify the reason why there
is no listing, which could be because: 

\begin{itemize}
\item the course is hidden 
\item the course has no institutional code 
\item the course has not been assigned to any custom categories 
\item the course has an institutional code, but display of the official
courses catalog is disabled 
\end{itemize}

Index: loncom/html/adm/help/tex/Domain_Configuration_Color_Schemes.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_Color_Schemes.tex
\label{Domain_Configuration_Color_Schemes}
Default color schemes can be set for the domain for four types of
user context: 

\begin{itemize}
\item Student
\item Course Coordinator
\item Author/Co-author/Assistant Author
\item Domain roles (Domain Coordinator)
\end{itemize}
In each case the following can be set or modified:

\begin{itemize}
\item Header image displayed in place of the inline navigation controls
when the page is viewed with the Remote Control active. 
\item Color used for text in the LON-CAPA interface 
\item Background colors used for the page itself, and the inline navigation
(if shown) and the page header below it, and a border to the header
(not used). 
\item Default colors for links in the page, depending on status: either
active, visited or default (if neither apply).
\end{itemize}
Individual users can override any default settings you establish for
the domain via the \char`\"{}Change Color Scheme\char`\"{} link in
their individual Preferences screen. In the absence of individual
preferences, any domain defaults you set will be used whenever users
from your domain are using LON-CAPA, regardless of which domain owns
the server hosting the session. 

Index: loncom/html/adm/help/tex/Domain_Configuration_Contact_Info.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_Contact_Info.tex
\label{Domain_Configuration_Contact_Info}
LON-CAPA will send automatic e-mail to administrators/support staff
under certain circumstances. The contact information data table can
be used to provide e-mail addresses for receipt of these e-mails and
to configure which types of e-mail should be sent to each address.

The types of e-mail are: 

\begin{itemize}
\item Error reports - whenever a server encounters a 500 error (Internal
Server Error), Apache will handle that event by displaying an error
report form which the affected user can complete and submit. The submission,
which contains session information besides any information provided
by the user, will be sent as an e-mail.
\item Package update alerts - the CHECKRPMS script run every other day will
generate e-mail if it detects that package updates are needed. 
\item Helpdesk requests - clicking the Help link displayed at the right
side of the inline navigation bar at the top of a LON-CAPA page (unless
the Remote Control is active) will display a Help Menu which includes
an \char`\"{}Ask helpdesk\char`\"{} link. The \char`\"{}Ask helpdesk\char`\"{}
link provides access to a web form which a user will complete and
submit to request LON-CAPA support. The submission, which contains
information about the user's browser, besides information provided
by the user, will be sent as an e-mail.
\end{itemize}
Definition of the default Admin email address and the default Support
E-mail address saved from the {}``Contact Information'' screen supercede
any definitions made when ./UPDATE is run to update to a new version
of LON-CAPA. Addresses entered the first time ./UPDATE was run on
the primary library server for the domain (i.e., when LON-CAPA was
first installed) will continue to apply until the first \char`\"{}Save\char`\"{}
of the Contact Information settings has occurred in the domain. 

Index: loncom/html/adm/help/tex/Domain_Configuration_InstDirectory_Search.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_InstDirectory_Search.tex
\label{Domain_Configuration_InstDirectory_Search}
LON-CAPA provides a mechanism to search for users by complete username,
last name, or last name,first name (or fragments of each). Accounts
within the LON-CAPA domain itself can be searched, or alternatively,
an institutional directory may be searched, if you are able to implement
a conduit to directory information to support such searches. This
will be done by customizing the \&get\_userinfo() routine in localenroll.pm.
This routine has a dual role in LON-CAPA. Not only will it support
searches where the user is not excatly known, but it can also be used
to retrieve institutional records for a specific usernames or student/employee
ID. This latter mode of use is appropriate when adding a new user
to LON-CAPA.

Settings for directory searches are: 

\begin{itemize}
\item Set directory searches as available or unavailable in the domain
\item Set whether users from other LON-CAPA domains can use the institutional
directory search to search for users. Note: this only applies to institutional
directory data, users with privileges to add users to a course will
always be able to search the LON-CAPA user database for other domains.
\item For searches by users within your domain, you can limit the users
who can use directory search based on institutional status
\item Set which types of search method - username, last name or last name,first
name are allowed for institutional searches
\item Set which types of search latitude - exact match, begins with or contains
- are allowed
\end{itemize}
In the case of a \char`\"{}contains\char`\"{} type search at least
three characters must be entered by the user as the search term. Searches
are case insensitive.

Index: loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_LangTZAuth.tex
\label{Domain_Configuration_LangTZAuth}
The login page can be customized for your domain, by:

\begin{itemize}
\item uploading custom image files, 
\item changing colors of text, links or backgrounds 
\item enabling/disabling display of sepcific links 
\end{itemize}
Logos displayed in the login page configuration table are scaled down
from the full size used in the login-page itself. 

\hfill{}

\noindent The following elements are configurable: 

\begin{itemize}
\item Header image at the top of the page
\item Main Logo centred in the upper part of the main panel 
\item Domain logo in the lower left corner of the main panel 
\item Header above the login panel - can also be set to use text (\char`\"{}Log
in\char`\"{}) instead of an image. 
\item Backgrond colors for the page itself, the main panel, and the left
(side) panel. 
\item Text color used for text on the page
\item Enable/disable display of three links: 

\begin{itemize}
\item Course Catalog, for a catalog of courses; 
\item Admin E-mail, for the e-mail address of the administrator; 
\item New User, for users to create their own accounts. 
\end{itemize}
\item Default colors for links in the page, depending on status: either
active, visited or default (if neither apply).
\end{itemize}

Index: loncom/html/adm/help/tex/Domain_Configuration_Quotas.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_Quotas.tex
\label{Domain_Configuration_Quotas}
Each user in your domain will receive an individual portfolio space
to which files may be uploaded. Students can submit items from their
portfolio to meet the requirements of assignments in their courses.
The default quotas you set for users in your domain will be overridden
by any quota you set for individual users. 

Default quotas (in Mb) can be set to vary by institutional affiliation,
as defined for your domain (e.g., Faculty, Adjunct, Staff, Student).
If a user is affiliated with more than one group, whichever default
quota is largest for the different groups is the one which applies.
Institutional types need to be defined in a customized version of
\&inst\_usertypes() in the localenroll.pm module installed on the
primary server in your domain. If no types have been defined, then
a single default quota will apply for all users from the domain.

Index: loncom/html/adm/help/tex/Domain_Configuration_Scantron_Format.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_Scantron_Format.tex
\label{Domain_Configuration_Scantron_Format}
Where scantron exams are used in a course, the format of data in the
file generated from the processing of bubbled-in scantron sheets may
vary between institutions. The format definitions available when performing
scantron grading in LON-CAPA were originally listed in the scantronformat.tab
file, stored in /home/httpd/lonTabs, which might have been modified
locally on each server. 

Starting with LON-CAPA 2.7, scantron format information is read from
either a custom.tab file, or a default.tab file both of which belong
to the special domain configuration user (\$dom-domainconfig, where
\$dom is the name of the domain) and which are automatically published
into resource space. 

For LON-CAPA installations older than 2.7, when the primary library
server for the domain has been updated, a Domain Coordinator should
display the \char`\"{}Scantron format file\char`\"{} configuration
page via \char`\"{}Domain Configuration\char`\"{}. The first time
this page is displayed, a default.tab (a copy of the standard LON-CAPA
scantronformat.tab file), and a custom.tab (if the scantronform.tab
file currently on the server differs from the standard file) will
be copied and published. Thereafter any changes to scantron format
files to be used for grading scantron exams in courses from the domain
will be made via the Domain Configuration menu. Any scantronform.tab
files in /home/httpd/lonTab directories on servers in the domain will
no longer be used.

The settings available via \char`\"{}Scantron format file\char`\"{}
support upload of a new custom file, or deletion of an existing custom
file (in which case grading will default to use of the default.tab
file). An uploaded scantron format file contains one or more lines
of colon-separated values for the parameters in the following order:

name:description:CODEtype:CODEstart:CODElength:IDstart:IDlength:Qstart:Qlength:Qoff:Qon:PaperID:PaperIDlength:FirstName:FirstNamelength:LastName:LastNamelength 

\begin{itemize}
\item name is the internal identifier used within LON-CAPA
\item description is the text displayed for each option in the   
the {}``Format of data file'' dropdown in the Scantron grading
screen.  The user will choose the appropriate format for the scantron
file currently being used for scantron grading.
\item CODEtype can be either 'none' 'letter' 'number' 
\item Qon can be either:

\begin{itemize}
\item the symbol that says a bubble has been selected, or
\item 'letter' (for when the selected letter appears), or 
\item 'number' for when a number indicating the selected letter appears 
\end{itemize}
\end{itemize}
As an example, below are four different format lines: the first two
were used at MSU prior to 2006; the last two have been used since
then.

\begin{itemize}
\item msunocode:MSU without any CODE:none:0:0:57:9:77:10: :1:5:5:51:1:41:10 
\item msucode:MSU with CODE in separate location:letter:69:6:57:9:77:10:
:1:5:5:51:1:41:10 
\item msucodelet:MSU with CODE in separate location (letter format):-1:69:6:57:9:77:1:
:letter:5:5:51:1:41:10 
\item msucodenum:MSU with CODE in separate location (number format):-1:69:6:57:9:77:1:
:number:5:5:51:1:41:10
\end{itemize}

Index: loncom/html/adm/help/tex/Domain_Configuration_User_Creation.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_User_Creation.tex
\label{Domain_Configuration_User_Creation}
Identity management in a LON-CAPA domain is dependent on settings
made for user creation and user modification. Of particular concern
is the potential for assignment of usernames in a format used by your
institution when the username does not yet exist. In such a case,
authentication is likely to be set to be \char`\"{}internal\char`\"{},
and should a real user be created in the future, and be enrolled in
a course by auto-enrollment, the user would either be unable to authenticate
(using LON-CAPA log-in page), or would be authenticated by SSO, and
have access to the original user's roles and associated information.

It is important therefore to establish format rules for new usernames
so the only users created with institutional-type usernames are the
real users themselves with the appropriate authentication type (Kerberos
or localauth). Even without format rules, the Domain Coordinator can
set who can create new users, and the authentication types that may
be set in different context.

The domain-wide options available for user creation are: 

\begin{itemize}
\item Activate/deactivate operation of format rule(s) for usernames 
\item Activate/deactivate opration of format rule(s) for student/employee
IDs 
\item Activate/deactivate operation of format rule(s) which prohibit self-created
accounts using certain types of e-mail address as the username.
\item Control which types of username (official or non-official) may be
used when creating new users in course or author context 
\item Control which types of user may create their own accounts in LON-CAPA 
\item Control which types of authentication may be used when assigning authentication
to new users in author, course or domain context
\end{itemize}
The format rules themselves are defined by customizing the following
routines in localenroll.pm: 

\begin{itemize}
\item usernames: \&username\_rules() and \&username\_check()
\item IDs: \&id\_rules() and \&id\_check()
\item self-created accounts: \&selfcreate\_rules() and \&selfcreate\_check()
\end{itemize}
The first two of these - username and ID check, when enforced, require
that if a username and/or ID of the activated formats is to be used
in LON-CAPA, they must exist in the institutional directory. If they
exist, the corresponding user information (first name, middle name,
last name, e-mail address) will be used when creating the new user
account. If they do not exist, account creation will not occur.

The third one operates in the opposite manner - if a user attempts
to self-create an account employing a username with an e-mail address
in a format which matches the rule, the action does not proceed, and
the user is directed to create an account with the corresponding institutional
log-in. In this case account creation can only occur once the user
has authenticated using that login. 

Index: loncom/html/adm/help/tex/Domain_Configuration_User_Modification.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_User_Modification.tex
\label{Domain_Configuration_User_Modification}
Configuring settings which apply to modification of existing user
information (names, e-mail address, student/employee ID) forms a part
of LON-CAPA identity management. Authors and Course Coordinators both
have access to \char`\"{}Manage Users\char`\"{} which permits them
to assign roles to users appropriate to the context. In addition to
the ability to assign roles, the ability to modify existing user information
may be conferred in this context depending on the target user's role(s).
The types of user information which are modifiable in the different
contexts is also configurable.

If you have chosen to permit users to self-create their accounts,
you can also set which fields in their user records they may set,
in cases where the corresponding fields retrieved from the institutional
directory are blank. Users may receive different settings depending
on their institutional status(es). Institutional status types available
are the ones defined for the domain in a customized version of the
\&inst\_usertypes() routine in the localenroll.pm module installed
on the primary server in your domain.

Index: loncom/html/adm/help/tex/Domain_Configuration_Login_Page.tex
+++ loncom/html/adm/help/tex/Domain_Configuration_Login_Page.tex
\label{Domain_Configuration_Login_Page}
The login page can be customized for your domain, by:

\begin{itemize}
\item uploading custom image files, 
\item changing colors of text, links or backgrounds 
\item enabling/disabling display of sepcific links 
\end{itemize}
Logos displayed in the login page configuration table are scaled down
from the full size used in the login-page itself. 

\hfill{}

\noindent The following elements are configurable: 

\begin{itemize}
\item Header image at the top of the page
\item Main Logo centred in the upper part of the main panel 
\item Domain logo in the lower left corner of the main panel 
\item Header above the login panel - can also be set to use text (\char`\"{}Log
in\char`\"{}) instead of an image. 
\item Backgrond colors for the page itself, the main panel, and the left
(side) panel. 
\item Text color used for text on the page
\item Enable/disable display of three links: 

\begin{itemize}
\item Course Catalog, for a catalog of courses; 
\item Admin E-mail, for the e-mail address of the administrator; 
\item New User, for users to create their own accounts. 
\end{itemize}
\item Default colors for links in the page, depending on status: either
active, visited or default (if neither apply).
\end{itemize}

--raeburn1216780919--