Scrivi il tuo report

In questa sezione descriveremo come creare nuovi report di Twproject usando Jasper Reports.

I dati del tuo progetti sono raccolti e gestiti con cura da Twproject e questo rappresenta uno degli aspetti più preziosi nell’adozione di Twproject
Come puoi estrarre i tuoi dati e presentarli ai tuoi utenti? In realtà Twproject ha varie pagine con funzionalità di filtro dinamico che estraggono dati significativi, ma fino alla versione 5.5 mancava un sistema di report personalizzabile.
In questa versione abbiamo integrato Jasper Reports, uno dei più potenti motori di report. Jasper reports aggiunge la possibilità di creare il tuo report in pochi minuti usando un editor grafico.
I report sono integrati con la flessibile struttura di sicurezza di Twproject in un modo facile e pratico, senza obbligare gli utenti a scrivere query e regole complesse.


JasperReports
è uno strumento di reporting di JasperSoft (acquisita recentemente da Tibco) largamente usato dalla comunità java orientata alle imprese.

I report possono essere disegnati facilmente con iReport Designer, che è facile, potente, gratuito e open-source, oppure con Jaspersoft Studio.

Jasper Studio è il prodotto principale ed è basato su Eclipse. iReport è più facile da configurare, ma sfortunatamente verrà abbandonato presto. Se già conosci l’interfaccia Eclipse, usa Jasper Studio, altrimenti usa iReport. In realtà i passi per la configurazione sono molto simili.

Per i nostri scopi iReport funziona perfettamente.

Driver e classpath

Una volta che iReport  è installato il primo passo è quello di aggiungere le librerie del database all’editor.

1)  Clicca su tools->options e poi sul tab “classpath”.

image

I driver del Database sono inclusi nella distribuzione di Twproject, puoi trovarli qui:

  • SQL server: [twproject root]\WEB-INF\lib\jtds-1.2.5.jar
  • My SQL: [twproject root]\WEB-INF\lib\mysql-connector-java-5.1.6-bin.jar
  • Oracle: [twproject root]\WEB-INF\lib\ojdbc5.jar
  • PostgreSQL: [twproject root]\WEB-INF\lib\postgresql-9.0-801.jdbc3.jar
  • HSQLDB: [twproject root]\WEB-INF\lib\hsqldb.jar

Clicca sul bottone “Add jar” e selziona il driver per il database che stai usando.

Quindi dovresti aggiungere anche le classi di Twproject, nel caso dovessimo usare qulache funzione di formattazione.

Clicca su “Add Folder” e seleziona la cartella [twproject root]\WEB-INF\lib\classes

Una volta fatto siamo pronti per connettere il database di Twproject

1) clicca su “Step 1: Create database connection”

image

3) scegli Database JDBC Connection

image

4) scrivi il nome della connessione, “TW5 test” per esempio

5) seleziona il driver del database giusto:

inserisci i dati di connessione al server, nome del database, utente e password:

image

6) fai un test della connessione

image

Se la connessione è corretta, possiamo procedere scrivendo il nostro primo report.

Crea il tuo primo report

Clica su “Step 2 : create a new report“

image

Il wizard del report si aprirà in pop-up. Ci sono vari template:

image

Seleziona quello che ti piace di più e clicca su “Launch Report Wizard”.

image

Inserisci il nome del report e la location con attenzione: il nome del report e la location sono informazioni cruciali per l’integrazione tra Twproject e iReport. Leggi la sezione dedicata sotto.

Clicca “Next”

image

seleziona la tua fonte di dati appena creata “TW5 test”;ora è il momento di pensare alla query.

In questo esempio vorremmo riportare il tempo che ogni risorsa impiega sui loro progetti.

Per scrivere una query, è obbligatorio conoscere la struttura dati di Twproject. Anche se i nomi delle tabelle sono abbastanza immediati, suggerisco di dare unosguardo a questa sezione:

https://twproject.com/support/it/utilizzo-avanzato/import-export/struttura-del-database/

Se sei un mago di SQL puoi scrivere la tua query direttamente, ma se preferisci qualcosa di più  “visuale” clicca sul bottone “Design query”:

image

Trascina le tabelle di cui hai bisogno per la query.

Nel nostro caso le ore lavorative sono nella tabella twk_worklog. I record di worklog sono sempre collegati a un’assegnazione. Le assegnazioni creano relazioni tra risorse e task ponderate con un ruolo. Quindi dobbiamo aggiugere “twk_assignment”, “tsk_task”, “twk_resource” e “olpl_role”. Lo strumento di modifica della query userà le sql foreign keys per creare i joins.

Salva la query e clicca su “next”.

image

Puoi selezionare i campi che vuoi vedere nel tuo report. Nel nostro caso li aggiungeremo manualmente. Clicca su “next”

Qui definirai alcuni gruppi, ma questo non è obbligatorio, puoi aggiungerli anche dopo.

image

Clicca su “next” e poi su “finish”.

Il tuo “schema” del report è quasi pronto:

image

Si noti che un report ha molte sezioni come “Titolo”, “page header,” intestazione di due gruppi, dettagli, e un footer.

Se clicchi su “preview” vedrai qualcosa di bruttino come questo:

image

Torna sul designer e fai qualche modifica:

Cambia il titolo, usa il nome del task e della risorsa invece dell’id

Trascina la data di inserimento del worklog, azione e tempo speso dall’area “fields” sul nostro report nella sezione “details”:

image

Con queste semplici modifiche apparirà così:

image

Un po’ meglio, ma:

  1. le date sono in un formato strano: per sistemarle, fai tasto destro sul campo e clicca su “field pattern”. Scegli “Date” e poi il formato
  2. ci sono dei “null” nel caso non sia stata inserita la descrizione: seleziona il campo e dal box proprietà seleziona “Blank when null”
  3. il tempo impiegato è in millisecondi:  in questo caso devi usare quello usato nella funzione utility di Twproject. Fai tasto destro sul campo e scegli “Edit expression” poi scrivi:
    org.jblooming.utilities.DateUtilities.getMillisInHoursMinutes($F{twk_worklog_duration}). Questa funzione trasformerà millisecondi in a Ore:Minuti

Adesso siamo così:

image

Ora potresti volere somme parziali dei gruppi in header/footers. Questo può essere fatto introducendo le variabili.

In questo caso avremo bisogno di una variabile per sommare worklog su un gruppo di task, vedi ”sumGroup1”:

image

Trascina la variabile appena creata su “group footer 1” e formatta il risultato usando la funzione “getMillisInHoursMinutes” come sopra:

image

Puoi giocare con il designer per ottimizzare il tuo report. Quando sei pronto salvalo!

Integrazione tra iReport e Twproject

Una volta ottenuto il tuo report puoi lanciarlo dentro iReport, direttamente al database, ma se vuoi integrarlo in Twproject nel modo giusto (e.g.: rispettando la sicurezza) devi conoscere alcuni dettagli in più.

Il report appena creato è già disponibile nel tuo Twproject (se lo hai creato nel posto giusto con un nome univoco Smile).

Per vedere i report installati vai su Admin –> Customizations –> Forms, plugins and reports.

Nella sezione “Additional iReports” dovrebbe essere elencato il tuo report. Se non è così clicca sul bottone “reload plugins” (se ancora non appare c’è un problema sul report, vedi i log).

screen977

Dovresti già avere un widget speciale (“Report list” su wp_genericReports.jsp file) installato nel tuo Twproject. Aggiungilo al tuo cruscotto se vuoi accedere al tuo report direttamente da Twproject.
Vedi https://twproject.com/support/it/utilizzo-avanzato/personalizzazione/cruscotto/ per creare una nuova portlet/widget

image

Il widget contiene già i tuoi report se sei amministratore altrimenti sarà vuoto fino a che non assegnerai i giusti permessi come descritto di seguito.

Ma chi può eseguire questi report? Come vengono protetti i report in Twproject?

I nomi dei report sono usati per generare un permesso che è necessario selezionare per concedere l’accesso a un report, questo è il kotivo per cui i nomi devono essere significativi e univoci.

Ogni report estende l’implementazione standard basata sui ruoli di Twproject aggiungendo un permesso speciale, one for each report. Questi permessi possono essere assegnati a un ruolo esattamente come quelli standard, sa a livello globale che di progetto.

Ecco l’editor del ruolo esteso con i permessi del report:

screen978

Per una discussione approfondita sulla sicurezza di Twproject vedi: https://twproject.com/support/it/usare-twproject/sicurezza/

Una volta aggiunto un permesso del report a un ruolo, questo report sarà visibile agli utenti con quel ruolo.

Detto questo, per integrare JasperReports con Twproject dobbiamo occuparci di sicurezza e visibilità dei dati.

Accedendo al database direttamente dal motore di report può essere accettabile per alcuni report di “alto livello”, ma come sai, il modello di sicurezza di Twproject è molto flessibile, permettendo di vedere solo un set consentito di dati per ogni utente. Come può essere possibile creare un report che rispetti il modello di sicurezza di Twproject senza scrivere query complesse?

Report location e sicurezza

Abbiamo lavorato duro per risolvere questo problema e abbiamo trovato una soluzione facile e pratica.

Prima di tutto dividiamo i report in “globali” e “entitè correlata”.

I report globali sono i più flessibili e facili da costruire (come quello appena creato); possono usare tutti i tipi di dati di Twproject: task, worklog, riosrse o issue, senza restrizioni.

I report globali testeranno la sicurezza solo a livello di ruoli globali: nel peggiore dei casi chi può accedere al report può leggere i suoi dati (e.g progetti e costi), anche se non ha accesso ai “progetti” da cui provengono i dati.
Se il tuo report mostra dati sensibili, concedi l’accesso con attenzione.

Come dovresti sapere Smile , la sicurezza di Twproject usa a livello alto il concetto di “area di sicurezza” (vedi qui per dettagli: https://twproject.com/support/it/usare-twproject/sicurezza/aree/). Avere il permesso di vedere “report x” sull’“area 1” non significa che tu possa vedere lo stesso report sull’“area 2”. Per risolvere questo problema, Twproject passa al report la lista delle aree su cui hai i permessi. Puoi usare questa lista per filtrare i dati del report da mostrare, per esempio, solo project/resources/issues/worklog da “area 1” e non da “area 2”. Spiegheremo come usare questo parametro di seguito.

I report a entità correlate, invece, sono correlati a un’entità principale di Twproject come task, risorsa, issue e l’accesso è testato oggetto per oggetto, singolarmente.

Twproject non può ispezionare il report e sapere se è “globale”, relativo a tasks, a issues e così via; devi istruire Twproject circa i contenuti del report mettendoli in una cartella strutturata come di seguito:

image

dove “ACME” è il nome della tua azienda.

Quindi i report sulla root “report” sono considerati “globali” mentre quelli nelle cartelle “issue”, “risorse”, “task” o “worklog” sono considerati relativi alle entità di Twproject.

I report delle entità sono mostrati nelle pagine di lista dell’entità stessa come la lista dei task, la lista delle risorse, analisi worklog e così via..

I report relativi alle entità saranno accessbili usando il menu stampa su ogni sezione (task, risorse, issue, worklog):

I report delle entità riceveranno da Twproject la lista di id delle entità correntemente visibili sulla pagina compatibilimente con i permessi.

Un esempio chiarificatore: se oggi sei coinvolto su due progetti, uno come “project manager” e un altro come “worker”, la lista dei task mostrerà entrambi i progetti.

Considera che di default, com PM, puoi vedere i costi di progetto, ma come qoerker non puoi. Se hai creato un report per l’analisi dei costi, darai l’accesso a questo report solo al PM.

Costruendo il set di id per il report, Twproject controllerà entità per entità se hai i permessi per vederlo, e in questo caso, i progetti dove sei assegnato come worker rimarranno fuori.

Quindi il report sarà applicato alle entità che rispondono al filtro (task di oggi) e ai vincoli di sicurezza.

La lista delle entità consentite sarà passata al tuo report, ma adesso devi usarli!

I report riceveranno i seguenti parametri:

  • global reports: AREA_IDS
  • task reports: TASK_IDS e TASK_DESCENDANTS
  • resource reports: RESOURCE_IDS e RESOURCE_DESCENDANTS
  • issue reports: ISSUE_IDS
  • worklog reports: WORKLOG_IDS

Usa questi parametri nel tuo report come di seguito.

Per un report globale devi aggiungere alla query qualcosa come

$X{ IN ,twk_task.area,AREA_IDS} 

eventualmente in “AND” con altre clausole.

Per report di entità correlate aggiungi qualcosa come:

$X{ IN ,twk_worklog.id,WORKLOG_IDS}

o

$X{ IN ,twk_task.id,TASK_IDS}

Twproject fornisce vari report da usare come base di partenza. (Se copi un report esistente ricorda che devi cambiare sia il nome del file che la proprietà “nome del report” in iReport)