Aurum Developer Documentation
=============================

This documentation is intended for developers to use or to extend Aurum.

Basic Workflow
--------------

1. Register an Aurum account
2. Create an exercise on Aurum
    * create / upload a repository using the same Aurum username and password, or
    * link to an existing repository on SCM-Manager / Bitbucket / GitHub
3. Createa SCORM module with 
    * access_key provided when creating an exercise  and/or Aurum account registration
    * exercise_id provided when creating an exercise
    * a fixed url to the resource (BlackBoard will point to easyXDM)
4. Upload the SCORM to the desired education management site (e.g BlackBoard)

Create An Aurum Account
-----------------------

Aurum requires instructor to have an account and this account must be created in GCS, Natrium,
Kalium, SCM-Manager and Aurum. As a result, to extend Aurum the developer must provide a way
for the users to register an account. The account registration will go through all five
sub-systems listed above by sending a ``POST`` request to Aurum::

    >>> import requests
    >>> data = {
        ...     'username': 'yeukhon',
        ...     'password': 'mypassword',
        ...     'masteru': 'master-username',
        ...     'masterp': 'master-password',
        ...     }
    >>> res = requests.post('http://<hostname>/aurum/private/account/signup', data=data, verify=False)
    >>> res.status_code
    201
    >>> res.json
    {u'access_key': u'484907fdc4f74539e28c2b1ce14804c0', u'status': u'201', u'reason': u'User yeukhon created.'}

The most important thing to take away is the ``access_key`` which is needed to create a valid SCORM module.

We will use `HTTP status code <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ and
using Pyramid's ``HTTP`` 
`(see here) <http://pyramid.readthedocs.org/en/latest/api/httpexceptions.html#module-pyramid.httpexceptions>`_
 objects as much as possible. Since there is no visual interface yet in Aurum, we assume programmers
will look at ``<name>.json`` and ``<name>.status_code`` to control logic.

Other conditions
~~~~~~~~~~~~~~~~

1. When username is taken::

    >>> res.status_code
    409
    >>> res.json
    {u'reason': u'Username yeukhon already exist in Aurum'}    

The first check is applied on Aurum. If Aurum doesn't find the requested username, it will move on and register
on GCS and then Natrium. We will implement a "first-check" later (find user on all subsytems and then proceed
with the actual registration to ensure idempotence.) So if Natrium has the usernam exist, the ``reason`` will 
actually list the problem in Natrium.

2. When password is less than six characters:: 

    >>> res.status_code
    400
    >>> res.json
    {u'reason': u'Password length must be at least six characters long.'}

Any password less than six characters are considered to be bad. Since most services require at least six characters,
Aurum will use this convention.


Create an exercise repository
-----------------------------

Instructors can create an exercise repository on either SCM Server or BitBucket or GitHub or even Google Code.
** Because of SCM Manager's `REST API <https://bitbucket.org/sdorra/scm-manager/wiki/Home>`_ restriction, we cannot allow regular users (e.g. instructors) to register
a repository, users must use Bitbucket or GitHub. **

The requirement is the repository should be private and adds **glasslab** user to the repository with READ
access. The server can access this exercise repository because we have the SSH key setup in the account.
There is no leak of the exercise repository credential in this process.

We can do this through `Repoman bitbucket apis <https://bitbucket.org/mdogy/repoman-master/src/ad9bb2f9a14c/src/repoman/bitbucket.py>`_ so take a look at that. It can create, update, and delete repository through script so that automation can be achieved.


Register an exercise on Aurum
-----------------------------

Now that the instructor has the repository handy, the instructor should be able to register an exercise on Aurum,
and proceed to creating a scorm module automatically::

    >>> import requests
    >>> data = {
    ...     'username': 'yeukhon',
    ...     'password': 'mypassword',
    ...     'repo': 'ssh://hg@bitbucket.org/story645/gtest'
    ... }
    >>> url = 'http://192.168.1.165/aurum/api/exercise'
    >>> resp = requests.post(url, data=data)
    >>> resp.json
    {u'access_key': u'484907fdc4f74539e28c2b1ce14804c0', u'exercise_id': u'39e43c4c55d4e9806f966b19a9a915a4'}

You get back the ``access_key`` and ``exercise_id`` which you need to put into ``config.js``. See next few sections
on how and where to put these values. The ``access_key`` value is also obtained when the user fist signed up.

    
Create SCORM Module
-------------------

To create a valid SCORM module, we need these files to be present.

1. ims_xml.xsd
2. imscp_rootv1p1p2.xsd
3. imslrm.xml
4. imsmanifest.xml
5. imsmd_rootv1p2p1.xsd
6. index.html
7. js/*
8. css/*  (optional)

The automation script we publish will generate files from 1-5 automatially. Instructors will write the details of the exercise in `ReStructuredText <http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`_ and then use the automated script to compile it into a valid ``index.html``. Javascript and css will also be generated accordingly depending on the learning management platform instructors will be using. Doing it in BlackBoard will require `easyXDM <http://easyxdm.net/wp/category/examples/>`_ to communicate with Aurum.

We created a sample SCORM module for C programming class on bitbucket `here <https://bitbucket.org/yeukhon/aurum-blackboard-scorm>`_.


Aurum SCORM Module
------------------

To be specific, Aurum will assume the following structure::

    ./
        *.xsd files
        *.xml files
        config.js
        index.html
        css/
        js/
            easyXDM/
            ged.js
            *.js  <the rest>

config.js
~~~~~~~~~

This file is the central configuration file and it needs these values::

    var problem_id = "";
    var access_code = "";
    var url = "http://<hostname>/aurum/static/easyXDM/src/cors";

Sample is provided in the sample SCORM module `here <https://bitbucket.org/yeukhon/aurum-blackboard-scorm>`_.


ged.js
~~~~~~
Most of the ged.js contains ajaxs between the blackboard and aurum (and to client).
Notable, we added this line to enable easyXDM communication::


    var xhr = new easyXDM.Rpc({ remote: url }, { remote: { request: {} } });


For developer, the automated script should just clone this ``ged.js`` when generating a new SCORM.


index.html
~~~~~~~~~~
The core of the communication is done in the following snippet in ``index.html``::

    <script src="js/easyXDM/easyXDM.debug.js"></script>
    <script src="config.js"></script>
    <script src="js/ged.js"></script>  
    <script>   
        var srccode = "Loading ....";
        var myCodeMirror = CodeMirror(document.getElementById("EArea"), {
            value: srccode,
            lineNumbers: true
        });
        $(document).ready(ged_main(url,problem_id, access_code));
    </script>

Essentially, when student opens the exercise, it reads the ``index.html`` and execute the javascript.


others
~~~~~~

We use `CodeMirror <http://codemirror.net/>`_ as the code editor and `jQuery <http://jquery.com>`_ as our javascript library. We also include a gallary library called `galleria <http://galleria.io/>`_ to display homework generated images.