project archive versione 2

versione 1.00, 1 maggio 2012

Michele Liberi
mail: mliberi@gmail.com
tel.: 049 9116199, cell: 3485211456

indice

Introduzione
Descrizione dell'applicazione
Architettura e componenti dell'applicazione
Struttura del database

Introduzione

Project archive è un'applicazione web progettata su specifiche ABB per gestire la documentazione di progetto, a fronte di una comunità di utenti.

Tutto ruota intorno al concetto di progetto, ed ogni documento gestito da project archive è inserito nel contesto di un ben preciso progetto e può avere un numero arbitrario di allegati.

Le funzioni disponibili per gli utenti dipendono dal ruolo ad essi assegnato.

Descrizione dell'applicazione

I nuovi progetti possono essere creati nel sistema solo da utenti con il ruolo di assistant, ed è subordinata alla presenza degli stessi nel gestionale SAP, con il quale project archive è collegato.

Ogni progetto ha:

un codice progetto, che lo identifica in modo univoco in SAP come in project archive;
un cliente di riferimento, informazione che viene reperita direttamente dal DB di SAP all'atto della creazione del progetto in project archive;
uno stabilimento di installazione, informazione viene reperita direttamente dal DB di SAP all'atto della creazione del progetto in project archive;
un responsabile di progetto responsabile del progetto, nel seguito indicato brevemente con la sigla PM;
un assistente del PM, nel seguito indicato brevemente con la sigla AS;
una lista di distribuzione cioè una lista di persone interessate a ricevere notifiche legate ad attività sul progetto.

Ogni progetto inoltre può essere collegato con una relazione genitore-figlio ad un altro progetto da cui è stato derivato.

I documenti inseriti in project archive sono essenzialmente dei files, identificati in modo univoco da un codice documento che viene assegnato dal sistema al momento del check-in. Per ogni documento il sistema gestisce i seguenti attributi:

un numero di revisione, che viene automaticamente incrementato dal sistema quando un utente inserisce una nuova revisione di un documento esistente: le precedenti revisioni, benché superate, rimangono disponibili nel sistema;
un progetto di riferimento;
un tipo documento: questa categorizzazione permette di fare ricerche mirate e di differenziare la gestione degli stessi; i tipi documento gestiti sono:
- corrispondenza
- ordine del cliente
- specifica tecnica contrattuale
- conferma ABB
- specifica tecnica ABB
- costo/conteggio
- offerta
- piano di progettazione
- disegno
- DXF portelle
- verbale di riesame del progetto
- verbale di validazione della progettazione
- certificato di collaudo
- certificato di collaudo subfornitori
- autorizzazione alla spedizione
- piano controllo qualità
- rapporto montaggio esterno
- fotografie
- varie
- logistico/contabile
una dimensione: A4V, A4O, A3V, etc.;
una data del documento;
una descrizione;
un proprietario che coincide con l'utente che lo ha inserito nel sistema.

Ogni documento con tipologia corrispondenza o disegno può avere un numero arbitrario di allegati. Per ogni allegato il sistema gestisce i seguenti attributi:

una dimensione: A4V, A4O, A3V, etc.;
una data di riferimento;
una descrizione;
un proprietario che coincide con l'utente che lo ha inserito nel sistema.

Il sistema gestisce inoltre un flusso di approvazione per alcune tipologie di documenti.

L'accesso ai documenti viene controllato dal sistema in base alla tipologia del documento, ed al ruolo che ha l'utente nel sistema e nel progetto che lo contiene.

Ruoli

I ruoli possibili per gli utenti sono:

super: super user che dispone di tutte le funzioni del sistema;
pm: project manager, che può essere il referente di uno o più progetti;
as: assistant, dispone di particolari funzioni legate al suo ruolo;
pe: project engineer, nel seguito indicato brevemente con la sigla PE;
ro: utente generico, che accede all'archivio solo in consultazione.
rev: revisore dei conti, ha accesso ad alcune tipologie di documenti;

Esistono anche utenti che non hanno alcun ruolo, in tal caso non hanno accesso al sistema. Vengono censiti solo perchè in passato hanno avuto un ruolo e sono referenziati come proprietari di documenti o allegati agli stessi, o come PM o AS di progetti chiusi.

Funzioni

Quando si accede all'applicazione con il proprio browser preferito all'URL http://10.39.148.33/pm/pa2, dopo aver completato la fase di autenticazione, viene mostrata la pagina principale dell'applicazione nella quale l'utente può immettere dei filtri di ricerca e attivare delle funzioni.

Progetti

Creazione nuovo progetto

Funzione accessibile solo dalla pagina principale e riservata ad utenti con ruolo assistant.

Con un click sul tasto new_project gli utenti con ruolo assistant accedono alla pagina di creazione nuovo progetto.

Dopo aver compilato il modulo contenente il numero di progetto e le altre informazioni del progetto, con un click sul tasto add_project il progetto verrà effettivamente creato.

La creazione di un progetto è subordinata alla esistenza dello stesso nel sistema gestionale SAP, a cui project archive è colegato.

Ricerca progetti o visualizzazione dettagli di un progetto

Funzione accessibile a tutti gli utenti.

Con un click sul bottone prjdetails l'utente può visualizzare i dettagli di un singolo progetto (se viene fornito il project number), oppure la lista dei progetti che corrispondono ai filtri di ricerca immessi, dalla quale si può successivamente accedere alle informazioni di dettaglio dei singoli progetti.

L'accesso ai dettagli di un singolo progetto è possibile:

dalla pagina principale dell'applicazione
dalla lista dei progetti selezionati tramite filtri di ricerca
dalla lista dei documenti selezionati tramite filtri di ricerca

I filtri di ricerca pertinenti per la ricerca dei progetti sono:

project number: deve corrispondere esattamente ad un codice progetto esistente;
manager: il PM del progetto, la scelta avviene tramite menu a tendina che riporta tutti i possibili PM dei progetti censiti nel sistema;
assigned from/to: data minima/massima di assegnazione del progetto al PM;
customer: il cliente di riferimento del progetto, l'utente può immettere anche solo una parte della ragione sociale del cliente;
plant: la sede del cliente di installazione degli apparati, l'utente può immettere anche solo una parte dell'informazione;

Nella pagina di dettaglio di un progetto c'è una tabellina con tutte le informazioni associate al progetto, la linea di ascendenza e l'albero dei progetti derivati (ottenuti tramite elaborazione delle relazioni genitore-figlio), e una tabellina di conteggio dei documenti associati al progetto suddivisi per tipologia degli stessi.

Solo il PM o AS del progetto hanno accesso da questa pagina alle funzioni di modifica del progetto stesso, cioè possono modificare: PM, AS, lista di distribuzione, progetto genitore.

Cambio del PM o AS di un progetto

Funzione accessibile dalla pagina dei dettagli del progetto, riservata al PM o AS del progetto.

Dopo aver selezionato il nuovo PM e/o il nuovo AS, con un click sul tasto update_manager, l'utente può modificare il progetto.

Modifica della lista delle persone interessate alle notifiche

Funzione accessibile dalla pagina dei dettagli del progetto, riservata al PM o AS del progetto.

La lista delle persone facenti parte della lista di distribuzione avviene tramite menu a tendina a scelta multipla. Per selezionare/deselezionare un elemento bisogna premerlo con il mouse mantenendo premuto il tasto CTRL della tastiera.

Per modificare la lista di distribuzione del progetto, l'utente deve premere il tasto update_dlist

Modifica della relazione genitore-figlio di un progetto

Funzione accessibile dalla pagina dei dettagli del progetto, riservata al PM o AS del progetto.

L'albero delle derivazioni dei vari progetti viene mantenuta tramite un collegamento tra figlio e genitore, ovvero tra progetto derivato e progetto dal quello esso è stato derivato.

Per modificare l'albero il PM o AS deve accedere alla pagina di dettaglio del progetto derivato (figlio), introdurre nel campo parent il codice del progetto da cui è stato derivato, e premere il tasto update_parent.

Cancellazione di un progetto

Funzione accessibile dalla pagina dei dettagli del progetto, riservata al PM o AS del progetto.

Solo nel caso il progetto non contenga alcun documento, nella pagina di dettaglio ci sarà il tasto prj_delete.

L'utente dovrà confermare la cancellazione del progetto con un click sul tasto confirm_prj_delete.

Documenti

Ricerca documenti

Funzione accessibile a tutti gli utenti, dalla pagina principale.

Questa è senz'altro la funzione principale del sistema: permette di cercare nell'archivio tutti i documenti che corrispondono ai filtri di ricerca immessi.

Con un click sul tasto search viene generata la lista di tutti i documenti che corrispondono ai criteri di ricerca immessi. Inoltre verrà generata una tabellina riepilogativa del numero dei documenti selezionati suddivisi per tipo.

Tutti i filtri di ricerca relativi alla selezione dei progetti continuano a funzionare esattamente come descritto nel capitolo precedente: i documenti selezionati saranno quelli relativi ad uno dei progetti selezionati.

L'utente potrà ulteriormente circoscrivere la ricerca utilizzando i seguenti filtri specifici per i documenti:

doc type: la scelta avviene tramite menu a tendina;
da approvare: indicatore on/off specifico per la ricerca di documenti per i quali è necessaria l'approvazione da parte del PM, ha senso solo per ocumenti con tipo disegno;
checked in from/to: data minima/massima di data del documento;
title: il nome del file, l'utente può immettere anche solo una parte dell'informazione;
reference: la descrizione del documento, l'utente può immettere anche solo una parte dell'informazione;
revision: le scelte possibili sono:
- latest: per ogni documento viene presa in considerazione solo l'ultima revisione;
- all: vengono prese in considerazione tutte le revisioni del documento.

A partire dalla lista generata dalla funzione di ricerca l'utente potrà:

accedere ai dettagli di progetto, con un click sul collegamento presente nella colonna project;
accedere ai dettagli del documento ed eventuali allegati, con un click sul collegamento presente nella colonna title;
visualizzare o scaricare il file associato al documento, con un click sul collegamento presente nella colonna files;
scaricare con un unica operazione un insieme di files;
richiamare una delle possibili azioni in base al suo ruolo ed alla tipologia del documento;
accedere alla funzione di check-in, con la quale potrà inserire nuovi documenti nel sistema.

Dettagli di un documento

Funzione accessibile a tutti gli utenti, con un click sul collegamento presente nella colonna title della pagina contenente i risultati della ricerca.

Si accede ad una pagina contenente le informazioni di dettaglio del documento non contenute nella tabella principale.

Tra i dettagli del documento ci sono i suoi allegati.

Accesso ai files associati ai documenti

Funzione accessibile a tutti gli utenti, con alcune limitazioni legate alla tipologia dei documenti.

Nella pagina contenente i risultati di una ricerca, per ogni documento, nella colonna files, c'è un collegamento al file in esso contenuto.

Gli utenti con ruolo rev (revisore dei conti) ha accesso solo a files associati a documenti con tipo costo/conteggio oppure logistico/contabile.

L'accesso a files di tipo costo/conteggio è riservato al PM del progetto e al suo assistente.

L'accesso ai disegni non approvati è riservato al proprietario (utente che lo ha immesso in archivio), al PM e al suo AS.

Per scaricare un insieme di files con un'operazione unica è disponibile la funzione extract_selected, che l'utente attiverà dopo aver scelto i files desiderati. Arriverà un file in formato .zip dal quale l'utente potrà estrarre i files.

Creazione nuovi documenti

Funzione accessibile dalla pagina principale e dalla pagina contenente i risultati di una ricerca, riservata ad utenti con ruolo pm (project manager), pe (project engineer), as (assistant), con un click sul tasto new_document.

La creazione di nuovi documenti può avvenire con tre modalità:

file singolo
files multipli
stampa PDF

Nel primo caso l'utente seleziona un singolo file da inserire nell'archivio.

Nel secondo invece i files da inserire nell'archivio sono contenuti in un unico file .zip.

Il terzo è un caso un po' particolare. Su ogni PC è installata una stampante PDF tramite la quale gli utenti possono creare dei files a partire da qualsiasi programma, ad esempio lotus notes, che verranno salvati direttamente sul server dove gira project archive. Nel modulo di check in è presente un tasto pdf_files che consente all'utente di andare a selezionare uno dei files PDF che ha precedentemente creato. Nella stessa pagina l'utente può cancellare files PDF utilizzando il tasto pdf_remove

Nel modulo è inoltre presente un'opzione send e-mail to PM: se impostato il PM del progetto riceverà una e-mail di notifica con i dettagli del documento inserito nell'archivio.

L'inserimento del documento avviene quando l'utente preme il tasto check_in o pdf_checkin.

Nuova revisione di un documento

Funzione accessibile dalla pagina contenente i risultati di una ricerca con un click sul collegamento newrev presente nella colonna action, riservata ad utenti con ruolo pm, pe, as.

La funzione non è disponibile per i documenti per i quali esiste già una revisione successiva, o per i disegni non approvati.

La creazione di una nuova revisione di un documento è simile a quella di un documento ex novo, ma prevede solo la modalità "file singolo".

Anche in questo caso nel modulo è presente l'opzione send e-mail to PM: se impostato il PM del progetto riceverà una e-mail di notifica con i dettagli del documento inserito nell'archivio.

Cancellazione di un documento

Funzione accessibile dalla pagina contenente i risultati di una ricerca con un click sul collegamento delete presente nella colonna action, riservata al proprietario del documento.

L'utente dovrà confermare l'intenzione di cancellare il documento con un click sul tasto confirm_delete.

Tutti gli allegati al documento vengono parimenti cancellati.

Approvazione disegni

Funzione accessibile dalla pagina contenente i risultati di una ricerca con un click sul collegamento approve presente nella colonna action, riservata al PM del progetto che contiene il disegno.

Allegati

Creazione allegati

La creazione di allegati ad un documento può avvenire con due modalità:

file singolo
files multipli

Nel primo caso l'utente seleziona un singolo file da inserire nell'archivio.

Nel secondo invece i files da inserire nell'archivio sono contenuti in un unico file .zip.

L'inserimento dell'allegato avviene quando l'utente preme il tasto attach.

Accesso agli allegati

Funzione accessibile a tutti gli utenti.

Nella pagina dei dettagli di un documento è presente una tabellina con una riga per ognuno degli allegati al documento. Per ogni allegato è disponibile un collegamento al file in esso contenuto.

Cancellazione allegato

Funzione accessibile dalla pagina di dettaglio di un documento, con un click sul collegamento delete presente nella colonna action, riservata al proprietario dell'allegato.

L'utente dovrà confermare l'intenzione di cancellare il documento con un click sul tasto confirm_delete.

Utenti

La gestione degli utenti esula dall'applicazione web e viene fatta a mano dall'amministratore di sistema.

tabella riepilogativa funzioni/ruoli

funzione/ruolo	super	pm	as	pe	ro	rev
creazione nuovo progetto	*	-	*	-	-	-
ricerca progetti o visualizzazione dettagli di un progetto	*	*	*	*	*	*
cambio del PM o AS di un progetto	*	1	1	-	-	-
modifica della relazione genitore-figlio di un progetto	*	1	1	-	-	-
modifica della lista delle persone interessate alle notifiche	*	1	1	-	-	-
cancellazione di un progetto	*	1	1	-	-	-
ricerca documenti	*	*	*	*	*	2
dettagli di un documento	*	*	*	*	*	*
accesso ai files associati a disegni non approvati	*	1	-	-	-	-
accesso ai files di tipo costo/conteggio	*	1	1	-	-	-
accesso ai files associati ad altri documenti	*	*	*	*	*	*
creazione nuovi documenti	*	*	*	*	-	-
nuova revisione di un documento	*	*	*	*	-	-
cancellazione di un documento	*	3	3	3	-	-
approvazione disegni	*	*	-	-	-	-
creazione allegati	*	*	*	*	-	-
accesso agli allegati	*	*	*	*	*	*
cancellazione allegato	*	3	3	3	-	-

Legenda:

* disponibile
- non disponibile
1 solo per il PM o AS del progetto
2 ricerca limitata ai soli documenti di tipo costo/conteggio e logistico/contabile
3 solo se proprietario del file

*	disponibile
-	non disponibile
1	solo per il PM o AS del progetto
2	ricerca limitata ai soli documenti di tipo costo/conteggio e logistico/contabile
3	solo se proprietario del file

notifiche

Project archive prevede delle notifiche via e-mail collegate a funzioni richiamate dagli utenti.

Ove non specificato diversamente la e-mail di notifica viene inviata al PM del progetto, al AS del progetto e a tutti i componenti della lista di distribuzione.

Le situazioni che prevedono una notifica sono le seguenti:

check-in di un disegno: viene inviata solo al PM del progetto e contiene il collegamento diretto alla pagina che contiene la funzione di approvazione del disegno;
(opzionale) check-in di altri tipi di documento: viene inviata al PM del progetto a discrezione di chi inserisce il documento;
cancellazione di un disegno approvato
approvazione di un disegno
creazione di un nuovo progetto
cambio del PM di un progetto

Architettura e componenti dell'applicazione

Project archive è un'applicazione pensata per funzionare in ambiente UNIX, ma in linea teorica può funzionare anche in ambiente Windows utilizzando l'ambiente di compatibilità open source Cygwin.

Si tratta di un'applicazione scritta in korn shell, linguaggio di programmazione standard in ambiente UNIX, che utilizza l'interfaccia CGI. Per il suo funzionamente è quindi necessario un server HTTP opportunamente configurato.

La script fa ampio uso di comandi del mio personale pacchetto di strumenti, che devono essere installati nel sistema e sono un prerequisito indispensabile. Essi sono pubblicamente disponibili e liberamente scaricabili all'URL http://mliberi.top.

Per quanto riguarda i dati gestiti dall'applicazione non è necessario alcun database relazionale, è sufficiente il filesystem di UNIX.

Struttura del database

Una delle peculiarità di project archive versione 2 (nel seguito brevemente pa2) è che non usa un database relazionale, ma si appoggia esclusivamente su filesystem.

Questa caratteristica rende molto semplice la gestione dei dati da un punto di vista sistemistico e consente di operare sugli stessi con i normali comandi del sistema operativo UNIX (ls, grep, awk, etc.).

pa2 può funzionare con qualunque tipo di filesystem, ma per motivi di prestazioni e di ottimizzazione dello spazio si consiglia di utilizzare "raiserFS", di gran lunga migliore di tutti gli altri.

Tutti i dati sono contenuti in un'unica directory base e tutti i componenti descritti nel seguito sono contenuti in questa directory base.

Nel database di pa2 esistono quattro tipologie di oggetti:

persone
progetti
documenti
allegati

Per ogni oggetto, al momento della creazione, la procedura andrà a generare un identificatore univoco. Tutti gli identificatori di oggetti sono memorizzati nella directory .r.

Il file .csys contiene i contatori per la numerazione progressiva dei record all'interno del database.

Il file .pol contiene i contatori per la numerazione progressiva dei documenti.

I files contenuti nei documenti sono salvati nella directory .p/N.18.ext, con N=id univoco del record, ext=estensione originale del file (doc, xls, pdf, etc.).

I files allegati ai documenti sono salvati nella directory .p/N.23.ext, con N=id univoco del record, ext=estensione originale del file (doc, xls, pdf, etc.).

persone

Ogni persona censita nel DB ha i seguenti attributi:

username: l'identificativo necessario per accedere al sistema
name: nome di battesimo
surname: cognome
email: indirizzo di e-mail per le notifiche
role: ruolo della persona in pa2
winuser: username in AD, attributo valorizzato solo se diverso da username

Per ogni persona esiste un file nella directory people/.k/, il nome del file corrisponde al valore dell'attributo username, chiave primaria del record.

Per ottimizzare le ricerche massive i dati relativi agli oggetti di questo tipo sono mantenuti anche nel file people/.fts.

progetti

Ogni progetto censito nel DB ha i seguenti attributi:

P: codice del progetto
customer: cliente di riferimento del progetto
plant: stabilimento di installazione
pm: username del PM
since: data di assegnamento del progetto al PM
as: username del AS
parent: progetto genitore
dlist: lista di usernames delle persone inserite nella lista di distribuzione

Per ogni progetto esiste un file nella directory projects/.k/, il nome del file corrisponde al valore dell'attributo P, chiave primaria del record.

Per ottimizzare le ricerche massive i dati relativi agli oggetti di questo tipo sono mantenuti anche nel file projects/.fts.

documenti

Ogni documento censito nel DB ha i seguenti attributi:

D: codice del documento, viene assegnato automaticamente da pa2 al momento del check-in; le prime 4 lettere indicano il tipo di documento, segue un numero progressivo di 8 cifre;
R: numero di revisione del documento, viene inizializzato a 1 quando il documento viene creato, ed incrementato quando si crea una nuova revisione;
project: il codice del progetto di riferimento;
type: il tipo di documento;
latest: valore booleano (true/false) che indica se si tratta dell'ultima revisione del documento;
approved: valore booleano (true/false) che indica se il documento è stato approvato;
size: la dimensione del documento (A4V, A4O, A3V, etc.);
date: la data del documento, che non corrisponde alla data del check-in;
reference: testo libero che descrive il documento;
f: il nome del file contenuto nel documento;
owner: lo username del proprietario del documento, ovvero l'utente che lo ha inserito in archivio;
att: valore booleano (true/false) che indica se il documento ha allegati.

Per ogni documento esiste un file nella directory docs/.k/, il nome del file corrisponde al numero progressivo assegnato da pa2 al momento del check-in, infatti il record non ha chiave primaria.

Per ottimizzare le ricerche massive i dati relativi agli oggetti di questo tipo sono mantenuti anche nel file docs/.fts.

allegati

Ogni allegato censito nel DB ha i seguenti attributi:

doc: codice del documento a cui si riferisce
rev: revisione del documento a cui si riferisce
project: il codice del progetto di riferimento;
size: la dimensione del documento (A4V, A4O, A3V, etc.);
date: la data del documento, che non corrisponde alla data dell'inserimento in archivio;
reference: testo libero che descrive l'allegato;
f: il nome del file allegato;
owner: lo username del proprietario dell'allegato, ovvero l'utente che lo ha inserito in archivio;

Per ogni allegato esiste un file nella directory attachs/.k/, il nome del file corrisponde al numero progressivo assegnato da pa2 al momento del check-in, infatti il record non ha chiave primaria.

Per ottimizzare le ricerche massive i dati relativi agli oggetti di questo tipo sono mantenuti anche nel file attachs/.fts.