Sommaire

Service SMS-U
	Université de Paris 1

	Manuel d'installation du Back Office

Installation du Back office

L'application de Back office packagée se trouve dans le dossier /dist du projet.
Dézippez le contenue de la distribution la plus récente de esup-smsuapi dans un répertoire de travail.
Le paramétrage suivant est à effectuer dans le dossier ainsi créé.

...

Le back office nécessite un serveur de base de donnée MySQL en version 5.

Création du schéma en base de donnée

Pour créer le schéma de base de donnée :

Se connecter au serveur mysql en tant qu'administrateur et saisir le mot de passe

mysql -u root -p

Créer un schéma nommé « smsuapi »

create database smsuapi ;

Initialisation des tables en base de données

...

est disponible sur github. Il est conseillé d'utiliser git pour télécharger les sources :

Bloc de code
git clone https://github.com/EsupPortail/

...

esup-smsu-api.

...

git

N'hésitez pas également à utiliser GIT en interne pour exploiter et maintenir à jour vos instances.

Vous pouvez aussi trouver des zip sur cette page : https://github.com/EsupPortail/esup-smsu-api/tags.

Paramétrage

– Ajout du premier super administrateur
INSERT INTO user_bo_smsu VALUES (1, 3, "admin");

Figure 1 : Fichier populate_tables_esup-smsu-api.sql
Il faut remplacer admin par le login de l'utilisateur qui sera le super administrateur.

A l'aide des scripts ant fournis avec le back office, créer les tables par la tache init-data

ant init-data

...

Vérification des tables en base de données

Pour vérifier que les étapes précédentes se sont correctement déroulées :

Se connecter à la base de donnée et saisir le mot de passe :

mysql -u root -p

Se placer dans le schéma smsuapi :

use smsuapi ;

Lister les tables présentes :

show tables ;

...

-------------------

...

Tables_in_smsuapi

...

account

...

application

...

b_user

...

b_user_admin

...

b_vers_mana

...

b_vers_mana_admin

...

blacklist

...

fonction

...

institution

...

role

...

role_composition

...

sms

...

statistic

...

user_bo_smsu

...

Configuration de l'application

Le back office se déploie en mode servlet.
Vérifier la configuration des fichiers Configurez les fichiers :

créez src/main/resources/properties/config.properties
- vérifier les informations de connexion à la base de donnée
- vérifier le chemin d'accès au fichier libmgs.properties
properties/libmgs.properties
- Pas de paramétrage à modifier à l'heure actuelle
build.properties
- Paramétrez le type de déploiement désiré. (servlet, protlet, quick-start ... voir documentation du framework : http://www.esup-portail.org/pages/viewpage.action?pageId=1867791^{Image Removed})

en s'inspirant de config.sample.properties

si vous utilisez git pour l'exploitation et la mise à jour, il est conseillé de faire

Bloc de code

ln -s config.sample.properties src/main/resources/properties/config.properties
git add src/main/resources/properties/config.properties
git commit -m 'utiliser config.sample.properties comme base de configuration'

pour les paramètres, cf paramètres généraux ci-dessous

src/main/resources/propertiesProperties/logging/log4j.properties
- Vérifier vérifier le chemin d'accès du fichier de log

Lancement de l'application

L'application se lance par la tache ant start si le mode quick-start est paramétré dans le fichier build.properties :

ant start

L'application peut être déployée dans un serveur d'applications existant, voir documentation du framework (http://www.esup-portail.org/pages/viewpage.action?pageId=1867791^{Image Removed})

...

Deux fichiers de propriété permettent aux exploitants de paramétrer le Back Office : un fichier pour les paramètres généraux de l'application (config.properties) et un fichier pour les paramètres lié au broker (libmgs.properties).

...

src/main/resources/properties/broker/broker.xml
- et aussi src/main/resources/properties/broker/olm/libmgs.properties si vous utilisez le broker OLM

Paramètres généraux

Voici la liste des paramètres disponibles disponibles :

Url d'accès à la base de
donnée
donnée :
Bloc de code
hibernate.connection.jdbc.url=jdbc:mysql://<host>

...

/smsuapi
Ce paramètre

...

définit l'url de la base de donnée du back office.
Login d'accès à la base de
donnée
donnée :
Bloc de code
hibernate.connection.jdbc.username=root
Ce paramètre

...

définit le login pour l'accès à la base de donnée du back office.
Mot de passe d'accès à la base de
donnée
donnée :
Bloc de code
hibernate.connection.jdbc.password=xxx
Ce paramètre

...

définit le mot de passe pour l'accès à la base de donnée du back office.
Mode d'accès à la base de
donnée
donnée :
Bloc de code
hibernate.useJndi=false
Défini le mode d'accès à la base de donnée du back office.
Nom du connecteur
OLM utilisé
utilisé :
Bloc de code
sms.connector

...

.name=

...

allmysms
Ce paramètre

...

Localisation du fichier de configuration de la libraire MGS :

sms.connector.olm.propertyFile=/an/example/libmgs.properties
Ce paramètre défini le chemin d'accès vers le fichier contenant la configuration de la librairie MGS.

Statut utilisé par OLM pour définir un envoi réussi :

sms.connector.olm.olmSentStatusCode=0
Ce paramètre défini la valeur du statut envoyée par les acquittements d'OLM définissant un SMS transmis avec succès.

Statut utilisé par OLM définissant un échec d'envoi:

sms.connector.olm.olmErrorStatusCode=1
Ce paramètre défini la valeur du statut envoyée par les acquittements d'OLM définissant une erreur lors de la transmission d'un SMS.

Valeur de la cause utilisée par OLM pour définir un échec d'envoi du à un numéro invalide:

sms.connector.olm.olmInvalidMSISDNCauseCode=10
Ce paramètre défini la valeur de la cause envoyée par les acquittements d'OLM définissant une erreur lors de la transmission d'un SMS du à un numéro invalide.

définit le nom du

...

broker utilisé. Les brokers disponibles sont "olm", "smsenvoi", "proxy" et "allmysms".

Active / désactive l'envoi effectif des
SMS
SMS :
Bloc de code
sms.connector.simulateSending=false
Ce paramètre sert à désactiver l'envoi effectif des messages au broker. Si à

...

« true » alors aucun message ne sera envoyé au broker.
Nombre maximum de jour de conservation des
SMS
SMS :
Bloc de code
purge.sms.seniorityDay=

...

180
Ce paramètre sert à définir la durée maximum (en jours) de conservation des SMS en base avant que ceux ci ne soient purgés.
Nombre maximum de jour de conservation des
statistiques
statistiques :
Bloc de code
purge.statistic.seniorityDay=

...

730
Ce paramètre sert à définir la durée maximum (en jours) de conservation des statistiques en base avant que ceux ci ne soient purgés. Ces statistiques sont utilisés pour la création des rapports consolidés.
La
localisation du fichier de configuration de quartz :

quartz.configFile.location=/an/example/smsuapi_quartz.properties
Ce paramètre défini le chemin d'accès vers le fichier de configuration de quartz.

La
cron expression utilisée par la tache de génération des statistiques :
Bloc de code
quartz.buildStatisticsTrigger.cronExpression=0 0 0 1 * ?
Ce paramètre

...

définit l'expression cron qui est utilisée pour planifier la tache qui génère les statistiques nécessaires aux relevés consolidés.
La cron expression utilisée par la tache de purge des sms :
Bloc de code
quartz.purgeSmsTrigger.cronExpression=0 0 3 1 * ?
Ce paramètre

...

définit l'expression cron qui est utilisée pour planifier la tache qui purge les SMS.

La cron expression utilisée par la tache de purge des statistiques :

quartz.purgeStatisticTrigger.cronExpression = 0 0 5 1 * ?
Ce paramètre défini l'expression cron qui est utilisée pour planifier la tache qui purge les statistiques.

...

Paramètres liés au broker

Les brokers disponibles sont "olm", "smsenvoi", "proxy" et "allmysms".

Broker allmysms

Voici la liste des paramètres disponibles :

Identifiant de l'application :

libmgs.smsuapi.sid=2421
L'identifiant unique de l'application (fourni par OLM)

Mode de fonctionnement de la librairie :

libmgs.smsuapi.mode=sgs
Spécifie le mode de fonctionnement de la librairie (texte, voix, fax ...)

Url utilisée pour l'envoi de SMS :

...

disponibles dans le fichier src/main/resources/properties/config.properties :

Utilisateur et mot de passe de connexion à allmysms.com (fourni par allmysms.com) :
Bloc de code
sms.connector.allmysms.account.login=xxx sms.connector.allmysms.account.apikey=xxx
Pour configurer le champ expéditeur d'un SMS. Attention, ce champ est limité : 11 caractères max et caractères alphanumériques+espace
Bloc de code
sms.connector.allmysms.from.mapJSON = { "": "Univ Xxxxxx", "compte1": "Foo" }
NB : pour avoir les accusés de réception, il faut configurer https://sms.

...

univ.fr/

...

esup-

...

smsuapi/backChannelAck dans le WebHook accusé de allmysms à l'url https://manager.allmysms.com/api

Broker OLM

Voici la liste des paramètres disponibles dans le fichier src/main/resources/properties/broker/olm/libmgs.properties :

Url utilisée pour le suivi des acquittements des SMS :

libmgs.smsuapi.mgs.notifUrl=http://sms.cvf.fr/cgi-bin/notifications.cgi^{Image Removed}
Défini l'url à utiliser pour suivre les acquittements des SMS.

Localisation du certificat :

Identifiant de l'application (fourni par OLM) :
Bloc de code
libmgs.smsuapi.sid=1234
Chemin d'accès du certificat utilisé pour communiquer avec OLM (fourni par OLM) :
Bloc de code

libmgs.smsuapi.https.keystore=/an/example/certificat.ks

...

Mot de passe du
certificat :
certificat (fourni par OLM) :
Bloc de code
libmgs.smsuapi.https.passwd=xxxxxxx

...

Type de
logger
logger :
Bloc de code
libmgs.smsuapi.log.type=file
Défini le type de logger utilisé par la librairie.
Fichier de
log
log :
Bloc de code
libmgs.smsuapi.log.file.path=/an/example/pushLibMGS.log
Défini le chemin d'accès du fichier de log utilisé par la librarie libMGS.
Timeout de
notification
notification :
Bloc de code
libmgs.smsuapi.advanced.notifTimeout=1
Défini la durée (en minute) avant que la connexion vers l'url de notification soit automatiquement fermée et ré-ouverte.

Timeout :

libmgs.smsuapi.timeout=15
Défini la durée (en seconde) du timeout.

...

Liste des paramètres :

Le driver a utiliser pour se connecter à la base de données :

org.quartz.dataSource.myDS.driver= org.gjt.mm.mysql.Driver
Défini le driver qui sera utilisé par quartz pour se connecter à la base de données.

L'adresse de la base de données :

org.quartz.dataSource.myDS.URL=jdbc:mysql://<host>/smsuapi
Défini l'adresse qui sera utilisée pour se connecter à la base de données.

Le login d'accès à la base de données :

org.quartz.dataSource.myDS.user = root
Défini le login a utiliser pour se connecter à la base de données.

Le mot de passe d'accès à la base de données :

org.quartz.dataSource.myDS.password = root
Défini le mot de passe a utiliser pour se connecter à la base de données

Le nombre maximum de connection à la bse de donées :

org.quartz.dataSource.myDS.maxConnections = 5
Défini le nombre de connections maximum qui peuvent être utilisées.
Les autres paramètres n'ont normalement pas à être modifiés, dans le cas contraire se référer à la documentation Quartz.

...

L'application de d'administration Back office packagée se trouve dans le dossier /dist du projet.
Dézippez le contenue de la distribution la plus récente de esup-smsuapiadmin dans un répertoire de travail.
Le paramétrage suivant est à effectuer dans le dossier ainsi créé.

...

L'administration du back office utilise la même base de données que celle du back office. Il n'y a donc pas de procédure d'installation de base de données pour l'administration du back office.

...

Configuration de l'application

Le back office se déploie en mode portlet.
Vérifier la configuration des fichiers :

properties/config.properties
build.properties
properties/logging/log4j.properties

Déploiement de l'application

L'application se déploie par la tache ant deploy :

ant deploy

...

...

Broker smsenvoi

Voici la liste des paramètres disponibles dans le fichier src/main/resources/properties/config.properties :

Utilisateur et mot de passe de connexion à smsenvoi.com (fourni par smsenvoi.com) :

Bloc de code
sms.connector.smsenvoi.account.email = smsu@univ-paris1.fr sms.connector.smsenvoi.account.apikey = xxx

Pour configurer le champ expéditeur d'un SMS. Attention, ce champ est limité : 10 caractères max et caractères alphanumériques+espace
Bloc de code
sms.connector.smsenvoi.from.mapJSON = { "": "Univ Xxxxxx", "compte1": "Foo" }
Intervalle en secondes de connexion à smsenvoi.com pour obtenir les statuts
Bloc de code
sms.connector.smsenvoi.acknoledgeStatus.repeatInterval=20
Pour obtenir le statut d'un SMS (En cours, Délivré, Numéro invalide...), le back office doit se connecter à smsenvoi.com à intervalle régulier.

Broker "proxy"

URL de back office SMS-U proxy

Bloc de code
sms.connector.proxy.ws.address=https://sms.univ-xxx.fr/

Utilisateur et mot de passe de connexion à smsenvoi.com (fourni par smsenvoi.com) :
Bloc de code
sms.connector.proxy.ws.username = xxx sms.connector.proxy.ws.password = xxx
Intervalle en secondes de connection au proxy pour obtenir les statuts
Bloc de code
sms.connector.proxy.acknoledgeStatus.repeatInterval=20
Pour obtenir le statut d'un SMS (En cours, Délivré, Numéro invalide...), le back office doit se connecter au back office "proxy" à intervalle régulier.

Création de la base de données

Le back office nécessite un serveur de base de données MySQL en version 5.

Création du schéma en base de donnée

Pour créer le schéma de base de donnée : se connecter au serveur mysql en tant qu'administrateur et saisir le mot de passe

Bloc de code

mysql -u root -p -e "create database smsuapi"
mysql -u root -p smsuapi < src/main/resources/database/create_tables.sql
mysql -u root -p smsuapi < src/main/resources/database/create_qrtz_tables_esup-smsuapi.sql

Nb : Aucune table ne doit être présente dans le schéma smsuapi au moment de l'exécution de cette commande sous peine d'échec.

Vérification des tables en base de données

Pour vérifier que les étapes précédentes se sont correctement déroulées : se connecter à la base de données et saisir le mot de passe :

Bloc de code
mysql -u root -p -e "show tables" smsuapi

La liste des tables doit apparaître de la manière suivante :

Bloc de code

+--------------------------+
| Tables_in_smsuapi        |
+--------------------------+
| QRTZ_BLOB_TRIGGERS       |
| QRTZ_CALENDARS           |
| QRTZ_CRON_TRIGGERS       |
| QRTZ_FIRED_TRIGGERS      |
| QRTZ_JOB_DETAILS         |
| QRTZ_JOB_LISTENERS       |
| QRTZ_LOCKS               |
| QRTZ_PAUSED_TRIGGER_GRPS |
| QRTZ_SCHEDULER_STATE     |
| QRTZ_SIMPLE_TRIGGERS     |
| QRTZ_TRIGGERS            |
| QRTZ_TRIGGER_LISTENERS   |
| account                  |
| application              |
| blacklist                |
| institution              |
| sms                      |
| statistic                |
+--------------------------+

Déploiement

Bloc de code
mvn package

puis copiez le war dans le répertoire webapps de tomcat.

ou si vous préférez vous pouvez utiliser ant en configurant préalablement le chemin de déploiement dans build.properties

Bloc de code
ant deploy

L'application peut être déployée dans un serveur d'applications existant, voir la documentation du framework esup-commons

Lancement de l'application

en test

L'application se lance par la tache

Bloc de code
ant jetty.run # or mvn jetty:run

en production

L'application se lance quand on lance le serveur tomcat.

Pour envoyer plus de 10000 SMS, il faut configurer le paramètre tomcat "maxParameterCount".

Les services REST d'esup-smsu-api sont synchrones : esup-smu-api ne répond que lorsque l'opération demandée est effectivement traitée. Aussi si une requête sur smsu-api correspond à demander à envoyer un sms à plusieurs milliers de numéros de téléphones, le temps de réponse peut être long. Il faut donc s'assurer qu'aucun timeout au niveau d'un éventuel reverse-proxy ne vienne perturber le bon renvoi de la réponse par esup-smus-api.

→ Sous apache, on positionnera un timeout sur le proxypass suffisamment conséquent : par exemple 1 heure et non 1 minute comme positionné par défaut.

Bloc de code
ProxyPass / ajp://localhost:8009/ retry=1 timeout=3600

Configuration sans esup-smsu-api-admin

La façon recommandée d'administrer esup-smsu-api est d'utiliser esup-smsu-api-admin.

Il est néanmoins possible de s'en passer, en modifiant directement la base de données smsu-api. Pour faire la configuration initiale à la main, vous pouvez faire :

Bloc de code

insert into institution (INS_LABEL) values ("monUniv");
insert into account (ACC_LABEL, ACC_QUOTA) values ("test", 100);
insert into application (INS_ID, ACC_ID, APP_NAME, APP_CERTIFCATE, APP_QUOTA) values (1, 1, "test", "leMotDePassePourAllerAvecLeUserTest", 20);

<Connector port="8082" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
emptySessionPath="true"/>

Figure 3 : Fichier server.xml
Ce paramètre permet à la servlet de téléchargement de fonctionner correctement.
Le reste du déploiement est conforme à un déploiement portlet dans le portail esup.

Intégration de l'applet au portail

La portlet d'administration du back office se déploie par le biais du gestionnaire de canaux.
La configuration utilisée est la suivante :
Image Removed
Figure 4 : Intégration de la portlet au portail

...

Un fichier de propriété permet aux exploitants de paramétrer l'administration du Back Office.
Voici la liste des paramètres disponibles :

Url d'accès à la base de donnée :

hibernate.connection.jdbc.url=jdbc:mysql://<host>:3306/smsuapi
Ce paramètre défini l'url de la base de donnée du back office

Login d'accès à la base de donnée :

hibernate.connection.jdbc.username=root
Ce paramètre défini le login pour l'accès à la base de donnée du back office

Mot de passe d'accès à la base de donnée :

hibernate.connection.jdbc.password=xxxx
Ce paramètre défini le mot de passe pour l'accès à la base de donnée du back office

Méthode d'accès à la base de donnée :

hibernate.useJndi=false
Défini le mode d'accès à la base de donnée du front office.

Le nom de l'attribut uid dans le portail :

auth.portal.uidAttribute=false
Défini le nom de l'attribut définissant l'uid.

L'url du serveur cas :

...

Pages enfant

Comparaison des versions

Ancienne version 1

Nouvelle version Actuel

Légende

Installation du Back office

Création du schéma en base de donnée

Initialisation des tables en base de données

Paramétrage

Vérification des tables en base de données

Configuration de l'application

Lancement de l'application

Paramètres généraux

Paramètres liés au broker

Broker allmysms

Broker OLM

Configuration de l'application

Déploiement de l'application

Broker smsenvoi

Broker "proxy"

Création de la base de données

Création du schéma en base de donnée

Vérification des tables en base de données

Déploiement

Lancement de l'application

en test

en production

Configuration sans esup-smsu-api-admin

Intégration de l'applet au portail

Pages enfant

Pages ESUP-SMS-U Manual d'installation du Back Office (esup-smsu-api) Historique de la page

Comparaison des versions

Ancienne version 1

Nouvelle version Actuel

Légende

Installation du Back office

Création du schéma en base de donnée

Initialisation des tables en base de données

Paramétrage

Vérification des tables en base de données

Configuration de l'application

Lancement de l'application

Paramètres généraux

Paramètres liés au broker

Broker allmysms

Broker OLM

Configuration de l'application

Déploiement de l'application

Broker smsenvoi

Broker "proxy"

Création de la base de données

Création du schéma en base de donnée

Vérification des tables en base de données

Déploiement

Lancement de l'application

en test

en production

Configuration sans esup-smsu-api-admin

Intégration de l'applet au portail

Pages
ESUP-SMS-U
Manual d'installation du Back Office (esup-smsu-api)

Historique de la page