Nel corso di quest'articolo vedremo come sia semplice e immediato utilizzare i Web Services di Liferay per importare una lista di utenti da un foglio Excel.

1. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
Liferay
Web
Services
Come
importare
utenti
da
un
foglio
Excel
Lavorando
in
contesti
d'integrazione,
capita
spesso
e
volentieri
di
dover
compiere
operazioni
d'integrazione
dati
sfruttando
tecnologie
che
ruotano
nell'intorno
dei
Servizi
Web.
L'articolo
prende
spunto
da
un
recente
caso
d'integrazione
che
vede
coinvolto
un
sistema
di
ERP1
(Enterprise
Resource
Planning)
e
il
nostro
Liferay.
L'integrazione
prevede
l'importazione
dei
"Clienti"
dall'ERP
a
Liferay,
e
su
quest'ultimo
possiamo
identificare
i
clienti
come
utenti.
Per
la
stesura
dell'articolo
ho
eliminato
di
proposito
il
primo
e
secondo
elemento
dell'integrazione,
rispettivamente,
l'ERP
e
l'ESB2
(Enterprise
Service
Bus).
L'ERP
la
sorgente
dati
e
l'ESB
"orchestratore"
dei
Servizi
Web.
L'azione
d'eliminazione
è
giustificata
dal
fatto
che
vorrei
focalizzare
l'attenzione
sui
Servizi
Web
di
Liferay,
per
cui
il
nostro
schema
di
riferimento
è
quello
mostrato
nella
figura
a
seguire.
Figura
1
Macro
processo
d’importazione
utenti
da
foglio
Excel.
Come
da
Figura
1,
la
fonte
dei
dati
è
un
foglio
Excel
da
cui
leggere
i
record
da
importare
su
Liferay
come
utenti.
Il
record
ha
una
struttura
del
tipo
indicata
a
seguire:
• Title
• Screen
Name
• Email
• First
Name
• Middle
Name
Enterprise
Resource
Planning
(letteralmente
"pianificazione
delle
risorse
d'impresa",
spesso
abbreviato
in
ERP)
è
un
sistema
di
gestione,
chiamato
in
informatica
sistema
informativo,
che
integra
tutti
i
processi
di
business
rilevanti
di
2
Un
Enterprise
Service
Bus
gestione
magazzino,
contabilità
etc.)
che
fornisce
servizi
di
supporto
ad
architetture
SOA
un'azienda
(vendite,
acquisti,
(ESB)
è
un'infrastruttura
software
complesse.
Un
ESB
si
basa
su
sistemi
disparati,
interconnessi
con
tecnologie
eterogenee,
e
fornisce
in
maniera
consistente
servizi
di
orchestration,
sicurezza,
messaggistica,
routing
intelligente
e
trasformazioni,
agendo
come
una
dorsale
attraverso
la
quale
viaggiano
servizi
software
e
componenti
applicativi.
1
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
1

2. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
•
•
•
•
•
•
•
•
•
Last
Name
Gender
Birthday
(deve
essere
di
tipo
data)
Job
Title
Site
Name
(lista
dei
site
separati
da
virgola)
Role
Name
(lista
dei
ruoli
separati
da
virgola)
Language
(codifica
della
lingua:
esempio
it_IT,
en_EN)
Time
Zone
(codifica
del
Time
Zone:
esempio:
UTC)
AccountId
(identificativo
del
sistema
sorgente)
La
struttura
del
record
ha
tre
attributi
che
ritengo
rilevanti,
il
Site
Name,
Role
Name
e
AccountId.
Il
Site
Name
contiene
la
lista
dei
site (Liferay Inc., 2013)
(può
essere
anche
una
lista
vuota)
a
cui
il
nuovo
utente
deve
essere
associato,
il
Role
Name
contiene
la
lista
di
ruoli
(Liferay Inc., 2013)
(può
essere
anche
una
lista
vuota)
da
assegnare
al
nuovo
utente,
l'AccountId
contiene
l'identificativo
univoco
del
record
sul
sistema
che
ha
fornito
i
dati.
L'AccountId,
lato
Liferay
è
un
attributo
di
tipo
custom
(Liferay Inc., 2013)
sull'entità
utente.
I
diagrammi
come
sempre
aiutano
la
comprensione
e
i
flow
chart
fanno
al
caso
nostro.
I
diagrammi
a
seguire
mostrano
il
processo
d'importazione
nella
sua
globalità.
Figura
2
Processo
d'importazione
utenti
da
Excel
a
Liferay.
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
2

3. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
Figura
3
Processo
di
lettura
e
verifica
dati
da
importare.
Figura
4
Processo
che
esegue
l'import
effettivo
su
Liferay
tramite
chiamate
ai
WS.
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
3

4. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
Per
l'operazione
d'importazione
degli
utenti
da
file
Excel
a
Liferay,
faremo
uso
dell'API 3
(Application
Programming
Interface)
di
Liferay
e
in
particolar
modo
dei
servizi
SOAP4
(Simple
Object
Access
Protocol)
su
HTTP.
Per
chi
non
fosse
avvezzo
con
quest'area
di
Liferay
consiglio
di
leggere
nell'ordine
i
seguenti
documenti:
• Liferay
APIs
(Liferay Inc., 2013)
• Service
Security
Layers
(Liferay Inc., 2013)
• SOAP
Web
Services
(Liferay Inc., 2013)
Per
l'obiettivo
prefissato,
i
servizi
di
nostro
interesse
sono:
• Portal_UserService:
Servizio
utilizzato
per
inserire
il
nuovo
l'utente;
• Portal_CompanyService:
Servizio
utilizzato
per
ricavare
la
company
id;
• Portal_GroupService:
Servizio
utilizzato
per
verificare
l'esistenza
del
site;
• Portal_RoleService:
Servizio
utilizzato
per
verificare
l'esistenza
del
ruolo.
E'
possibile
vedere
tutti
gli
end-­‐point
dei
servizi
puntando
il
proprio
browser
all'indirizzo
http://[hostname|FQDN]:[port]/api/secure/axis
Figura
5
Liferay
API
utilizzate
e
dettaglio
delle
operazioni
chiamate.
Fino
a
questo
punto
abbiamo
avuto
modo
di
spiegare
(a
parole)
come
sia
possibile
portare
a
termine
con
semplicità
operazioni
d'integrazione
sfruttando
i
servizi
web
esposti
da
Liferay.
Spostando
l'attenzione
sul
pratico,
implementare
quanto
esposto
fino
a
questo
momento,
è
molto
semplice
utilizzando
i
seguenti
elementi
software:
• Apache
POI:
Utilizzato
per
leggere
la
lista
degli
utenti
da
importare
da
un
foglio
Excel
(The Apache Software Foundation, 2013);
• Liferay
Portal
Client
(v.
6.1.1):
Utilizzato
per
interagire
con
i
servizi
SOAP
esposti
da
Liferay.
Con
Application
Programming
Interface
(in
acronimo
API,
in
italiano
Interfaccia
di
Programmazione
di
un'Applicazione),
in
informatica,
si
indica
ogni
insieme
di
procedure
disponibili
al
programmatore,
di
solito
raggruppate
a
formare
un
set
di
strumenti
specifici
per
l'espletamento
di
un
determinato
compito
all'interno
di
un
certo
programma.
4
In
informatica
SOAP
(inizialmente
acronimo
di
Simple
Object
Access
Protocol)
è
un
protocollo
leggero
per
lo
scambio
di
messaggi
tra
componenti
software,
tipicamente
nella
forma
di
componentistica
software.
La
parola
object
manifesta
che
l'uso
del
protocollo
dovrebbe
effettuarsi
secondo
il
paradigma
della
programmazione
orientata
agli
oggetti.
3
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
4

5. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
Ogni
record
letto
dal
foglio
Excel
rappresenta
il
nuovo
utente
che
in
fase
d'importazione
sarà
mappato
su
un
oggetto
del
tipo
visibile
in
Figura
6.
Quest’
oggetto
farà
poi
parte
di
una
lista
di
oggetti
dello
stesso
tipo,
l'insieme
di
questi
oggetti
saranno
poi
inseriti
effettivamente
su
Liferay.
Figura
6
Modello
che
rappresenta
l'utente
letto
dal
file
Excel
e
che
sarà
poi
inserito
su
Liferay.
Fino
a
questo
momento
è
stata
trattata
una
soluzione
al
“problema
d’importazione”,
da
questo
punto
in
avanti
vedremo
invece
l’aspetto
pratico.
Il
progetto
d’esempio
che
implementa
la
nostra
soluzione
d’importazione
utenti
è
disponibile
in
forma
pubblica
sul
repository
(GitHub5)
ImportUsersLiferayViaWS
(Musarra, 2013).
Il
progetto
è
basato
su
Maven6
e
testato
sulla
versione
6.1
di
Liferay
Community
Edition
(che
potrebbe
comunque
funzionare
anche
sull’edizione
Enterprise).
I
task
eseguiti
dal
programma
d’importazione
sono
i
seguenti:
• Login
su
Liferay
con
utenza
di
tipo
amministrativo;
• Recupero
della
CompanyId
su
base
virtual
host;
• Lettura
del
file
Excel
e
per
ogni
riga
che
identifica
l’utente:
o Verifica
formale
di
alcuni
campi
(esempio:
Screen
Name
e
Email
non
possono
essere
vuoti);
o Verifica
dell’esistenza
del
ruolo
specificato
da
assegnare
all’utente;
o Verifica
dell’esistenza
del
site
o
gruppo
a
cui
assegnare
l’utente;
• Creazione
degli
utenti
non
scartati.
GitHub
è
un
servizio
web
di
hosting
per
lo
sviluppo
di
progetti
software
(e
non
solo)
che
usa
il
sistema
di
controllo
di
versione
Git.
GitHub
offre
diversi
piani
per
repository
privati
a
pagamento
ma
anche
piani
gratuiti
molto
utilizzati
per
lo
sviluppo
di
progetti
open-­‐source.
6
In
informatica
Maven
è
un
software
usato
principalmente
per
la
gestione
di
progetti
Java
e
build
automation.
Per
funzionalità
è
similare
ad
Apache
Ant,
ma
basato
su
concetti
differenti.
5
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
5

6. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
A
questo
punto
vediamo
quali
sono
i
passi
necessari
per
eseguire
con
successo
la
prima
importazione
di
test:
• Clonazione
del
repository
del
progetto;
• Build
del
progetto
via
Maven;
• Esecuzione
del
programma
d’importazione.
Dopo
la
compilazione
del
progetto
(vedi
Listato
1)
il
programma
d’importazione
sarà
reso
disponibile
all’interno
della
directory
target,
figlia
della
directory
ImportUsersLiferayViaWS.
Gli
“eseguibili”
java
generati
a
fronte
della
compilazione
sono
due:
• import-­‐users-­‐liferay-­‐via-­‐ws-­‐0.0.1-­‐SNAPSHOT.jar
• import-­‐users-­‐liferay-­‐via-­‐ws-­‐0.0.1-­‐SNAPSHOT-­‐jar-­‐with-­‐
dependencies.jar
Il
primo
jar
non
contiene
le
dipendenze
(axis,
sax,
etc…)
mentre
il
secondo
contiene
tutte
le
dipendenze
necessarie
a
runtime,
quest’ultimo
è
ovviamente
di
dimensioni
più
grandi
ma
sicuramente
più
comodo
da
utilizzare.
Il
primo
e
il
secondo
listato
mostrano
esattamente
l’esecuzione
dei
passi
visti
in
precedenza
(CBE7).
$
git
clone
git://github.com/amusarra/ImportUsersLiferayViaWS.git
$
cd
ImportUsersLiferayViaWS
$
mvn
package
Listato
1
Clonazione
del
repository
e
compilazione
del
progetto.
$
java
-­‐Dusername=admin
-­‐Dpassword=admin
-­‐jar
-­‐
DfileToImport=src/main/resources/users_for_import_liferay.xlsx
target/import-­‐users-­‐liferay-­‐via-­‐ws-­‐0.0.1-­‐
SNAPSHOT-­‐jar-­‐with-­‐dependencies.jar
Listato
2
Esecuzione
del
programma
d'importazione.
Quanto
mostrato
nel
Listato
3
evidenzia
l’avanzamento
(dei
vari
task)
del
programma
d’importazione.
2013-­‐11-­‐14
13:48:13,892
[main]
INFO
ImportUsersToLiferay
-­‐
Try
lookup
User
Service
by
End
Point:
http://admin:admin@localhost:8080/api/secure/axis/Portal_UserService...
2013-­‐11-­‐14
13:48:14,343
[main]
INFO
ImportUsersToLiferay
-­‐
Try
lookup
Company
Service
by
End
Point:
http://admin:admin@localhost:8080/api/secure/axis/Portal_CompanyService...
2013-­‐11-­‐14
13:48:14,581
[main]
INFO
ImportUsersToLiferay
-­‐
Company
ID
1
2013-­‐11-­‐14
13:48:14,582
[main]
INFO
ImportUsersToLiferay
-­‐
Get
UserID...
2013-­‐11-­‐14
13:48:14,619
[main]
INFO
ImportUsersToLiferay
-­‐
UserId
for
user
named
admin
is
10382
2013-­‐11-­‐14
13:48:15,517
[main]
INFO
ImportUsersToLiferay
-­‐
Add
user
object
UserToImport
[accountId=7477234f-­‐34f7-­‐76bf-­‐b
2013-­‐11-­‐14
13:48:15,533
[main]
WARN
ImportUsersToLiferay
-­‐
The
username
attribute
can
not
be
null
for
rowId
5
2013-­‐11-­‐14
13:48:15,534
[main]
INFO
ImportUsersToLiferay
-­‐
User
ready
for
import
to
liferay
is
4
2013-­‐11-­‐14
13:48:15,534
[main]
INFO
ImportUsersToLiferay
-­‐
Starting
import
users...
2013-­‐11-­‐14
13:48:15,557
[main]
INFO
ImportUsersToLiferay
-­‐
User
cmontagno
added
on
liferay.
2013-­‐11-­‐14
13:48:15,558
[main]
INFO
ImportUsersToLiferay
-­‐
Import
users
to
liferay
completed
successfully
Listato
3
Log
che
mostra
l'attività
del
programma
d'importazione.
Il
programma
d’importazione
per
impostazione
predefinita
(senza
specificare
nessun
parametro)
tenta
di
connettersi
ai
Web
Services
della
propria
installazione
locale
di
Liferay.
I
parametri
(a
linea
di
comando)
supportati
sono
i
seguenti:
7
Cloning,
Building
and
Execution
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
6

7. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
•
•
•
•
•
•
-­‐DliferayAddressProtocol:
Imposta
il
protocollo
http
o
https
(valore
predefinito:
http);
-­‐DliferayAddressPort:
Imposta
la
porta
TCP
(valore
predefinito:
8080);
-­‐DliferayAddressFQDN:
Imposta
il
nome
host
o
FQDN
(valore
predefinito:
localhost);
-­‐Dusername:
Imposta
la
username
dell’utente
di
tipo
amministrativo
(valore
predefinito:
test);
-­‐Dpassword:
Imposta
la
password
(valore
predefinito:
test);
-­‐DfileToImport:
Imposta
il
path
completo
del
file
Excel
contenente
la
lista
degli
utenti.
I
primi
tre
parametri
di
configurazione
devono
essere
specificati
insieme,
in
caso
contrario
nessuno
dei
tre
sarà
tenuto
in
considerazione.
All’avvio
del
programma
d’importazione
è
possibile
cadere
in
alcuni
comuni
errori
“fatali”
che
fermano
l’esecuzione
del
programma.
Gli
errori
sono
mostrati
in
console
e
in
genere
sono:
• org.apache.axis.AxisFault(401)Unauthorized:
Accade
perché
le
credenziali
di
accesso
a
Liferay
non
sono
corrette;
• org.apache.axis.AxisFault(403)Forbidden:
Accade
perché
che
le
impostazioni
dei
Web
Services
di
Liferay
non
sono
corrette;
• org.apache.axis.AxisFault;
nested
exception
is:
java.net.ConnectException:
Connection
refused:
Accade
perché
le
impostazioni
di
connessione
non
sono
corrette,
per
questo
è
consigliabile
accertare
che
i
servizi
di
Liferay
siano
operativi
e
per
ultimo
che
le
macchine
(client
e
server)
siano
nelle
condizioni
di
poter
comunicare;
• No
such
file
or
directory:
Accade
perché
il
path
del
file
Excel
non
è
corretto
o
accessibile
dal
programma
d’importazione.
L’esecuzione
del
programma
d’importazione
vista
in
precedenza,
utilizza
un
file
Excel
di
esempio
presente
all’interno
del
progetto.
Utilizzando
quindi
il
file
Excel
di
esempio
per
un
vostro
test
d’importazione,
dovreste
ritrovare
sulla
vostra
istanza
di
Liferay,
quattro
nuovi
utenti.
Nelle
figure
a
seguire
è
mostrato
tramite
screenshot 8
il
risultato
dell’importazione
utilizzando
il
file
Excel
di
esempio.
Il
termine
inglese
screenshot
(da
screen,
schermo,
e
shot,
scatto
fotografico),
in
italiano
schermata,
indica
ciò
che
viene
visualizzato
in
un
determinato
istante
sullo
schermo
di
un
monitor,
di
un
televisore
o
di
un
qualunque
dispositivo
video.
8
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
7

8. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
Figura
7
Lista
dei
nuovi
utenti
importati.
Figura
8
Dettaglio
di
uno
degli
utenti
importati.
Figura
9
Site
associati
all’utente.
Figura
10
Ruoli
assegnati
all’utente.
Ogni
utente
importato
è
taggato
con
il
tag
“imported
users”
(vedi
Figura
11).
Applicare
un
tag
faciliterà
poi
la
ricerca
degli
stessi
(vedi
Figura
13).
In
Figura
12
è
mostrato
il
valore
applicato
al
campo
personalizzato
AccountId
proveniente
dal
foglio
Excel.
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
8

9. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
Figura
11
Tag
assegnato
all’utente
importato.
Figura
12
Campo
personalizzato
importato.
Figura
13
Ricerca
utenti
importati
by
tag.
Abbiamo
avuto
modo
di
vedere
come
sia
prezioso
il
vantaggio
che
si
ottiene
con
la
possibilità
di
poter
interagire
con
ogni
funzionalità
ed
entità
del
portale
esposta
tramite
API
locali
e
remote.
Il
progetto
che
implementa
la
soluzione
discussa
nel
corso
della
prima
parte
dell’articolo
potrebbe
essere
la
base
di
partenza
per
il
vostro
progetto
d’importazione.
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
9

10. Antonio
Musarra's
Blog
Document Revision:1.0
The
ideal
solution
for
a
problem
Blog:
http://www.dontesta.it
LinkedIn:
http://it.linkedin.com/in/amusarra
Mail:
antonio.musarra@gmail.com
Bibliography
Liferay
Inc.
(2013).
Creating
sites
and
managing
pages.
Tratto
da
Liferay
Portal
6.1
-­‐
User
Guide:
http://www.liferay.com/it/documentation/liferay-­‐
portal/6.1/user-­‐guide/-­‐/ai/managing-­‐pages-­‐in-­‐liferay-­‐portal
Liferay
Inc.
(2013).
Custom
Fields.
Tratto
da
Liferay
Portal
6.1
-­‐
User
Guide:
http://www.liferay.com/it/documentation/liferay-­‐portal/6.1/user-­‐guide/-­‐
/ai/lp-­‐6-­‐1-­‐ugen12-­‐custom-­‐fields-­‐0
Liferay
Inc.
(2013).
Liferay
APIs.
Tratto
da
Liferay
Portal
6.1
-­‐
Developers
Guide:
http://www.liferay.com/it/documentation/liferay-­‐portal/6.1/development/-­‐
/ai/liferay-­‐ap-­‐1
Liferay
Inc.
(2013).
Roles
and
permissions.
Tratto
da
Liferay
Portal
6.1
-­‐
User
Guide:
http://www.liferay.com/it/documentation/liferay-­‐portal/6.1/user-­‐
guide/-­‐/ai/lp-­‐6-­‐1-­‐ugen15-­‐roles-­‐and-­‐permissions-­‐0
Liferay
Inc.
(2013).
Service
Security
Layers.
Tratto
da
Liferay
Portal
6.1
-­‐
Developers
Guide:
http://www.liferay.com/it/documentation/liferay-­‐
portal/6.1/development/-­‐/ai/service-­‐security-­‐layers
Liferay
Inc.
(2013).
SOAP
Web
Services.
Tratto
da
Liferay
Portal
6.1
-­‐
Developers
Guide:
http://www.liferay.com/it/documentation/liferay-­‐
portal/6.1/development/-­‐/ai/soap-­‐web-­‐services
Musarra,
A.
(2013,
Nov.
14).
Import
users
from
excel
into
Liferay
Portal
by
Web
Services
SOAP.
Tratto
da
Antonio
Musarra's
GitHub
Repositories:
https://github.com/amusarra/ImportUsersLiferayViaWS/tree/master
The
Apache
Software
Foundation.
(2013).
Apache
POI
-­‐
the
Java
API
for
Microsoft
Documents.
Tratto
da
The
Apache
POI
Project.
01/01/14
This
document
is
issued
with
license
Creative
Commons
Attribution-­‐NonCommercial-­‐ShareAlike
10