bloggers bloggers

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 ERP (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'ESB. L'ERP la sorgente dati e l'ESB(Enterprise Service Bus)"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.

La sorgente dati da cui leggere i record da importare su Liferay come utenti sarà un foglio excel che avrà una struttura del tipo indicata a seguire:

• Title
• Screen Name
• Email
• First Name
• Middle Name
• 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 dati prevede tre informazioni che ritengo rilevanti, il Site Name, Role Name e AccountId. Il Site Name contiene la lista dei site (può essere anche una lista vuota) a cui il nuovo utente deve essere associato, il Role Name contiene la lista di ruoli (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 sull'entità utente.

I diagrammi come sempre aiutano la comprensionee i flow chart fanno al caso nostro. I diagrammi a seguire mostrano il processo d'importazione nella sua globalità.

Figura 1 - Processo d'importazione utenti da Excel a Liferay

Figura 2 - Processo di lettura e verifica dati da importare.

Figura 3 - Processo che esegue l'import effettivo su Liferay tramite chiamate ai WS

Per l'operazione d'importazione degli utenti da file excel a Liferay, faremo uso dell'API (Application Programing Interface) di Liferay e in particolar modo dei servizi SOAP (Simple Object Access Protocol) su HTTP. Per coloro che non fossero avvezzi con quest'area di Liferay, consiglio di leggere nell'ordine i seguenti documenti:

• Liferay APIs
• Service Security Layers
• SOAP Web Services

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 4 - Liferay API utilizzate e dettaglio delle operazione 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 risulta molto semplice utilizzando i seguenti componenti:

• Apache POI: Utilizzato per leggere la lista degli utenti da importare da un foglio excel;
• Liferay Portal Client (v. 6.1.1): Utilizzato per interaggire con i servizi SOAP esposti da Liferay

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 5. Questo oggetto farà poi parte di una lista di oggetti dello stesso tipo, l'insieme di questi oggetti saranno poi inseriti effettivamente su Liferay.

Figura 5 - Modello che rappresenta l'utente letto dal file excel e che sarà poi inserito su Liferay

Preferisco non riportare sull'articolo interi pezzi di codice che implementano la soluzione, ho invece preferito rendere pubblico l'intero progetto che trovate all'indirizzo ImportUsersLiferayViaWS, inoltre il README del progetto contiene le informazioni necessarie a eseguire un test d'importazione.

E' molto significativo il vantaggio che si ottiene con la possibilità di poter interagire con ogni funzionalità del portale e entità (configurata appositamente) esposta tramite API locali e remote.