Some finalizations.

[kic.git] / enrolment_status.tex

\documentclass[12pt,a4paper]{article}
\usepackage[nolists,nomarkers]{endfloat}
%\usepackage[english]{babel}
\usepackage{textcomp}
\usepackage[utf8x]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{color}
\usepackage{graphicx}
\usepackage{chngpage}
\usepackage{ifthen}
\usepackage{gitinfo}
%\enabledraftstandard
\usepackage[firstpage]{draftwatermark}
\usepackage[hidelinks]{hyperref}
\usepackage{url}
\usepackage{breakurl}
\usepackage{xcolor,soul,lipsum}
\usepackage{lineno}
%\usepackage{adjustbox}
%\usepackage{fancyvrb}
%\usepackage{verbatim}
\usepackage{rotating}
\usepackage{listings}

\newcommand{\myul}[1]{\ul{#1}}

%\SetWatermarkText{ENTWURF}
\SetWatermarkText{DRAFT}
\SetWatermarkScale{4}
\SetWatermarkAngle{50}
\SetWatermarkLightness{0.90}

\sloppy
%\hoffset-3mm
\parindent0mm

\newcommand{\da}{DA}
\newcommand{\sa}{SA}
\newcommand{\ecs}{ECS}
\newcommand{\ilias}{ILIAS}
\newcommand{\cces}{\texttt{cc/enrolment\_status\ }}
\newcommand{\button}[1]{\fbox{\texttt{#1}}}
\newcommand{\jsToAppletComUrlA}{\mbox{http://stackoverflow.com/questions/7278626/javascript-to-java-applet-communication}}
\newcommand{\jsToAppletComUrlB}{\mbox{http://docs.oracle.com/javase/tutorial/deployment/applet/invokingAppletMethodsFromJavaScript.html}}
\newcommand{\appletToDom}{\mbox{http://docs.oracle.com/javase/tutorial/deployment/applet/manipulatingDOMFromApplet.html}}

\lstset{basicstyle=\ttfamily}
\newcommand{\includecode}[2][{}]{\lstinputlisting[numbers=left, numberstyle=\tiny, stepnumber=1, numbersep=5pt, breaklines, breakatwhitespace, linewidth=1.1\textheight, xleftmargin=1cm, language=#1]{#2}}

\newcommand{\texta}{}
\newcommand{\textb}{}
\newcommand{\textc}{}
\newcommand{\textd}{}
\newcommand{\texte}{}
\newcommand{\textf}{}

%\linenumbers

\begin{document}
\title{Mahara/Moodle enrolment status}
\author{David Boehringer\\Universit\"at Stuttgart \and Heiko Bernl\"ohr\\FreeIT.de}
\maketitle
\begin{center}
%  Version: 2.0
  Version: \gitVtag\\
%  Commit-id: \gitAbbrevHash
\end{center}
\begin{abstract}
New ECS resource providing enrolment status for users enroled to
external courses (via courselinks). The course providing participant (e.g.
Moodle) informs the courselink providing participant of the subscribed user
(e.g. Mahara) about every change of its enrolment status in the course.
\end{abstract}

%\vspace{\fill}
%\begin{center}
%\includegraphics[scale=1.0]{vip_lms}
%\end{center}
%\vspace{\fill}
%
\newpage

\section{Enrolment status}

The \cces resource describes an enrolment status of a
remotly subscribed user (via courselinks) to a course. This document supersedes
the part
\begin{quote}
  {\bf Moodle}\\
  1. New enrolmentStatus resource
\end{quote}
in \cite{specBoehMaharaMoodle}.

\subsection{Events\label{events}}
\newcommand{\rstat}[1]{return status: #1}
For the following event considerations please have always the state chart on
page \pageref{state:enrolmentStatus} in mind.\medskip

Moodle has to send the user enrolment status to Mahara on these events:
\begin{description}
  \item[first time clicking courselink] A user clicks on a courselink on Mahara
    for the first time and tries to consume the linked course on Moodle (sequence
    diagram on page \pageref{seq:initialEnrolmentStatus}).\\
    \rstat{active | pending }
  \item[reject] User will be rejected by course or system admin. This could only happen
    in \textit{pending} state, e.g. user was on a waiting list, but had not been
    accepted for the course.\\
    \rstat{rejected}
  \item[subscribe] User will be subcribed to course (leaving waiting list). Now
    he is able to access and consume the course.\\
    \rstat{active}
  \item[waiting list] User will be transfered to waiting list
    i.e. he can't access and consume the course yet. He has to wait until
    he will be subscribed to the course.\\
    \rstat{pending}
  \item[unsubscribe] User ended course membership himself or his course
    membership has been terminated by course administrator or system
    administrator. To access and consume the course again he has to enrole
    again.\\
    \rstat{unsubscribed}
  \item[disable subscription] User is disabled by course or system
    administrator, i.e. he is (temporarly) not allowed to access course for
    whatever reason.\\
    \rstat{denied}
  \item[enable subscription] User is enabled by course or system administrator,
    i.e. he is to be allowed to access course again.\\
    \rstat{active}
  \item[delete user account] User account on remote system is deleted. \cces
    has to be sent for all of the user's course memberships.\\
    \rstat{unsubscribed}
  \item[deactivate user account] User account on remote system is deactivated.\\
    \rstat{inactive\_account}
  \item[activate user account] User account on remote system is activated.\\
    \rstat{active | pending | denied}
  \item[subsequently clicking courselink] A user subsequently clicks a
    courselink on Mahara and consumes an already enroled course on Moodle (see
    page \pageref{seq:subsequentEnrolmentStatus}).  After this event Moodle has
    to send the current enrolment status.  This also guarantees to have a
    status even if Mahara just forget/loose\footnote{We don't make the resource
    persistent,  so loosing the status somehow on Mahara it will be refreshed
    after next click on a courselink.} it somehow.\\
    \rstat{pending | active | denied }
\end{description}

\subsection{Status values\label{statusValues}}
\newcommand{\statusnotstored}{This status is usually not persistently stored in the LMS.}
For the following status considerations please have always the state chart on
page \pageref{state:enrolmentStatus} in mind.\medskip

The status attribute could have following values:
\begin{description}
  \item[active] User is enroled and allowed to consume the course.
  \item[pending] User enroled for the course, but is on a waiting list.
  \item[rejected] User is not on waiting list anymore\footnote{Clicking the courselink
    again the user will get through initial enrolment as described in sequence
    diagram on page \pageref{seq:initialEnrolmentStatus}.}. \statusnotstored
  \item[unsubscribed] User is not enroled
    anymore\addtocounter{footnote}{-1}\footnotemark. \statusnotstored
  \item[denied] Still enroled but not allowed to access the course.
  \item[inactive\_account] Still enroled but temporarly not allowed to access
    the system. 
\end{description}
Whereas only \texttt{active, pending, rejected} and \texttt{inactive\_account}
status values have to be stored/saved on the LMS. All others are only generated
while the transitions. 

\subsection{Redirect querystring parameters\label{subsec:redirect_querystring_parameters}}

Our present specification of redirecting a user is defined in
\cite{specRedirectProcedure} and the procedure how to compute the redirect hash
(for securing the redirect parameters) in \cite{specHashCumputing}. As
described in the document \cite{specBoehMaharaMoodle} Moodle has to provide an
interface to define for each participant and its community participation what
personal data should be appended as query strings. Of course to allow this we
have to enhance our specs in \cite{specRedirectProcedure} and
\cite{specHashCumputing}. This still needs to be done.

\begin{figure}[p]
  \includegraphics[scale=0.8]{enrolment_status_seq}
  \caption{\label{seq:initialEnrolmentStatus}Sending enrolment status after
  consuming a courselink for the first time. For \textit{params} in
  the \textit{redirect} of the \textit{consume courselink} block  see
  \ref{subsec:redirect_querystring_parameters} at page
  \pageref{subsec:redirect_querystring_parameters}.}
\end{figure}

\begin{figure}[p]
  \includegraphics[scale=0.8]{subsequent_enrolment_status_seq}
  \caption{\label{seq:subsequentEnrolmentStatus}Sending enrolment status
  after subsequently consuming a courselink.}
\end{figure}

\begin{figure}[p]
  \centering
  \includegraphics[scale=0.5]{enrolment_status_state}
  \caption{\label{state:enrolmentStatus}UML state diagram. Enrolment status of
  a user in respect to a course on a LMS. For event description see
  \ref{events} on page \pageref{events}. For status values description see
  \ref{statusValues} on page \pageref{statusValues}.} 
\end{figure}


\subsection{Resource attributes}

For the json schema of \cces see page \pageref{schema:enrolment_status}.
Following description write on \cces resource attributes for which a user
status has changed or asked for:
\begin{description}
  \item[courseURL] It's a url transfering a courselink consuming user
    directly to the course on the course providing system. It's also used as a
    unique id.
  \item[courseID] It's a unique course id on the course providing system. It
    references the same course as \texttt{courseURL}.
  \item[personID] Unique id of the course consuming user.
  \item[personIDtype] Class/type of \texttt{personID}. It's a controlled
    vocabulary (see page \pageref{schema:enrolment_status} for possible
    values).
  \item[status] Status of the user's course enrolment. It's a controlled
    vocabulary (for possible values see schema on page
    \pageref{schema:enrolment_status} and values descriptions at
    \ref{statusValues}).
\end{description}

\begin{sidewaysfigure}[p]
    \includecode{cc_enrolment_status.schema.json}
    \caption{JSON-Schema definition of enrolment\_status resource}
    \label{schema:enrolment_status}
\end{sidewaysfigure}

\begin{thebibliography}{99}
\bibitem{specRedirectProcedure} \url{http://freeit.de/documents/ecsa/index.html#_redirect_procedure_protocol_when_consuming_courselinks}
\bibitem{specHashCumputing} \url{http://freeit.de/documents/ecsa/index.html#_courselinks}
\bibitem{specBoehMaharaMoodle} David Boehringer. \textit{Mahara and Moodle Specification Version 03}
\end{thebibliography}

\end{document}