h1. Presentation

"AMCtoOwncloud":https://github.com/remjg/AMCtoOwncloud is a _Nautilus script_ that sends Auto Multiple Choice (AMC) annotated papers to Owncloud/Nextcloud and share them with the corresponding students.

Each quiz file is uploaded to a remote folder unique to each student. Then each folder is:

* _shared with the student_ who can be a local user or a remote user on another federated server
* _shared by link_

Eventually, _shared links are saved_ to a newly created @.csv@ file (default behaviour) or to the current @.csv@ file.

In the end, the remote folder structure will look like this:

<pre>
Quizzes/
├── 3emeE/
| ├── MOUSE Mickey (3998) - Maths Quizzes/
│ │ └── Quiz 1 - MOUSE Mickey (3998).pdf
│ └── MOUSE Minnie (3999) - Maths Quizzes/
│ └── Quiz 1 - MOUSE Minnie (3999).pdf
└── 4emeE/
└── DUCK Donald (4999) - Maths Quizzes/
└── Quiz 1 - DUCK Donald (3999).pdf
</pre>

The root folder @Quizzes/@, @Quiz 1@, and @Maths Quizzes@ are configurable, and the other fields come from the @.csv@ `.csv` file.
For instance, if you don't have groups specified in you @.csv@ file, and you live the root folder empty @''@, it can also look like this:

<pre>
MOUSE Mickey (3998) - Maths Quizzes/
└── Quiz 1 - MOUSE Mickey (3998).pdf
MOUSE Minnie (3999) - Maths Quizzes/
└── Quiz 1 - MOUSE Minnie (3999).pdf
DUCK Donald (4999) - Maths Quizzes/
└── Quiz 1 - DUCK Donald (3999).pdf
</pre> I use this script to avoid sending emails.

h1. Installation

Download the "latest release from github":https://github.com/remjg/AMCtoOwncloud/releases/tag/v0.3.0 and copy @AMCtoOwncloud.sh@ and @.AMCtoOwncloud.py@ in the _Nautilus scripts_ folder: @~/.local/share/nautilus/scripts/@

!https://github.com/remjg/AMCtoOwncloud/raw/master/docs/InstallingScript.png!

In order to make it work, you need to install the following Python modules:

@requests@, @lxml.html@, @owncloud@ (see "pyocclient":https://github.com/owncloud/pyocclient).

Usually the first are packaged in your distribution. For the @owncloud@ package, I use the following command:

<pre>
pip3 install pyocclient
</pre>

You also need @gnome-terminal@ or you will have to edit the @AMCtoOwncloud.sh@ script file to use another terminal.

h1. Configuration

Edit the @.AMCtoOwncloud.py@ and change the parameters at the end:

<pre><code class="python">
CSV = '/path/to/csv/students.csv'
FOLDER = 'Quizzes/'
ADDRESS = 'https://ncloud.zaclys.com'
USERNAME = 'MyUserName'
</code></pre>

The CSV file containing all your student information must use colons @:@ as separators and the following headers (there are optional parameters in method @identify_students()@ to change this behaviour, see "Special use cases":https://project.auto-multiple-choice.net/projects/auto-multiple-choice/wiki/Upload_and_share_with_ownCloud_or_NextCloud#Special-use-cases):

<pre>
group:surname:name:number:owncloud:email
3emeE:MOUSE:Mickey:3998:cabitzmil:mickeymouse@domain.com
3emeE:MOUSE:Minnie:3999:agrevet:minniemouse@domain.com
4emeE:DUCK:Donald:4999:prenaud@aFederatedServer.com:donaldduck@domain.com
</pre>

Finally, *annotated papers must contain the student number in their name*
(the first number of the file name is extracted to associate each quiz to the corresponding student). Don't forget to configure @auto-multiple-choice@ using the column headers of your @.csv@ file:

!https://github.com/remjg/AMCtoOwncloud/raw/master/docs/RenamingAnnotatedPapers.png!

h1. Use

_Right click_ on the annotated papers (or on folders) and go to the submenu _scripts_:

!https://github.com/remjg/AMCtoOwncloud/raw/master/docs/UsingScript1-Menu.png!

Then enter your _Owncloud_ password, the name of the quiz, and wait:

!https://github.com/remjg/AMCtoOwncloud/raw/master/docs/UsingScript2-Output.png!

Every encountered issue should be displayed (unmatched files, login error, uploading or sharing errors).

h1. Special use cases

To change the script behaviour, you can edit the last four lines:

<pre><code class="python">
amcsend = AMCtoOwncloud()
amcsend.identify_students(csv_filepath=CSV)
amcsend.connect_owncloud(address=ADDRESS, username=USERNAME, SSO=False)
amcsend.upload_and_share(folder_root=FOLDER, replace_csv=False)
</code></pre>

For instance, if your _Owncloud_ server is behind a _Central Authentication Service (CAS)_, you might want to use the parameter @SSO=True@. It has been tested with the Virtual Learning Environment "Envole":https://envole.ac-dijon.fr of a school that use CAS fo authentication.

You can also save shared links to the _current_ @.csv@ file with @replace_csv=True@. Make sure to backup before and be aware that _comment lines starting with a @#@ are lost in the process_.

More options are available, see below for a full list of parameters with default values:

<pre><code class="python">
amcsend = AMCtoOwncloud(list_of_paths=None, verbose=False)
amcsend.identify_students(csv_filepath=CSV, verbose=False, debug=False,
csv_delimiter=":",
csv_comment="#",
name_header="name",
surname_header="surname",
group_header="group",
number_header="number",
email_header="email",
owncloud_header="owncloud",
link_header="link")
amcsend.connect_owncloud(address=ADDRESS, username=USERNAME, password=None, SSO=False)
amcsend.upload_and_share(folder_root=FOLDER, folder_name=" - Maths Quizzes",
quiz_name=None,
share_with_user=True,
share_by_link=True,
replace_csv=False)
</code></pre>