Nell'articolo Come importare utenti da un foglio Excel[1] pubblicato su D'vel Tech Blog è stato discusso il modo d'utilizzare i Web Services esposti da Liferay con l'obiettivo di poter importare un insieme di utenti da un foglio Excel. Nell'articolo [1] non è stato trattato l'aspetto pratico ma illustrata una soluzione di cui vedremo l'implementazione nel corso di questo post.

L'intero progetto d'esempio che implementa la soluzione discussa in [1] è disponibile sul repository ImportUsersLiferayViaWS. Il progetto è basato su Maven 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:
  • Verifica formale di alcuni campi (esempio: screen Name e Email non possono essere vuoti);
  • Verifica dell'esistenza del ruolo specificato da assegnare all'utente;
  • Verifica dell'esistenza del site o gruppo a cui assegnare l'utente;
• Creazione degli utenti non scartati.

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.

Il programma d'importazione dopo la compilazione del progetto sarà 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.

$ git clone git://github.com/amusarra/ImportUsersLiferayViaWS.git
$ cd ImportUsersLiferayViaWS
$ mvn package

$ 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

Il listato a seguire mostra invece l'avanzamento (dei vari task) del programma d'importazione.

2013-11-14 13:48:13,892 [main] INFO  it.dontesta.liferay.example.portal.client.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  it.dontesta.liferay.example.portal.client.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  it.dontesta.liferay.example.portal.client.ImportUsersToLiferay - Company ID 1
2013-11-14 13:48:14,582 [main] INFO  it.dontesta.liferay.example.portal.client.ImportUsersToLiferay - Get UserID...
2013-11-14 13:48:14,619 [main] INFO  it.dontesta.liferay.example.portal.client.ImportUsersToLiferay - UserId for user named admin is 10382
2013-11-14 13:48:15,517 [main] INFO  it.dontesta.liferay.example.portal.client.ImportUsersToLiferay - Add user object UserToImport [accountId=7477234f-34f7-76bf-b
2013-11-14 13:48:15,533 [main] WARN  it.dontesta.liferay.example.portal.client.ImportUsersToLiferay - The username attribute can not be null for rowId 5
2013-11-14 13:48:15,534 [main] INFO  it.dontesta.liferay.example.portal.client.ImportUsersToLiferay - User ready for import to liferay is 4
2013-11-14 13:48:15,534 [main] INFO  it.dontesta.liferay.example.portal.client.ImportUsersToLiferay - Starting import users...
2013-11-14 13:48:15,557 [main] INFO  it.dontesta.liferay.example.portal.client.ImportUsersToLiferay - User cmontagno added on liferay.
2013-11-14 13:48:15,558 [main] INFO  it.dontesta.liferay.example.portal.client.ImportUsersToLiferay - Import users to liferay completed successfully

Il programma d'importazione per impostazione predefinita (senza specificare nessun parametro) tenta di connettersi ai Web Services della vostra installazione locale di Liferay. I parametri supportati sono i seguenti:

• -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 degli screenshot il risultato dell'importazione utilizzando il file Excel di esempio.

 

Se il site specificato sul foglio Excel esiste sulla vostra istanza di Liferay allora l'utente sarà associato, in caso contrario sarà associato a quello di default (vedere Figura 3). La stessa regola vale per i ruoli (vedere Figura 4).

 

 Ogni utente importato è taggato con il tag "imported users" (vedere Figura 5). Applicare un tag faciliterà poi la ricerca degli stessi (vedere Figura 7). In Figura 6 è mostrato il valore applicato al campo personalizzato accountId proveniente dal foglio Excel.

 

 

 

Nel corso di questo articolo abbiamo avuto modo di vedere come utilizzare il progetto che implementa la soluzione illustrata in [1]. Questo progetto potrebbe essere la base di partenza per il vostro progetto d'importazione.

Bibliography

[1] Musarra, A. (2013, Nov. 18). Come importare utenti da un foglio Excel. Retrieved from D'VEL TECH BLOG: http://blog.d-vel.com/web/blog/home/-/blogs/come-importare-utenti-da-un-foglio-excel