<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//UR1//DTD docbookAllegeEsup//FR"
"http://www.esup-portail.org/consortium/espace/docbook/xxe/dtd/docbook_allege_esup.dtd">
<article lang="FR">
  <title>Canal SMS</title>

  <subtitle>Installation</subtitle>

  <section>
    <title>Principe</title>

    <para>L’envoi des messages au travers le portail se fait au moyen d’un
    service de multidiffusion de messages mis en place par France Télécom
    R&amp;D (FTR&amp;D).</para>

    <para>Le service de multidiffusion de FTR&amp;D permet à un service
    applicatif (dans notre cas, il s’agit de ESUP Portail), d’envoyer des
    messages de type courriel, fax, message vocal et SMS via un Web Service.
    Le service permet l’envoi d’un message grâce à une simple requête leur
    serveur. Dans notre cas, seul le mode d'envoi de SMS est utilisé.</para>

    <para>Pour tout renseignement concernant les modalités d'utilisation de ce
    service, veuillez me contacter.</para>
  </section>

  <section>
    <title>Installation</title>

    <para>L'installation du Canal SMS se repose sur les actions
    suivantes:</para>

    <itemizedlist>
      <listitem>
        <para>Recopie éventuelle de la librairie utilisée</para>
      </listitem>

      <listitem>
        <para>Configuration du Canal</para>
      </listitem>

      <listitem>
        <para>Déploiement du Canal</para>
      </listitem>
    </itemizedlist>

    <section>
      <title>Recopie des librairies utilisées</title>

      <para>Ce canal utilise la librairie :<itemizedlist>
          <listitem>
            <para>mail.jar</para>
          </listitem>
        </itemizedlist>Cette librairie est fournie par défaut avec le package
      uPortal esup. Il n'est donc pas nécessaire de l'ajouter manuellement à
      la librairie de votre portail. Cependant, les anciennes versions du
      portail utilisent une version trop ancienne de mail.jar. Si vous
      rencontrez des problèmes de "ClassNotFound" lors de l'utilisation de ce
      canal, voyez à remplacer le mail.jar de la distribution esup par celui
      fourni avec le canal.</para>
    </section>

    <section>
      <title>Configuration du Canal</title>

      <section>
        <title>Configuration générale du Canal</title>

        <para>La configuration générale du Canal SMS se fait via le fichier
        <filename>properties/CSms.xml</filename>.</para>

        <section>
          <title>Structure générale</title>

          <para>La structure générale du fichier de configuration du canal est
          la suivante:<programlisting>&lt;properties&gt;

	&lt;!-- ************************************ --&gt;	
	&lt;!-- Serveur d'envoi de SMS et parametres --&gt;
	&lt;!-- ************************************ --&gt;
	
	&lt;sms_cust_id/&gt;			&lt;!-- L'id de client --&gt;
	&lt;sms_cert/&gt;			&lt;!-- Le certificat --&gt;
	&lt;sms_trust_store/&gt;		&lt;!-- Le trusted store --&gt;
	&lt;sms_store_password/&gt;		&lt;!-- Le mot de passe du certificat --&gt;
	&lt;sms_strategy/&gt;			&lt;!-- La strategie --&gt;
	&lt;sms_size/&gt;			&lt;!-- Nombre de caracteres que peut contenir un SMS --&gt;
	&lt;sms_from/&gt;			&lt;!-- Dit de qui ca vient (par exemple "De" ou "From") --&gt;
	&lt;sms_from_activation/&gt;		&lt;!-- Emetteur lors de l'envoi du code d'activation --&gt;
	&lt;sms_subject_activation/&gt;	&lt;!-- Sujet du message lors de l'envoi du code d'activation --&gt;
	&lt;sms_message_activation/&gt;	&lt;!-- Message lors de l'envoi du code d'activation (ce qui precede le code d'activation) --&gt;


	&lt;!-- ************************ --&gt;
	&lt;!-- Serveur d'envoi de mails --&gt;
	&lt;!-- ************************ --&gt;
	
	&lt;mail_url/&gt;		&lt;!-- URL du serveur smtp --&gt;


	&lt;!-- ************* --&gt;
	&lt;!-- Acces au LDAP --&gt;
	&lt;!-- ************* --&gt;
	
	&lt;ldapUrl/&gt;		&lt;!-- URL du serveur LDAP --&gt;
	&lt;loginLdap/&gt;		&lt;!-- Compte pour la lecture des attributs du telephone mobile --&gt;
	&lt;passwordLdap/&gt;		&lt;!-- Mot de passe d'acces --&gt;
	&lt;ldapGroups/&gt;		&lt;!-- Branche des groupes dans le LDAP --&gt;
	&lt;ldapPeople/&gt;		&lt;!-- Branche people dans le LDAP --&gt;
	&lt;filtreInstituts/&gt;	&lt;!-- Filtre permettant de retrouver les institus --&gt;
	&lt;filtreFormations/&gt;	&lt;!-- Filtre permettant de retrouver les differentes formations --&gt;

	&lt;!-- ********************************************** --&gt;
	&lt;!-- Attributs LDAP contenus dans le PersonDirs.xml --&gt;
	&lt;!-- ********************************************** --&gt;
	
	&lt;mobile_attribute/&gt;		&lt;!-- Attribut qui contient le numero de telephone d'une personne au format international. Par exemple +33 6 00 00 00 00 --&gt;
	&lt;contact_mode_attribute/&gt;	&lt;!-- Attribut qui contient le mode de contact choisi par l'utilisateur --&gt;
	&lt;mail_attribute/&gt;		&lt;!-- attribut qui contient le mail de l'utilisateur --&gt;
	&lt;display_name_attribute/&gt;	&lt;!-- Attribut qui contient le nom complet d'un user --&gt;

	&lt;!-- **************************** --&gt;
	&lt;!-- Fichier de logs pour les SMS --&gt;
	&lt;!-- **************************** --&gt;
	
	&lt;logFile/&gt;	&lt;!-- Chemin complet du fichier dans lequel on ecrit les logs d'envoi des SMS --&gt;

&lt;/properties&gt;</programlisting>Nous pouvons voir apparaître en caractères
          gras les options de configuration qui doivent être éditées par
          l'administrateur du portail.</para>

          <para>Voyons en détail ces différentes parties:</para>
        </section>

        <section>
          <title>Paramètres d'envoi de SMS</title>

          <variablelist>
            <varlistentry>
              <term>sms_cust_id</term>

              <listitem>
                <para>Votre custId qui vous a été fourni par FT.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sms_cert</term>

              <listitem>
                <para>Certificat client qui vous a été fourni par FT. Exemple:
                "keyStore.jks". Ce fichier doit être copié dans le dossier
                <filename>properties/SSL</filename>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sms_trust_store</term>

              <listitem>
                <para>Fichier pour la chaîne de confiance qui vous a été
                fourni par FT. Exemple: "trustStore.jks". Ce fichier doit être
                copié dans le dossier
                <filename>properties/SSL</filename>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sms_store_password</term>

              <listitem>
                <para>Le mot de passe du certificat.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sms_strategy</term>

              <listitem>
                <para>La stratégie France Telecom utilisée pour l'envoi des
                messages.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sms_size</term>

              <listitem>
                <para>Taille maximale pour un SMS (160 par défaut).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sms_from</term>

              <listitem>
                <para>Label qui permet de dire de qui vient le message. Par
                défaut "De", afin de construire le SMS "De John
                Doe.....".</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sms_from_activation</term>

              <listitem>
                <para>Lors de l'envoi du code d'activation à l'utilisateur, on
                précise de qui vient le message. Préciser donc ici par exemple
                le nom de votre université.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sms_subject_activation</term>

              <listitem>
                <para>Le sujet du message lors de l'envoi du code d'activation
                via SMS. Par défaut "Code d'activation".</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>sms_message_activation</term>

              <listitem>
                <para>La partie du corps du message qui précèdera le code lors
                de l'envoi du code d'activation. Par défaut "Votre code
                d'activation est".</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </section>

        <section>
          <title>Paramètres d'envoi de courriels</title>

          <para>Dans cette version, nous utilisons un serveur POP qui ne
          requiert pas d'authentification. Par la suite, nous verrons à
          utiliser le canal mailTo en mode servant.</para>

          <variablelist>
            <varlistentry>
              <term>mail_url</term>

              <listitem>
                <para>Adresse du serveur POP pour l'envoi du message en mode
                courriel.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </section>

        <section>
          <title>Accès au serveur LDAP</title>

          <variablelist>
            <varlistentry>
              <term>ldapUrl</term>

              <listitem>
                <para>L'url du serveur ldap. Typiquement cet attribut est de
                la forme ldap://ldap.univ.fr:389 </para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>loginLdap</term>

              <listitem>
                <para>DN du compte LDAP permettant de lire tous les attributs
                des utilisateurs cités dans la partie "Attributs
                uPortal".</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>passwordLdap</term>

              <listitem>
                <para>Mot de passe du compte cité précédemment.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>ldapGroups</term>

              <listitem>
                <para>Branche du LDAP contenant les groupes. Exemple
                "ou=groups,dc=univ,dc=fr"</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>ldapPeople</term>

              <listitem>
                <para>Branche du LDAP contenant les personnes. Exemple
                "ou=people,dc=univ,dc=fr"</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>filtreInstituts</term>

              <listitem>
                <para>Filtre permettant de retrouver la liste des instituts de
                l'université. Par exemple
                "(&amp;amp;(&amp;amp;(objectClass=uvhcGroup)(uvhcGroupeType=institut))(uvhcGroupeOrigine=APO))".
                Notez qu'il faut encoder le caractère "&amp;" en "&amp;amp;"
                dans le fichier de config.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>filtreFormations</term>

              <listitem>
                <para>Filtre permettant de retrouver la liste des formations
                de l'université. Par exemple
                "(&amp;amp;(&amp;amp;(objectClass=uvhcGroup)(uvhcGroupeType=codeEtape))(uvhcGroupeOrigine=APO))".</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </section>

        <section>
          <title>Attributs uPortal</title>

          <variablelist>
            <varlistentry>
              <term>mobile_attribute</term>

              <listitem>
                <para>Attribut contenant le numéro de cellulaire des
                utilisateurs.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <variablelist>
            <varlistentry>
              <term>contact_mode_attribute</term>

              <listitem>
                <para>Attribut de type string qui contient le mode de
                réception des messages.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <variablelist>
            <varlistentry>
              <term>mail_attribute</term>

              <listitem>
                <para>Contient l'adresse courriel des utilisateurs.</para>
              </listitem>
            </varlistentry>
          </variablelist>

          <variablelist>
            <varlistentry>
              <term>display_name_attribute</term>

              <listitem>
                <para>Contient le nom complet d'un utilisateur.</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </section>

        <section>
          <title>Paramètres de log</title>

          <variablelist>
            <varlistentry>
              <term>logFile</term>

              <listitem>
                <para>Afin de garder une trace du nombre de SMS envoyés par
                utilisateur avec la date d'envoi, nous générons un fichier de
                logs. Il est nécessaire de renseigner le chemin complet de ce
                fichier à cet endroit. Exemple "C:\sms.log"</para>
              </listitem>
            </varlistentry>
          </variablelist>
        </section>
      </section>
    </section>

    <section>
      <title>Déploiement du Canal</title>

      <para>Préparation du déploiement : modifier le fichier
      <filename>build.properties</filename> en fonction de la version de
      portail que vous utilisez. Lancez la commande</para>

      <para><command>ant deploy</command></para>

      <para>relative au fichier <filename>build.xml</filename> contenu dans le
      package.</para>

      <para>Lors de la publication, l'administrateur devra déclarer deux fois
      le canal avec des paramètres différents:</para>

      <itemizedlist>
        <listitem>
          <para>Pour l'accès en mode de configuration du mode de réception des
          messages, il faudra déclarer l'attribut
          <emphasis>channelMode</emphasis> avec la valeur
          <emphasis>profil</emphasis></para>
        </listitem>

        <listitem>
          <para>Pour l'accès en mode d'envoi des messages, il faudra déclarer
          l'attribut <emphasis>channelMode</emphasis> avec la valeur
          <emphasis>envoi</emphasis></para>
        </listitem>
      </itemizedlist>
    </section>
  </section>
</article>