Documentació de referència

Arquitectura tècnica del sistema d'informació

El sistema d’informació consta de dues aplicacions:

• Laravel (https://portal.gennews.upc.edu)

• Mautic (https://gennews.upc.edu/xxxx)

El Laravel s’utilitza per implementar un portal de gestió centralitzada i de control dels diferents espais Mautic. El Mautic es troba en configuració multiinstància, de manera que només hi ha una còpia del codi font de l’aplicació, tot i que hi ha moltes instàncies Mautic.

El nombre d’instàncies Mautic és variable i es crearan sota demanda del client. Per fer la solució escalable i fàcilment mantenible, s’ha desenvolupat un sistema de configuració dinàmica del Mautic, de manera que les instàncies consten de certs recursos.

Recursos de les instàncies

• El fitxers de l’aplicació, compartits per totes les instàncies. Són únics i només es modifiquen en actualitzar el Mautic.

• Una base de dades MySQL per instància.

• Un directori de dades per instància.

Requisits de la sol·lució multi-instància de Mautic

• Els URL d’accés web són del tipus: http://servidor.domini.cat/nommautic.

• Els noms de les bases de dades MySQL acaben en números consecutius: mautic1, mautic2, mautic3, ....

• Existeix un fitxer que conté totes les relacions URL - base de dades (nommautic - mauticxx) que serveix per determinar la instància que es carrega.

• Els directoris de dades de les instàncies es troben tots dins del mateix directori pare i tenen el mateix nom que la base de dades: mautic1, mautic2, …

Estructura de directoris

/var/www/laravel/ -> Fitxers del Laravel

/var/www/laravel/public/ -> Directori de publicació del Laravel

/var/www/mautic/ -> Fitxers del Mautic

/var/www/mautic_sites/ -> Directori de publicació del Mautic

/var/www/mauticdata/mauticxx/ -> Fitxers de la instància xx del Mautic

El directori mautic_sites conté enllaços simbòlics que apunten al directori del codi font del Mautic. N’hi ha un per cada instància i es fa servir per a l’accés web.

Es necessiten dos dominis, un per al Laravel i un altre per al Mautic. El motiu és que el Laravel requereix un domini propi.

Ocupació de la base de dades

El Laravel requereix una base de dades amb una ocupació de fins a 50 MB. El Mautic requereix una base de dades per instància amb una capacitat gran i difícil d’estimar a priori. L’ocupació varia amb segons les dades següents:

• La instal·lació buida consumeix 10 MB

• Per a cada missatge que s’envia, l’increment mig d’ocupació és de 18 MB. En el cas del pilot, s’han enviat 11 butlletins a uns 5400 contactes, cosa que ha suposat una ocupació de la base de dades de prop d’1 GB.

Connexió amb altres serveis

• LDAP

• myList

• Gauss 

Funcionament del portal 

Accés

L'accés es fa exclusivament via web i cal entrar amb usuari i contrasenya per poder utilitzar qualsevol de les seves funcionalitats. Només hi ha dos perfils d'accés definits (Gestor d'instàncies Mautic i Administrador), encara que l’aplicació en suporta més. El perfil d’administrador està restringit al personal d’UPCnet / IThinkUPC que gestiona l’aplicació i als membres de l’ATIC que han de resoldre tiquets. La resta d’usuaris han de tenir perfil gestor.

En entrar a l’aplicació s’accedeix a la llista d’instàncies. Els administradors veuen totes les instàncies, mentre que els gestors només veuen les instàncies a les que estan associats (normalment, una).

A la capçalera de les pàgines hi ha un menú per accedir a diverses opcions. Els gestors només tenen enllaços a la llista d’instàncies, a l’edició de les seves dades i a sortir de l’aplicació.

Usuaris

Els usuaris poden canviar algunes de les seves dades: Nom, nom d’usuari, adreça i contrasenya. La contrasenya només és necessària pels usuaris que no existeixen a l’LDAP. Si un usuari LDAP canvia la seva contrasenya, el canvi només afecta al portal i es perdrà la propera vegada que entri amb les credencials LDAP. Per tant, els usuaris LDAP haurien d’entrar sempre amb les credencials LDAP.

Els administradors poden canviar el nom d’usuari. Això està pensat per poder corregir errors en la creació d’usuaris però, a la pràctica, suposa la possibilitat de traspassar la capacitat de gestió d’una instància d’un usuari a un altre, ja que si es canvia el nom d’usuari pel d’una altra persona que existeixi a l’LDAP, aquesta segona persona serà qui podrà gestionar la instància al portal.

 

Els usuaris no tindran accés a cap instància si no tenen assignats un rol i una instància. Normalment, en el moment de crear un usuari encara no existirà la instància. El que s’ha de fer és, després de crear la instància, editar l’usuari i assignar-li la instància.

Alta d’instàncies

Crear l'usuari si no existeix

Anar a la llista d’usuaris i mirar si l’usuari existeix. En cas afirmatiu, no cal fer res. En cas contrari, cal clicar al botó Afegeix un usuari i emplenar i trametre el formulari que apareixerà. Les dades que cal introduir són: Nom, nom d’usuari i adreça de correu. Normalment el nom d’usuari correspondrà a un usuari LDAP; si no és així, cal introduir una contrasenya (dues vegades) i proporcionar-la a l’usuari, o no podrà entrar.

Crear la instància

Cal anar a la llista d’instàncies i clicar a Afegeix una instància. Les dades que s’han d’introduir són:

• Nom: El text que apareixerà a la llista d’instàncies i a la capçalera del Mautic

• Descripció: Text descriptiu de la instància. És opcional perquè no es mostra enlloc.

• URL: Paraula final que definirà l’adreça d’accés al Mautic des del navegador. IMPORTANT: No es podrà canviar més endavant, així que cal assegurar-se abans de trametre el formulari. En cas que es produeixi un error i calgui canviar-la, caldrà escalar-ho als desenvolupadors de l’aplicació.

• Estat: Posar-lo sempre a Actiu per fer l’alta.

• Data d’expiració: Introduir una data amb el format AAAA-MM-DD HH:MM (Exemple: 2019-02-01 08:00). S’ha de posar la data actual + 1 any.

• Nom del remitent dels missatges de correu: Nom del remitent que figurarà en els missatges de correu electrònic que enviï el Mautic.

• Adreça del remitent dels missatges de correu: Adreça del remitent que figurarà en els missatges de correu electrònic que enviï el Mautic.

• Usuari de la instància: Seleccionar l’usuari que s’ha creat en el punt 1. IMPORTANT: Aquest usuari es crearà automàticament amb rol gestor al Mautic. Si no es tria l’usuari correcte, caldrà corregir-ho posteriorment al Mautic.

Quan estiguin totes les dades introduïdes, clicar a Crea la instància.

El procés de creació pot durar uns minuts. Quan finalitzi ha d’aparèixer un missatge indicant que el procés s’ha completat correctament. En cas que aparegui qualsevol error, cal copiar el missatge d’error i escalar-ho als desenvolupadors de l’aplicació.

Crear segments

A la llista d’instàncies, clicar a la icona Mostra els segments corresponent a la instància (segona icona). Tot seguit, clicar a Afegeix un segment al Mautic i introduir les dades següents (cal crear un segment per cada llista):

• Nom: Nom o descripció de la llista. Exemple: Personal d’Administració i Serveis

• Filtre: adreça de correu electrònic de la llista. Exemple: pas@llistes.upc.edu

Clicar a Crea el segment.

En cas que es produeixin errors en la creació dels segments o que calgui editar-ne o esborrar-ne algun, caldrà fer-ho des del Mautic.

Assignar la instància a l’usuari

A la llista d’usuaris, editar l’usuari que s’ha indicat en crear la instància i marcar-li la casella corresponent a la instància que s’acaba de crear.

Llista d’instàncies

La taula d’instàncies té tres columnes que mostren el següent:

• Nom: Mostra l’URL d’accés al Mautic, que inclou un enllaç

• Contactes: Data de la darrera vegada que es varen actualitzar els contactes del Mautic. Nota: Cada nit s’haurien d’actualitzar a partir de les llistes associades als segments.

• Accions: Mostren enllaços d’accés a altres seccions o permeten realitzar canvis directament. Els gestors només tenen accés a les primeres dues icones, mentre que els administradors en veuen vuit.

• Edita la instància: Permet accedir al formulari des d’on es poden canviar algunes dades associades a cada instància.

• Mostra els segments: Permet accedir al llistat de segments, des d’on els administradors en poden crear de nous i actualitzar els existents a partir dels contactes.

• Actualitza els contactes i els segments: Actualitza els contactes del Mautic a partir dels membres de les llistes associades als segments. Després d’actualitzar els contactes, actualitza els segments, operació que consisteix en treure dels segments els contactes esborrats i afegir els nous. Nota: Aquesta acció s’hauria de realitzar automàticament cada nit. En cas que no s’hagi fet, es pot fer manualment clicant en aquesta icona.

• Mostra els contactes: Permet accedir a la llista de contactes existents en el Mautic. Nota: Un dels requisits del servei és que els gestors no poden tenir accés a la llista de contactes.

• Mostra els usuaris: Permet accedir a la llista d’usuaris existents en el Mautic. No mostra els usuaris del portal.

• Mostra els butlletins: Permet accedir a la llista de butlletins (Newsletters) enviats des del Mautic.

• Esborra la instància: Esborra el registre de la instància al portal. No esborra la instància (base de dades i fitxers), tot i que queda inaccessible.

• Desactiva la instància: Deixa la instància inaccessible. Aquesta icona és un commutador, de manera que es pot tornar a clicar per deixar-la accessible de nou.

Usuaris de la instància

A la pantalla d’edició d’una instància es poden afegir usuaris a la instància. Això significa que aquests usuaris del portal podran veure la instància al portal, però no se’ls hi crearà automàticament cap usuari al Mautic. L’únic usuari que es crea automàticament al Mautic és el que se selecciona en el moment de crear la instància.

Permisos i rols

El portal incorpora una configuració de permisos i rols acordada amb el client, per tant, no s’hi han de fer canvis. Si un gestor d’instància vol tenir accés a més opcions, s’ha d’escalar la sol·licitud.

Descripció funcional del Mautic

Les instàncies Mautic es construeixen a partir d’una plantilla per tal de proveir una configuració única i d’acord amb les necessitats del client.

Els punts destacats aquesta plantilla són:

• Existència de dos rols: Administrador i Gestor. El primer reservat pels gestors del servei d’UPCnet / IThinkUPC i per a l’ATIC i el segon destinat als usuaris.

• Els administradors tenen accés a totes les opcions i continguts, mentre que els gestors només tenen accés a les funcionalitats de creació i enviament de butlletins.

• Existeixen dos administradors: admin.upcnet i admin.ws. El primer destinat a les persones i el segon a l’accés via API des del portal per tal de dur a terme les sincronitzacions de contactes. Els continguts generats automàticament pertanyen a aquest usuari.

• Els gestors poden crear butlletins a partir de plantilles, assignar segments als butlletins i enviar-los. Els enviaments es posen en una cua i s’envien en horari nocturn.

• S’ha afegit un Custom field anomenat Llista d’origen que conté els noms de les llistes a les que pertany el contacte.

Notes de funcionament

Un contacte pot pertànyer a més d’un segment. La pertinença a un grup es controla mitjançant un conjunt de regles lògiques. Per exemple: tots els contactes que tinguin el camp “Llista origen” que contingui pas@llistes.upc.edu o tots els contactes que tinguin l’adreça de correu acabada en “@ithinkupc.com”.

Els contactes i els segments tenen un propietari. Es pot fer que els usuaris només vegin els contactes dels que són propietaris. En el cas dels segments, sempre es veuen tots (es veu el nom i el nombre de contactes), però es pot fer que només es puguin editar els segments propis. Si entra a un segment propi que conté usuaris d’altres, es pot fer que només vegin els usuaris propis, encara que el segment en tingui més.

Es pot fer que no es puguin ni crear, ni editar, ni esborrar, ni importar, ni exportar usuaris.

No es poden crear ni grups de contactes ni grups de segments. L’única manera de que convisquin segments i contactes de diferents col·lectius tot mantenint-los aïllats, consisteix en utilitzar usuaris genèrics (compartits per vàries persones) i fer que els contactes i els segments pertanyin a aquests usuaris.

Un missatge es pot enviar a tots els segments que es vulgui. Si un contacte per pertany a més d’un segment, només se li envia un missatge.

Els missatges de correu es poden posar en una cua i començar-se a enviar mitjançant un cron.

En enviar un missatge, el “From name” i el “Reply to” s’agafen dels paràmetres del missatge. En canvi, el “From address”, tot i poder-se definir al missatge, s’agafa sempre el del sistema. Per tant, cal que el sendmail tingui configurada una adreça de no-reply.

En cas que el el “From name” i el “Reply to” no estiguin indicats en el missatge, s’agafen els indicats a la configuració general del Mautic.

Mecanisme de desubscripció

Quan es crea la plantilla pel missatge (el tema), es pot incloure opcionalment un enllaç de desubscripció. Si s'inclou aquest enllaç, els usuaris es poden desubscriure. Si no s'inclou aquest enllaç, no ho poden fer (Nota: l'enllaç de desubscripció no es pot endevinar perquè conté un número aleatori).

Quan un usuari clica a aquest enllaç i es desubscriu, ja no se li envia cap més missatge des d'aquell Mautic, a no ser que se subscrigui de nou. Cal dir que és possible, des del portal, esborrar les desubscripcions.

Més informació

• https://mautic.org/docs/en/emails/index.html