Document Management System in Oracle APEX

I Document Management System (o DMS) sono applicazioni web che aiutano le aziende ad automatizzare i processi di creazione, gestione, distribuzione ed archiviazione dei documenti aziendali.

Grazie ad un software documentale si possono ridurre i costi ed i tempi che comporta dover gestire una documentazione cartacea.

Inoltre, una gestione documentale efficiente porta alle aziende una notevole serie di vantaggi, una maggiore e ben organizzata disponibilità di informazioni e di conseguenza un maggior sviluppo del business.

Molti software di gestione documentale permettono anche di aggiungere la firma elettronica, indicizzare in modo efficiente i documenti, monitorare la conformità degli stessi e permetterne l’accesso anche da offline.

Molto spesso l’utilizzo di un software documentale viene poi accompagnato dall’uso di software per la gestione dei processi aziendali, software per la collaborazione aziendale o software per la gestione del workflow.

Le tipiche funzionalità che un DMS deve garantire sono: 

• La possibilità di consultare i documenti o chiedere il diritto di accesso
• La possibilità di caricare e modificare ed eventualmente eliminare i documenti
• La possibilità di condividere i documenti con gli altri utenti della realtà aziendale
• La possibilità di classificare con attributi aggiuntivi i documenti

In questo articolo desidero spiegarti come creare una semplice applicazione Document Management System in Oracle APEX.

In particolare imparerai

1. Come creare una applicazione che permette di caricare file nel database Oracle
2. Come gestire tags ed attributi aggiuntivi del documento
3. Come implementare un esempio di condivisione dei documenti

Prima di Iniziare

In questo tutorial costruiremo una applicazione APEX che salverà i file direttamente all’interno del database Oracle.

Tuttavia, non è detto che il file debba necessariamente risiedere nel database perché, ad esempio, potrebbe essere archiviato in Google Drive, in Share Point oppure utilizzando l’Object Storage messo a disposizione su Oracle Cloud.

Vedremo come implementare queste soluzioni in altri articoli dedicati.

Ricorda, infine, che puoi vedere una applicazione di demo collegandoti a questo link.

Step 1: crea una tabella custom

• Accedi ad Oracle APEX e vai in SQL Workshop > SQL Scripts
• Clicca sul bottone Create

• Copia ed incolla il seguente script SQL che creerà 2 oggetti:
  • la tabella custom DOCUMENTS
  • la sequenza custom DOCUMENTS_S

CREATE TABLE documents
  (
     id               NUMBER,
     file_name        VARCHAR2(4000),
     file_mimetype    VARCHAR2(1000),
     file_charset     VARCHAR2(1000),
     file_blob        BLOB,
     file_description VARCHAR2(4000),
     file_tags        VARCHAR2(4000),
     creation_date    DATE,
     created_by       VARCHAR2(4000),
     shared_with      VARCHAR2(4000)
     PRIMARY KEY ("id")
  );

CREATE TABLE document_tags
  (
     tag        VARCHAR2(4000)
  );

CREATE SEQUENCE documents_s
  START WITH 1
  INCREMENT BY 1; 

• Inserisci il nome dello script nel campo Script Name, premi Run e nella schermata successiva Run Now

• Se tutto è andato a buon fine dovresti vedere l’esito come nella schermata successiva. A meno che tu non voglia creare una maschera per caricare i files in un’applicazione già esistente, possiamo creare una nuova APP direttamente da qui cliccando sul bottone Create App

• Clicca su Create Application per avviare il wizard di creazione di una Applicazione APEX: questa opzione è comoda perché automatizza alcuni passaggi nella creazione dell’applicazione.

Step 2: crea una APP per gestire i files

Per gestire i files utilizzeremo una applicazione basata su Interactive Report + Form.

• Dall’APP Builder di Oracle APEX clicca su Create APP > New Application (questo passaggio non è necessario se hai avviato il wizard di creazione dell’APP dalla maschera di gestione degli Script SQL)
• Dai un nome alla tua APP (ad esempio File Manager APP) e premi Create Application
• Dall’APP Builder premi Create Page

• Seleziona il tipo pagine Form e premi Next

• Scegli l’opzione Report with Form e clicca Next

• Inserisci i parametri per la configurazione base del modulo:
  • Report Page Name: Documents
  • Form Page Name: Document
  • Form Page Mode: Normal
• Premi Next

• Puoi inserire fina da subito la pagina nel navigation menu dell’applicazione:
  • seleziona l’opzione Create a new navigation menu entry
  • specifica nel campo New Navigation Menu Entry l’etichetta che preferisci.

• Configura l’origine dati del modulo
  • Data Source: Local Database
  • Source Type: Table
  • Table View Name: seleziona la tabella DOCUMENTS che hai creato nello Step 1
• Premi Next

• Configura la colonna Primary Key e premi Create

Step 3: configura la Form Page

Una volta aver completato la procedura, dovresti vedere due nuove pagine ossia un Interactive Report e una Form.

In questa parte del tutorial andremo a configurare la Form Page che l’utente utilizzerà per caricare i file nell’applicazione.

• Seleziona la Form Page

Page Item PX_FILE_BLOB

Non so se lo hai notato. Nella tabella del database che abbiamo precedentemente creato ci sono alcune colonne particolari:

• FILE_NAME: il nome del file
• FILE_MIMETYPE: il tipo di file (immagine, file di testo, archivio,…)
• FILE_CHARSET: la codifica dei caratteri (es: UTF-8)
• FILE_BLOB: la colonna dove andremo a salvare il file vero e proprio

Fortunatamente APEX ci permette di configurare molto semplicemente come l’applicazione andrà a valorizzazione queste informazioni. Vediamo come fare.

• Seleziona il Page Item PX_FILE_BLOB

• Configura le proprietà principali
  • Type: File Browse
  • Label: Select File

• Vai alla sezione Settings ed imposta le seguenti proprietà
  • Storage Type: BLOB column specified in Item Source attribute
  • MIME Type Column: FILE_MIMETYPE (la colonna della tabella del database dove desideri che APEX salvi automaticamente il tipo di file)
  • Filename Column: FILE_NAME (la colonna della tabella del database dove APEX salverà il nome del file)
  • Character Set Column: FILE_CHARSET
  • Download Link Text: Download &P2_FILE_NAME.
    • NB: La stringa &P2_FILE_NAME. è un placeholder che APEX sostituirà automaticamente con il valore del Page Item P2_FILE_NAME
  • BLOB Last Updated Column: CREATION_DATE (la colonna della tabella del database dove desideri che APEX salvi automaticamente la data in cui è stato aggiornato il file)

• Nell’attributo File Types puoi indicare i tipi file (le estensioni) ammessi. Ti basta elencare le estensione dei file separati dal carattere ‘,’

• Nella proprietà Maximum File Size puoi specificare la dimensione massima del file che può essere caricata

Page Item PX_ID

• Seleziona il Page Item PX_ID

• Configura le seguenti proprietà
  • Type: Sequence
  • Sequence: DOCUMENTS_S

Page Item PX_CREATED_BY

• Seleziona il Page Item PX_CREATED_BY

• Configura le seguenti proprietà
  • Type: Hidden
  • Default > Type: SQL Query
  • Default > SQL Query: inserisci la query seguente

select v('app_user') from dual

Page Item PX_CREATION_DATE

• Seleziona il Page Item PX_CREATION_DATE

• Configura le seguenti proprietà
  • Type: Hidden
  • Default > Type: SQL Query
  • Default > SQL Query: inserisci la query seguente

select sysdate from dual

Page Items PX_FILE_NAME, PX_FILE_MIMETYPE, PX_FILE_CHARSET

• Seleziona i seguenti Page Items:
  • PX_FILE_NAME, PX_FILE_MIMETYPE, PX_FILE_CHARSET

• Configura per ciascuno di essi la proprietà Type a Hidden

Step 4: configura l’Interactive Report

Dopo aver configurato la Form Page possiamo concentrarci sull’Interactive Report.

• Seleziona l’Interactive Report Page

• Seleziona il componente Interactive Report

• Apri le proprietà del componente vai alla sezione Source
• Configurare le seguenti opzioni
  • Source > Type: SQL Query
  • SQL Query: inserisci la query seguente

select ID,
       FILE_NAME,
       FILE_MIMETYPE,
       FILE_CHARSET,
       sys.dbms_lob.getlength(FILE_BLOB) FILE_BLOB,
       FILE_DESCRIPTION,
       FILE_TAGS,
       CREATION_DATE,
       CREATED_BY,
       SHARED_WITH
  from DOCUMENTS

• Seleziona il Page Item FILE_BLOB

• Imposta il Type a Download BLOB

• Vai alla sezione BLOB Attributes e configura le seguenti opzioni
  • Table Name: DOCUMENTS
  • BLOB Column: FILE_BLOB
  • Primary Key Column 1: ID
  • Mime Type Column: FILE_MIMETYPE
  • Filename Column: FILE_NAME
  • Last Updated Column: CREATION_DATE
  • Character Set Column: FILE_CHARSET

Step 5: esegui l’applicazione

• Esegui la preview dell’applicazione.
• Inizialmente non ci sarà nessun file caricato nell’applicazione. Clicca sul bottone Create

• Seleziona un file dal PC e premi Create per salvare il file nel database

• Il record viene salvato nel database ed il file viene caricato all’interno della tabella DOCUMENTS nella colonna FILE_BLOB.
• Come avrai notato, APEX ha automaticamente salvato il nome del file (colonna File Name) o il tipo file (colonna File Mimetype)

• Cliccando sul link Download è possibile scaricare il file nel proprio PC

Come implementare la gestione dei tags

I tags sono delle parole chiave che vengono associate ad a un’informazione o ad un contenuto.

Ad esempio, i post che pubblichi attraverso un social media possono essere arricchiti tramite l’uso di tags e parole chiave specifiche utili sia per contestualizzare meglio il contenuto ma anche per classificarlo e indicizzarlo meglio.

I tag sono generalmente scelti in base a criteri informali e personalmente dagli autori del contenuto specifico.

Tornando alla nostra applicazione di gestione dei files, potrebbe essere interessante implementare un modo per taggare (e quindi classificare) i file che vengono caricati.

Vediamo insieme come fare partendo dalla Form Page.

• Apri la Form Page e seleziona il campo PX_FILE_TAGS

• Seleziona come Type l’opzione Popup LOV

• Vai in Settings ed imposta le seguenti proprietà
  • Display As: Inline Popup
  • Multiple Values: Yes
  • Separator: scegli il carattere che preferisci. Il default è ‘:’
  • Manuale Entry: Yes
  • Search as You Type: Yes

• Vai alla sezione List of Values e configura la LOV nel seguente modo:
  • Type: SQL Query
  • SQL Query: inserisci la query seguente

select tag from document_tags

• Clicca su Page Processing

• Crea un nuovo Processo di nome Save Tags

• Configura il processo Save Tags in questo modo
  • Type: Execute Code
  • Language: PL/SQL
  • PL/SQL Code: copia il seguente script ricordando si sostituire il Page Item P2_FILE_TAGS con quello che hai definito nella Form Page

INSERT INTO document_tags
(SELECT file_tag
 FROM   (SELECT Regexp_substr(:P2_FILE_TAGS, '[^:]+', 1, LEVEL)
                file_tag
         FROM   dual
         CONNECT BY LEVEL <= Regexp_count(:P2_FILE_TAGS, ':')
                             + 1)
 WHERE  NOT EXISTS (SELECT 1
                    FROM   document_tags
                    WHERE  tag = file_tag)); 

• Esegui la Preview dell’applicazione e clicca sul link Edit

• Vai al campo File Tags, inserisci un tag e premi Invio. Oracle APEX appenderà il nuovo tag alla Multi-Select LOV che abbiamo creato. Quando hai fatto salva il record premendo Apply Changes

• Nel campo FILE_TAGS della tabella DOCUMENTS viene salvata una stringa ottenuta come concatenazione dei tags che ho inserito

Come gestire la visibilità dei files

Quello che abbiamo creato fino a questo momento è una applicazione documentale che consente di archiviare files e documenti che possono essere consultati da chiunque abbia accesso all’applicazione.

Tuttavia nella realtà è probabile che tu debba gestire diversi livelli di visibilità affinché utenti specifici possano consultare solo i documenti di proprio interesse.

Ad esempio, potresti creare diversi gruppi (es. Sales Team, Operation Team, Service Team, ecc.) e tramite uno o più attributi aggiuntivi definiti a livello di record DOCUMENTS potresti gestire la loro visibilità da parte di gruppo utenti specifico.

Ovviamente quello che ti ho appena descritto è un possibile scenario ma non è detto che sia l’unico ed ovviamente dipende strettamente dalle specifiche che hai.

In quest’ultima parte di questo tutorial voglio solo darti un’idea su come gestire la visibilità dei documenti.

Si tratta di uno scenario ben preciso che potrebbe non essere adatto alle tue esigenze specifiche ma che, credo, può esserti utile per avere uno spunto di riflessione.

Scenario di esempio

Supponiamo che nella nostra applicazione di gestione file, tutti gli utenti possono caricare, aggiornare e cancellare i propri files e documenti.

Un utente può condividere i propri documenti con altri utenti dell’applicazione.

Ciascun utente, quindi, può vedere solo i propri files (quelli che ha personalmente caricato) ed eventualmente quelli che sono stati condivisi con lui.

Attributo Shared Width

Prima di tutto configuriamo la Form Page per gestire il campo di sharing del documento

• Apri la definizione della Form Page e seleziona il Page Item PX_SHARED_WITH
• Configura il campo PX_SHARED_WITH come di tipo Popup LOV

• Nella sezione Settings imposta le seguenti opzioni
  • Display As: Inline Popup
  • Multiple Values: Yes
  • Manual Entry: No
  • Search as You Type: Yes

• Vai alla sezione List Of Values per configurare la lista valori utenti abilitati all’uso dell’applicazione e con i quali sarà possibile condividere i documenti.
• Alcune considerazioni:
  • Il tipo di LOV da usare dipende dal tipo di accesso che è stato configurato per l’applicazione corrente.
  • Ad esempio, se utilizzi lo schema di autenticazione standard di Oracle APEX puoi usare la query seguente:

SELECT first_name
       ||' '
       ||last_name                         display_value,
       apex_workspace_apex_users.user_name return_value
FROM   apex_workspace_apex_users,
       apex_appl_acl_user_roles
WHERE  apex_workspace_apex_users.is_admin = 'No'
       AND apex_workspace_apex_users.user_name =
           apex_appl_acl_user_roles.user_name
       AND apex_appl_acl_user_roles.application_id = v('APP_ID'); 

• Esegui la preview dell’applicazione per testare il risultato

Gestione della visibilità

• Accedi all’Interactive Report Page

• Seleziona il componente Interactive Report e modifica la query con la seguente

SELECT id,
       file_name,
       file_mimetype,
       file_charset,
       sys.dbms_lob.Getlength(file_blob) FILE_BLOB,
       file_description,
       file_tags,
       creation_date,
       created_by,
       shared_with,
       (case when instr(shared_with, v('app_user')) > 0 then 'Y' else 'N' end) shared_document_flag,
       (case when created_by = v('app_user') then 'Y' else 'N' end) owned_document_flag
FROM   documents
WHERE  ( created_by = v('app_user') OR instr(shared_with, v('app_user')) > 0 ) 
 

• Eseguiamo la preview collegandoci con l’utente mario.rossi@appin5minuti.it
• Il file test_file_mario_rossi.txt è stato condiviso con l’utente giuseppe.verdi@appin5minuti.it

• Effettuiamo il logout e colleghiamo con l’utente giuseppe.verdi@appin5minuti.it che avrà l’accesso al medesimo file

• Effettuiamo il logout e colleghiamo con l’utente sara.gialli@appin5minuti.it. In questo caso l’utente non ha accesso a nessun file condiviso quindi non vedrà nulla nella propria home page