==================================
w.c.s. - Guide de l'administrateur
==================================

:auteur: Christophe Boutet et Pierre Cros
:contact: cboutet@entrouvert.com
:contact: pcros@entrouvert.com
:copyright: Copyright © 2005-2006 Entr'ouvert

.. contents:: Table des matières
.. section-numbering::

Vue générale
============

w.c.s est un logiciel permettant de générer des formulaires et des consultations
en ligne et de les intégrer dans un workflow. Il est conforme aux standards et
protocoles du consortium `Liberty Alliance`_ grâce à l'utilisation de la
librairie certifiée Lasso_. Il dispose d'une interface d'administration et d'un
back-office soignés permettant une personnalisation poussée et son adaption à de
nombreux usages différents.

Se procurer et installer w.c.s.
===============================

Installation sous Debian_ Sarge
+++++++++++++++++++++++++++++++

Pour fonctionner correctement Authentic s'appuie sur :

* Apache_ (1.3 ou 2, Apache2 recommandé) ;

* Lasso_ (0.6.2) ;

* Quixote_ (2.0) ;

* mod_python_ ou SCGI_ (SCGI_ recommandé).


Installation des paquets
------------------------

En tant que root tapez la commande ::

 echo 'deb http://deb.entrouvert.org/ sarge main' \
 >> /etc/apt/sources.list

Cette commande ajoute le répertoire qui contient tous les paquets nécessaires
dans votre fichier sources.list.

Toujours en tant que root tapez ::

 apt-get update
 apt-get install wcs

Tous les paquets nécessaires sont installés.

Si vous ne souhaitez pas modifier votre fichier sources.list vous pouvez
récupérer les paquets nécessaire et les installer manuellement avec la commande
dpkg -i :

* wcs et Quixote 2.0 sur http://wcs.labs.libre-entreprise.org/ ;

* Lasso sur http://lasso.entrouvert.org.

Configuration d'Apache_
-----------------------

Il faut ensuite configurer Apache_ pour avoir un virtual host w.c.s., le
fichier d'example ci-dessous s'appelle vhost-apache-wcs et il est installé par
défaut. Il fonctionne (en remplaçant www.example.com par le nom de domaine que
vous avez choisi pour w.c.s., nous utiliserons wcs.example.com) pour Apache2 et
SCGI_. Vous le trouverez dans le répertoire ``/etc/apache2/sites-enabled`` ::

 <VirtualHost *>
   ServerAdmin webmaster@locahost
   ServerName wcs.example.com
   DocumentRoot /usr/share/wcs/web/
   <LocationMatch "^/(forms|admin|liberty|login|logout|themes|consultations|token)|^/$">
     SCGIServer 127.0.0.1:3001
     SCGIHandler On
   </LocationMatch>
   SSLEngine On
   CustomLog /var/log/apache2/wcs-access.log combined
   ErrorLog /var/log/apache2/wcs-error.log
 </VirtualHost>

Il faut également vous assurer qu'Apache_ est configuré pour supporter le SSL,
vérifiez que dans votre fichier /etc/apache2/ports.conf vous avez une ligne ::

 Listen 443

Ajoutez la si elle n'est pas présente.

Ensuite, il s'agit d'activer le module SCGI, s'il ne l'était déjà ::

 a2enmod scgi

Vous pouvez ensuite redémarrer Apache_ (toujours en root) ::

 /etc/init.d/apache2 restart

Pensez également à modifier votre fichier /etc/hosts le cas échéant. Lorsque wcs
fonctionne, l'interface d'administration est se trouve à l'URL
http://wcs.example.com/admin.

Installation avec une autre distribution Linux
++++++++++++++++++++++++++++++++++++++++++++++

Nous supposons qu'Apache_, SCGI_ ou mod_python_ sont déjà installés. Il faut
ensuite télécharger les sources suivantes et les installer :

* Lasso http://lasso.entrouvert.org ;

* Quixote http://www.mems-exchange.org/software/quixote/ ;

* Authentic http://authentic.labs.libre-entreprise.org/.

Pour installer Authentic, décompressez les sources que vous avez téléchargées
et lancez le script setup.py ::

 tar xzf wcs*.tar.gz
 cd wcs*
 python setup.py install

Il vous faut ensuite configurer correctement Apache_.

Lorsque que w.c.s. fonctionne, l'interface d'administration est accessible à
l'URL http://wcs.example.com/admin.

Installation sous Windows
+++++++++++++++++++++++++

Nous n'avons pas à l'heure actuelle réalisé d'installation de w.c.s. sous
Windows. Mais étant donné que tous les composants nécessaires à son utilisation
fonctionne sur ce système d'exploitation, l'installation est envisageable et
nous seront peut-être amenés à la décrire bientôt. N'hésitez pas à nous faire
part de vos tentatives.

Configuration de base de wcs
============================

Création clés publiques et privées
++++++++++++++++++++++++++++++++++

Si vous ne possédez pas de clés au format pem, il vous faut en créer car elles
seront nécessaire pour configurer wcs comme fournisseur de service. Pour créer
un couple clé publique/clé privée avec OpenSSL_, utilisez ces commandes ::

 openssl genrsa -out nom-de-la-clé-privé.pem 2048

Cette commande crée la clé privée sous la forme d'un fichier appelé
nom-de-la-clé-privé.pem. ::

 openssl rsa -in nom-de-la-clé-privé-key.pem -pubout\
 -out nom-de-la-clé-publique.pem

Cette commande extrait la clé publique de la clé privée sous la forme d'un
fichier appelé nom-de-la-clé-publique.pem.

Configuration de base du fournisseur de service
+++++++++++++++++++++++++++++++++++++++++++++++

Allez sur l'interface d'administration de w.c.s. http://wcs.example.com/admin.

.. figure:: figures/wcs-admin.png

   L'interface d'administration lorsqu'aucun utilisateur n'existe encore.

Cliquez sur l'onglet paramètres puis sur le lien « fournisseur de service ».

.. figure:: figures/wcs-admin-settings-liberty_sp.png

   Configuration du fournisseur de service wcs

Les deux premiers champs sont remplis automatiquement, ne cherchez pas à les
modifier à moins de savoir réellement ce que vous faites.

Champs :

* Identifiant du fournisseur (un identifiant qui prend nécessairement la
  forme d'une URL) ;

* URL de la racine (toutes les URL nécessaires à `Liberty Alliance`_ se
  trouvent sur cette racine) ;

* Nom de l'organisation (nom de l'organisation qui gère le fournisseur
  d'identité) ;

* Clé privée (clé privée au format pem) ;

* Clé publique (clé publique au format pem) ;

* Domaine commun, pour « Identity Provider Introduction » (L'identity
  provider introduction est un mécanisme `Liberty Alliance`_ permettant à un
  fournisseur d'identité, pour un nom de domaine particulier, de générer un
  cookie sur la machine de l'utilisateur. C'est utile lorsqu'il y a plusieurs
  fournisseurs d'identités associés à un fournisseur de service : dans le
  cookie on associe les fournisseurs de service d'un domaine, au fournisseur
  d'identité qui a délivré le cookie. Cela permet de stipuler au fournisseur de
  service : « cet utilisateur utilise le fournisseur d'identité du domaine
  ».).

Une fois tous ces champs dûment remplis, cliquez sur le bouton valider.

Enregistrement du fichier de metadata
+++++++++++++++++++++++++++++++++++++

Dans l'interface d'administration de wcs vous pouvez récupérer le
fichier de metadata. Cela sera utile par la suite lorsqu'il s'agira de
déclarer wcs fournisseur de service sur un fournisseur d'identité. Procédez
comme suit :

* cliquez sur l'onglet paramètres ;

* vous voyez un lien «  Metadata du fournisseur de service ». Faites un clic
  droit et « enregistrer la cible du lien sous » ;

* choisissez le nom que vous donnez à ce fichier (par exemple
  metadata-wcs.xml) et l'endroit ou vous le sauvegardez.

Déclarer un fournisseur d'identité
++++++++++++++++++++++++++++++++++

Sur l'interface d'administration de w.c.s., cliquez sur l'onglet
paramètres, puis sur le lien « fournisseurs d'identités ». Cliquez encore
sur  « nouveau ».

.. figure:: figures/wcs-admin-settings-liberty_idp-new.png

   Déclarer un fournisseur d'identité

Compléter les champs suivants :

* Metadata (le fichier de metadata du fournisseur d'identité) ;

* Clé publique (la clé publique du fournisseur d'identité) ;

* Chaîne de certification (certificat contenant toute la chaîne
  d'authentification jusqu'au root CA).

Création Administrateur
+++++++++++++++++++++++

Les paramètres Liberty doivent avoir été configurés préablablement à la création
des utilisateurs. Pour créer l'administrateur, allez sur l'interface
d'administration de w.c.s.. Cliquez sur l'onglet « Gestion des identités », puis
sur le lien « Ajouter une identité ».

.. figure:: figures/wcs-admin-users-new.png

   Création de la première identité, celle de l'administrateur

Remplissez les champs suivants :

* Nom (saisissez vos Nom et prénom) ;

* Courriel (saisissez votre Courriel) ;

* Compte administrateur (cochez cette case pour que le compte créé soit un
  compte administrateur) ;

Cliquez sur valider, le compte administrateur est créé.

Onglet rôles
============

À chaque rôle il faut affecter une ou plusieurs adresses mail, qui seront
destinataires des notifications de remplissage de formulaires par les
utilisateurs.

Onglet utilisateurs
===================

Une fois un rôle créé, il faut aller sur les utilisateurs qui y auront accès au 
back-office correspondant et leur affecter le rôle.

On peut également grâce à cet onglet créer des utilisateurs, mais la création
d'un utilisateur à ce niveau n'est pas suffisante, s'agissant d'un contexte 
Liberty Alliance, il faut également que l'utilisateur dispose d'un compte sur le 
fournisseur d'identité.

Onglet catégories
=================

Il permet de gérer les catégories dans lesquelles les formulaires seront rangés 
coté utilisateur, par exemple « vie pratique ».

Par défaut si la catégorie de rangement n'est pas choisie pour un formulaire, 
il est classé dans la catégorie divers.

Onglet formulaires
==================

il permet de créer et d'administrer les formulaires :

Création du formulaire
++++++++++++++++++++++

Cliquer sur nouveau

Donner un nom au formulaire, puis fixer la valeur des champs et les nommer:
Les champs : titre, sous titre, et commentaire, ne sont pas de champs de 
réponse, ils servent à apporter des compléments d'information sur les 
formulaires.

Le champ commentaire, en particulier, permet de préciser le caractère 
obligatoire des réponses sur certaines question, matérialisé par un carré rouge,
mais aussi tout type d'information utiles, en revanche, il n'a pas fonction à 
servir d'aide directe à la complétion d'une question (traitée par ailleurs).

Les autres champs fixent la nature de la réponse que l'on souhaite voir 
apportée : date, adresse mail, bloc de texte, ligne de texte (qui sert également
pour les chiffres), case à cocher, liste, upload de fichier.

Une fois les champs fixés, il faut choisir le destinataire du formulaire.

Ensuite on affecte un rôle au formulaire, par défaut un formulaire est 
accessible à tout le monde, on peut restreindre l'accès de manière fine par le
biais des rôles.

La catégorie permet de classer l'affichage du formulaire coté utilisateur.

Il reste alors une série d'options :

- Cochée, la case « Inclure une page de confirmation » permet d'afficher une page
  récapitulative coté utilisateur avant qu'il n'envoie le formulaire.

- Cochée, la case « Permettre la discussion » autorise un dialogue via le 
  back-office entre l'utilisateur et la personne en charge du traitement d'un
  formulaire.

- Cochée, la case « accès public » permet à tous les utilisateurs d'un formulaire
  de visualiser toutes les réponses apportées.

- Cochée, la case « Envoyer des courriels de notification détaillés » , génère 
  pour la personne chargée du traitement, un mail reprenant tous les champs 
  complétés par le demandeur.

- Cochée, la case « Désactiver l'accès au formulaire » ne permet plus la 
  visualisation, donc la complétion du formulaire concerné coté utilisateur.
  Cette option permet de conserver dans la base les formulaires à utilisation 
  saisonnière.

La validation en bas de page génère la création du formulaire et vous dirige
vers l'écran suivant qui va vous permettre de définir précisement les champs 
selon leur type.

Définition des champs 
+++++++++++++++++++++

Outre la définition des champs, vous pouvez depuis cet écran modifier leur ordre
par « drag&drop ».

Tous les types de champs disposent d'une série d'options communes:

Obligatoire: il s'agit d'une case à cocher qui fixe le caractère obligatoire
d'une réponse pour l'utilisateur, si la case n'est pas cochée, la réponse à la
question est optionnelle.

Affichage dans les Listings: il n'est pas forcément pertinent que tous les
champs figurent dans le listing de back-office d'autant que dans le cas de
formulaires comprenant beaucoup de champs, le listing n'est pas très lisible si
tous sont affichés. Cette option permet donc, par le biais d'une case à cocher
de fixer, ou non, l'affichage du champ concerné dans le listing back-office.

Remarque: permet d'apporter une aide au répondant, dans le cas d'un champ 
adresse électronique: Exemple: francis.kuntz@wanagro.com.

Champ date : Il oblige le répondant à compléter une date de la forme 12/12/2005,
dans le cas des mois ou jours à chiffre unique, le zéro n'est pas obligatoire, 
3/6/2005 est admis.

Les dates admises actuellement vont du 01/01/1800 au 31/12/2099, un contrôle est
opéré.

Champ adresse électronique : le répondant devra mentionner une adresse mail, la
vérification s'effectue sur l'arobase.

Champ bloc de texte : la taille du bloc de texte est modifiable, par défaut le 
nombre de caractères par ligne est fixé à 20 et le nombre de lignes à 3. Pour un
affichage optimal coté utilisateur, 70 caractères par ligne constitue un bon 
compromis. 10 lignes par bloc permet une réponse déjà longue, sachant que si 
l'utilisateur dépasse, il aura un ascenseur.

Champ ligne de texte: Par défaut le nombre de caractères d'une ligne est fixé à
20, Le champ texte permet, de base une réponse comprenant des lettres et des 
chiffres, si la réponse ne doit comporter que des chiffres, il convient 
d'appliquer une règle dans le champ regex prévu à cet effet.

Exemple de règles :

- Tél : 10 chiffres ``^\d{10}$``
- Code postal : 5 chiffres ``^\d{5}$``
- Valeur numérique ``^\d+$``

La valeur Liberty, si elle est complétée autorise le pré-remplissage.
Si vous souhaitez utiliser cette fonction, il est indispensable que vous mettiez
en place un fournisseur de service candle.
La case explicite, si elle est cochée, demande un consentement supplémentaire à
l'utilisateur pour la complétion.

Champ liste : grâce à « éléments », il vous faut fixer possibilités de réponse à
votre liste, ajoutez autant d'éléments que nécessaire.

Vous pouvez choisir d'afficher les réponses sous forme de bouton radio à l'aide 
de la case à cocher prévue à cet effet.

Champ case à cocher : Case à cocher ; Un formulaire, une fois créé apparaît
sous la forme d'un résumé d'une ligne en bout de laquelle sont affichés 4
boutons qui respectivement permettent: l'édition, la modification des champs,
la duplication et la suppression.


Éditer
++++++

Le bouton prévu à cet effet permet d'éditer le formulaire.
Vous pourrez ensuite modifier le cas échéant, les types de champ du formulaire 
concerné, ainsi que les rôles, catégories, destinataire et d'activer/désactiver 
le formulaire.

Modifier
++++++++

Grâce à ce bouton, vous pourrez ensuite modifier les paramètres des champs d'un
formulaire ainsi que les déplacer par « drag&drop ».

Dupliquer
+++++++++

Ce bouton permet la duplication d'un formulaire, pour éviter d'avoir à faire une
création ex-nihilo si vous souhaiter créer un formulaire ayant une structuration
proche d'un existant.

Supprimer
+++++++++

Vous pourrez ici supprimer un formulaire. Afin d'éviter les suppressions 
brutales ou les erreurs de manipulation, une confirmation de la suppression 
est demandée.

Onglet Logs 
===========

S'il est activé, permet d'analyser le comportement des répondants.

Onglet Paramètres
=================

Sert à paramétrer complètement l'application



Licences
========

w.c.s., Authentic_, et Lasso_ sont publiés sous la `licence GNU/GPL`_.

.. _Lasso: http://lasso.entrouvert.org/
.. _`licence GNU/GPL`: http://www.gnu.org/copyleft/gpl.html
.. _`Liberty Alliance`: http://projectliberty.org/
.. _Authentic: http://authentic.labs.libre-entreprise.org
.. _Debian: http://www.debian.org/
.. _Apache: http://www.apache.org/
.. _Quixote: http://www.mems-exchange.org/software/Quixote
.. _mod_python: http://www.modpython.org/
.. _SCGI: http://www.mems-exchange.org/software/scgi/
.. _OpenSSL: http://www.openssl.org
