Sommaire |
---|
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éé.
Installation de la base de donnée
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
Bloc de code |
---|
mysql -u root -p -e "create database smsuapi"
|
Un schéma nommé « smsuapi » est maintenant créé
Initialisation des tables en base de données
Dans le fichier properties/config.properties, renseignez les paramètres relatifs à la base de donnée.
...
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
Bloc de code |
---|
-- Ajout du premier super administrateur
INSERT INTO user_bo_smsu VALUES (1, 3, "admin");
|
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
Bloc de code |
---|
ant init-data
|
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.
Nb : L'application étant lancée durant cette phase il faut que la configuration de l'application soit correcte avant de lancer la tache ant (cf Configuration_de_l'application)
Nb : Dû à un manque dans les classes appelées par la tâche init-data, il se peut que la tâche « ne rende pas la main » à la fin de son exécution. Ceci n'a pas d'impact sur les opérations effectuées.
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 :
Bloc de code |
---|
mysql -u root -p smsuapi "show tables"
|
La liste des tables doit apparaître de la manière suivante :
Bloc de code |
---|
+--------------------------+
| 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 |
+--------------------------+
14 rows in set (0.00 sec)
|
Déploiement de l'application back office
...
Le back office se déploie en mode servlet.
Vérifier la configuration des Configurez les fichiers :
- créez src/main/resources/properties/config.properties en s'inspirant de config.sample.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, portlet, quick-start ... voir documentation du framework esup-commons)
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/properties/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 :
Bloc de code |
---|
ant start
|
L'application peut être déployée dans un serveur d'applications existant, voir la documentation du framework esup-commons
Paramétrage du Back Office
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 :
Url d'accès à la base de donnée :
Bloc de code hibernate.connection.jdbc.url=jdbc:mysql://<host>:3306/smsuapi
Ce paramètre
définidéfinit l'url de la base de donnée du back office.
Login d'accès à la base de donnée :
Bloc de code hibernate.connection.jdbc.username=root
Ce paramètre
définidé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 :
Bloc de code hibernate.connection.jdbc.password=xxx
Ce paramètre
définidé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 :
Bloc de code hibernate.useJndi=false
Défini le mode d'accès à la base de donnée du back office.
Nom du connecteur
OLMutilisé :
Bloc de code sms.connector.olm.name=smsuapiallmysms
Ce paramètre
définidéfinit le nom du
connecteur OLM utilisé par l'application. Ce nom doit être identique à celui que l'on trouve dans le fichier libmgs.properties et notamment dans le champ libmgs.< name>.sid.- Localisation du fichier de configuration de la libraire MGS :
Ce paramètre défini le chemin d'accès vers le fichier contenant la configuration de la librairie MGS.Bloc de code sms.connector.olm.propertyFile=/an/example/libmgs.properties
- Statut utilisé par OLM pour définir un envoi réussi :
Ce paramètre défini la valeur du statut envoyée par les acquittements d'OLM définissant un SMS transmis avec succès.Bloc de code sms.connector.olm.olmSentStatusCode=0
- Statut utilisé par OLM définissant un échec d'envoi:
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.Bloc de code sms.connector.olm.olmErrorStatusCode=1
- Valeur de la cause utilisée par OLM pour définir un échec d'envoi du à un numéro invalide:
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 invalideBloc de code sms.connector.olm.olmInvalidMSISDNCauseCode=10
broker utilisé. Les brokers disponibles sont "olm", "smsenvoi", "proxy" et "allmysms".
Active / désactive l'envoi effectif des 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 :
Bloc de code purge.sms.seniorityDay=90180
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 :
Bloc de code purge.statistic.seniorityDay=365730
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 :
Ce paramètre défini le chemin d'accès vers le fichier de configuration de quartz.LaBloc de code quartz.configFile.location=/an/example/smsuapi_quartz.properties
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éfinidé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éfinidé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 :
Ce paramètre défini l'expression cron qui est utilisée pour planifier la tache qui purge les statistiques.Bloc de code quartz.purgeStatisticTrigger.cronExpression=0 0 5 1 * ?
Paramètres lié au broker
Paramètres liés au broker
Les brokers disponibles sont "olm", "smsenvoi", "proxy" et "allmysms".
Broker allmysms
Voici la liste des paramètres 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
- Identifiant de l'application :
L'identifiant unique de l'application (fourni par OLM)Bloc de code libmgs.smsuapi.sid=2421
- Mode de fonctionnement de la librairie :
Spécifie le mode de fonctionnement de la librairie (texte, voix, fax ...)Bloc de code libmgs.smsuapi.mode=sgs
- Url utilisée pour l'envoi de SMS :
libmgs.smsuapi.mgs.messageUrl=https://sms.cvfuniv.fr/cgiesup-bin/messages.cgi Défini l'url à appeler pour envoyer des SMS.Url utilisée pour le suivi des acquittements des SMS smsuapi/backChannelAck dans le WebHook accusé de allmysms à l'url https://manager.allmysms.com/apiBloc de code
Broker OLM
Voici la liste des paramètres disponibles dans le fichier src/main/resources/properties/broker/olm/libmgs.properties :
Identifiant de l'application (fourni par OLM) :
Défini l'url à utiliser pour suivre les acquittements des SMS.Bloc de code libmgs.smsuapi.mgs.notifUrl=http://sms.cvf.fr/cgi-bin/notifications.cgi
sid=1234
Chemin d'accès du certificat utilisé pour communiquer avec OLM (fourni par OLM)
Localisation du certificat:
Défini le chemin d'accès jusqu'au certificat utilisé pour communiquer avec OLMBloc de code libmgs.smsuapi.https.keystore=/an/example/certificat.ks
Mot de passe du certificat (fourni par OLM) :
Défini le mot de passe du certificatBloc de code libmgs.smsuapi.https.passwd=xxxxxxx
Type de logger :
Bloc de code libmgs.smsuapi.log.type=file
Défini le type de logger utilisé par la librairie.
Fichier de 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 :
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 :
Défini la durée (en seconde) du timeout.Bloc de code libmgs.smsuapi.timeout=15
Paramètres lié à Quartz
Liste des paramètres :
- Le driver a utiliser pour se connecter à la base de données :
Défini le driver qui sera utilisé par quartz pour se connecter à la base de données.Bloc de code org.quartz.dataSource.myDS.driver= org.gjt.mm.mysql.Driver
- L'adresse de la base de données :
Défini l'adresse qui sera utilisée pour se connecter à la base de données.Bloc de code org.quartz.dataSource.myDS.URL=jdbc:mysql://<host>/smsuapi
- 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.
Installation de l'administration du Back office
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éé.
Installation de la base de donnée
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.
Déploiement de l'application d'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 :
Bloc de code |
---|
ant deploy
|
Ajouter l'application dans le contexte du serveur du portail par le biais du fichier server.xml
Bloc de code |
---|
<Server port="8007" shutdown="SHUTDOWN">
<!-- Global JNDI resources -->
<GlobalNamingResources>
...
...
<Context path="/esup-smsu-api-admin" docBase="N:/outils/esup-2.6-esup-2.0.5/Portail/webapps/esup-smsu-api-admin/" /> \\
</Host>
</Engine>
</Service>
</Server>
|
Il faut également modifier la configuration du connecteur http du portail, également par son fichier server.xml. il faut ajouter le paramètre emptySessionPath="true"
Bloc de code |
---|
<!-- Define a non-SSL HTTP/1.1 Connector on port 8080 -->
<Connector port="8082" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
emptySessionPath="true"/>
|
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 :
Figure 4 : Intégration de la portlet au portail
Paramétrage de l'administration du Back Office
Un fichier de propriété permet aux exploitants de paramétrer l'administration du Back Office.
Voici la liste des paramètres disponibles :
...
Bloc de code |
---|
hibernate.connection.jdbc.url=jdbc:mysql://<host>:3306/smsuapi
|
...
Bloc de code |
---|
hibernate.connection.jdbc.username=root
|
...
Bloc de code |
---|
hibernate.connection.jdbc.password=xxxx
|
...
Bloc de code |
---|
hibernate.useJndi=false
|
...
Bloc de code |
---|
auth.portal.uidAttribute=false
|
...
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); |
...
Bloc de code |
---|
cas.url=https://<host>:<port>/cas
|
...