Titulus Web Services 3.10

In questo documento si descrive la piattaforma dei Web Service esposti da Titulus XML. Vengono descritte le modalità per la connessione all’applicativo, nonché la ricerca, modifica e registrazione di documenti.

• Java DOC dei Web Service.

I servizi esposti sono Titulus, per l'accesso all'archivio dei documenti, e Acl (Access Control List), per l'accesso all'archivio degli utenti e dei loro diritti.
Le rispettive URL hanno la seguente struttura:

http://<host>:<port>/titulus_ws/services/Titulus
http://<host>:<port>/titulus_ws/services/Acl

E' possibile anche invocare una servlet di presentazione, che mostra un elenco dei metodi esposti dai due servizi ed espone i link per la visualizzazione del loro WSDL e del manuale.
L'URL della servlet è il seguente:

http://<host>:<port>/titulus_ws/services

I web service di Titulus sono indipendenti dall'autenticazione usata. E' quindi possibile impiegare la Basic Authentication di Tomcat, Shibboleth o altro.

Il Web Service espone una serie di porte d’accesso per la registrazione di nuovi documenti e la consultazione della base dati.
Di seguito riportiamo l’elenco dei metodi principali con una breve descrizione:

• init(): Effettua la connessione a Titulus/ACL, caricando i diritti di accesso alla base dati dell'utente indicato nei parametri del metodo. Lo scope della chiamata deve essere impostato a “session”. Le chiamate agli altri metodi esposti dal servizio falliscono se prima non è stata effettuata una init.

• executeQuery()/executeQueryRH()/executeQueryRHA(): Effettua la ricerca dei termini espressi nella query secondo uno dei criteri impostati ed eventualmente raffinando rispetto all'esito di una ricerca precedente.
• getSearchOption(): Recupera le opzioni di ricerca correntemente impostate.
• setSearchOption(): Imposta le opzioni di ricerca.
• getCurrentSet(): Recupera il Result-Set corrente nell’ambito di una vista gerarchica (XML) rappresentativa della storia delle ricerche effettuate.
• setCurrentSet(): Imposta il Result-Set corrente.
• sortCurrentSet(): Riordina il Result-Set corrente.
• detachSet(): Rimuove il/i Result-Set specificati dalla storia delle ricerche effettuate.
• detachAll(): Rimuove l’intera storia delle ricerche effettuate.
• setUnexplodedSet(): Congela lo stato di esplosione o meno dei rami della rappresentazione gerarchica della storia delle ricerche.

• firstTitlePage(): Effettua il posizionamento sulla prima pagina dei titoli dei documenti del Result-Set corrente.
• nextTitlePage(): Effettua il posizionamento sulla pagina successiva dei titoli dei documenti del Result-Set corrente.
• prevTitlePage(): Effettua il posizionamento sulla pagina precedente dei titoli dei documenti del Result-Set corrente.
• lastTitlePage(): Effettua il posizionamento sull'ultima pagina dei titoli dei documenti del Result-Set corrente.
• currentTitlePage(): Effettua il posizionamento sulla pagina corrente dei titoli dei documenti del Result-Set corrente.
• titlePage(): Effettua il posizionamento diretto sulla pagina dei titoli specificata (dei documenti del Result-Set corrente).

• loadDocument(): Effettua il caricamento, tramite numero fisico, di una Information Unit con possibilità di locking.
• loadFirstDocument(): Effettua il caricamento della prima Information Unit del Result-Set corrente.
• loadNextDocument(): Effettua il caricamento della successiva Information Unit del Result- Set corrente.
• loadLastDocument(): Effettua il caricamento dell'ultima Information Unit del Result-Set corrente.
• loadPrevDocument(): Effettua il caricamento della precedente Information Unit del Result- Set corrente.

• loadParentDocument(): Effettua il caricamento del documento genitore di quello corrente sulla base di una relazione gerarchica impostata in fase di costituzione dell’archivio.
• loadChildDocument(): Effettua il caricamento di un documento figlio di quello corrente sulla base di una relazione gerarchica impostata in fase di costituzione dell'archivio.
• loadPrevSiblingDocument(): Effettua il caricamento del documento fratello-precedente di quello corrente sulla base di una relazione gerarchica impostata in fase di costituzione dell'archivio.
• loadNextSiblingDocument(): Effettua il caricamento del documento fratello-successivo di quello corrente sulla base di una relazione gerarchica impostata in fase di costituzione dell'archivio.

• saveDocument(): Effettua la registrazione di un nuovo documento.
• saveModifiedDocument(): Effettua il salvataggio di un documento modificato.
• deleteDocument(): Effettua, ove possibile, la rimozione di un documento.
• unlockDocument(): Effettua lo sblocco di un documento.
• grantRight(): Consente di assegnare un documento in Copia Conoscenza (CC), in Conferenza Di Servizi (CDS) o di modificare il Responsabile di Procedimento Amministrativo (RPA).
• denyRight(): Consente la rimozione di un utente dalla lista dei CC (Copia Conoscenza) o CDS (Conferenza Di Servizi) di un documento.
• postIt(): Consente l'inserimento di un postit in un documento.
• cancelDocument(): Consente, ove possibile, di annullare un documento.
• applyRegistrationToDraft()/applyRegistrationToDraftWithNRec(): Consente di protocollare un documento bozza.
• applyRegistrationMark(): Consente di applicare ad un documento la segnatura di protocollo.
• getRegistrationMark(): Restituisce la segnatura di protocollo di un documento.

• getIndexTitle(): Consente di recuperare i dati associati ad una voce d'indice.
• newIndexTitle(): Consente la creazione di una nuova voce d'indice.
• modifyIndexTitle(): Effettua la modifica di una voce d'indice.
• unlockIndexTitle()/unlockIndexTitleWithCod(): Consente di sbloccare una voce d'indice precedentemente bloccata dallo stesso operatore.
• deleteIndexTitle()/deleteIndexTitleWithCod(): Consente la rimozione di una voce d'indice.

• getAttachment(): Effettua il download di un allegato di un Information Unit (MIME o DIME).
• checkInContentFiles()/checkInExistingContentFiles(): Effettua l'upload (previo checkOutContentFile e quindi con versioning) di uno o più allegati (anche immagini) da associare ad un Information Unit (MIME o DIME).
• checkOutContentFile(): Effettua il download (eventualemente per apportare modifiche di versioning) di un allegato di un Information Unit (MIME o DIME).
• unlockContentFile(): Effettua lo sblocco (unlocking) di un allegato di un Information Unit precedentemente prenotato (checkOutContentFile).
• validateContentFile(): Verificare la validità dell'impronta (SHA1) dei file ed immagini associate ad un Information Unit.
• uploadAttachment(): Effettua l'upload nella banca dati di uno o più allegati (non richiede un preventivo checkout).

• newFolder(): Effettua la creazione di un nuovo fascicolo.
• newSubFolder(): Effettua la creazione di un nuovo sottofascicolo.
• assignFolderRPA(): Effettua il trasferimento di un fascicolo da un RPA ad un altro.
• addInFolder(): Effettua l'inserimento di un documento in un fascicolo.
• removeFromFolder(): Effettua la rimozione di un documento da un fascicolo.
• addLinkToFolder(): Effettua la creazione di un collegamento tra un documento ed un fascicolo.
• deleteLinkToFolder(): Effettua la rimozione del collegamento tra un documento ed un fascicolo.
• getFolderContent(): Effettua il recupero dei documenti contenuti e collegati ad un fascicolo.
• getFolderHierarchy(): Effettua il recupero della gerarchia (in forma sintetica) di sottofascicoli e documenti contenuti in un fascicolo.
• getFolder(): Effettua il recupero dei metadati XML rappresentativi di un fascicolo.
• closeFolder(): Effettua la chiusura di un fascicolo.
• openFolder(): Effettua la riapertura di un fascicolo.
• deleteFolder(): Effettua la rimozione di un fascicolo ma non del suo contenuto.

• getDesktop(): Implementa la funzionalità della scrivania producendo opportuni Result-Set (Personali/rpa, Personali/cc, …, Ufficio/uor, Ufficio/cc, …)
• getCustomDesktop(): Implementa la funzionalità della scrivania sulla base di criteri di ricerca impostati dal chiamante.

• getWorkflowId(): Effettua il recupero delle eventuali istanze di workflow, attive o meno, associate ad un documento.
• getWorkflowAction(): Effettua il recupero delle eventuali azioni disponibili per una determinata istanza di workflow associata ad un documento.
• startWorkflow(): Effettua l'attivazione di un workflow associato ad un documento.
• continueWorkflow(): Effettua l'esecuzione di una specifica azione associata ad un istanza di workflow relativa ad un documento.

• getWsRelease(): Restituisce le informazioni sulla release del servizio.

• getUser()/getUserWithNum(): Effettua il recupero delle informazioni relative ad una persona interna.
• addUser(): Effettua l'inserimento di una nuova persona interna.
• modifyUser()/modifyUserWithNum(): Effettua la modifica di una persona interna.
• removeUser()/removeUserWithNum(): Effettua la rimozione di una persona interna.
• unlockUser()/unlockUserWithNum(): Effettua lo sblocco di una persona interna precedentemente bloccato per modifica.
• setUserProfile()/setUserProfileWithNum(): Effettua l'assegnamento di un profilo di diritti ad una persona interna.
• updateUsersProfile(): Effettua l'aggiornamento dei diritti associati ad ogni persona interna selezionata tramite la chiave di profilo specificata.
• checkRight(): Verifica che un utente (persona interna) possieda o meno uno specifico diritto.
• getProfile()/getProfileWithKey(): Effettua il recupero dei metadati XML associati ad un profilo.
• addProfile(): Effettua l'inserimento di un nuovo profilo di diritti.
• modifyProfile()/modifyProfileWithKey(): Effettua la modifica di un profilo di diritti.
• removeProfile()/removeProfileWithKey(): Effettua la rimozione di un profilo di diritti.
• unlockProfile()/unlockProfileWithKey(): Effettua lo sblocco di un profilo precedentemente bloccato per modifica.
• getRole()/getRoleWithName(): Effettua il recupero dei metadati XML (record) relativi ad un ruolo (o mansione).
• addRole(): Effettua l'inserimento di un nuovo ruolo (generalmente referenziato dall'elemento mansione di una persona interna)
• modifyRole()/modifyRoleWithName(): Effettua la modifica di un ruolo.
• removeRole()/removeRoleWithName(): Effettua la rimozione di un ruolo.
• unlockRole()/unlockRoleWithName(): Effettua lo sblocco di un ruolo precedentemente bloccato per modifica.
• getInternalStructure()/getInternalStructureWithCod(): Effettua il recupero di una struttura interna (ufficio interno all'area organizzativa omogenea di riferimento).
• addInternalStructure(): Effettua l'inserimento di una nuova struttura interna.
• modifyInternalStructure()/modifyInternalStructureWithCod(): Effettua la modifica dei dati (record) relativi ad una struttura interna.
• removeInternalStructure()/removeInternalStructureWithCod(): Effettua la rimozione di una struttura interna.
• unlockInternalStructure()/unlockInternalStructureWithCod(): Effettua lo sblocco di una struttura interna precedentemente bloccata per modifica.
• getExternalUser()/getExternalUserWithNum(): Effettua il recupero del record relativo ad un utente esterno.
• addExternalUser(): Effettua l'inserimento di un nuovo utente esterno.
• modifyExternalUser()/modifyExternalUserWithNum(): Effettua la modifica dei dati (record) relativi ad un utente esterno.
• removeExternalUser()/removeExternalUserWithNum(): Effettua la rimozione di un utente esterno.
• unlockExternalUser()/unlockExternalUserWithNum(): Effettua lo sblocco di un utente esterno precedentemente bloccato per modifica.
• getExternalStructure()/getExternalStructureWithCod(): Effettua il recupero di una struttura esterna (ufficio esterno all'area organizzativa omogenea di riferimento).
• addExternalStructure(): Effettua l'inserimento di una nuova struttura esterna.
• modifyExternalStructure()/modifyExternalStructureWithCod(): Effettua la modifica dei dati (record) relativi ad una struttura esterna .
• removeExternalStructure()/removeExternalStructureWithCod(): Effettua la rimozione di una struttura esterna.
• unlockExternalStructure()/unlockExternalStructureWithCod(): Effettua lo sblocco di una struttura esterna precedentemente bloccato per modifica.

Per una descrizione dettagliata dei metodi e dei relativi parametri, si rimanda al Java Doc di riferimento. Segue una descrizione sommaria delle principali funzionalità messe a disposizione dal servizio.

Invocando il metodo init() si stabilisce una connessione con Titulus e si attiva una nuova sessione di lavoro utilizzata per tutte le richieste provenienti dallo stesso client (a carico del client rimane la notifica al server dell’intenzione di avvalersi delle sessioni, impostando lo scope di chiamata a “session”).
Di seguito si riporta un esempio in linguaggio Java, realizzato con la libreria Axis. Gli stub client usati (nel codice ”titulus” e ”acl”), sono stati generati a partire dal wsdl dei servizi, mediante il tool WSDL2Java.
Nell'esempio vengono effettuate le connessioni all'archivio centrale e ad ACL con l'utente “test-ws” (che deve essere registrato in ACL con login “test-ws”).

TitulusServiceLocator tsl = new TitulusServiceLocator();
AclServiceLocator     asl = new AclServiceLocator();
 
// impostazione dello scope di chiamata a "session"
tsl.setMaintainSession(true);
asl.setMaintainSession(true);
 
Titulus_PortType titulus = tsl.getTitulus();
Acl_PortType     acl     = asl.getAcl();
 
// impostazione della login per l'accesso autenticato al servizio
((TitulusSoapBindingStub)titulus).setUsername("prova");
((TitulusSoapBindingStub)titulus).setPassword("XXX");
((AclSoapBindingStub)acl).setUsername("prova");
((AclSoapBindingStub)acl).setPassword("XXX");
 
...
 
titulus.init(null, null, "test-ws", null, "xdocwaydoc", -1, -1);
 
...
 
acl.init(null, null, "test-ws", null);
 
...

In caso di fallimento viene sollevata una “Exception” con una descrizione testuale della causa dell’errore (da intercettare lato client).

Una volta attivata la connessione, per consultare il database è sufficiente invocare il metodo executeQuery(). Tramite questo metodo è possibile ricercare un insieme di dati che rispondono a determinati criteri di ricerca. Il primo parametro rappresenta la query espressa secondo la sintassi di eXtraWay:

([NON] [<canale di ricerca>]=<termini>) [<operatore> ([<canale di ricerca>]=termini) …]

Dove:

• <canale di ricerca>: individua l’alias al percorso XPath che rappresenta l’elemento o l’attributo su cui compiere la ricerca
• <termini>: una o più parole separate tramite operatore booleano “OR” o “AND” (accettata anche la versione italiana “O” o “E”). Se non si inserisce alcun operatore booleano vengono ricercati solo record aventi tali parole adiacenti. È possibile usare wildcard quali l’asterisco (“*”) in coda ad una radice di parola o il punto interrogativo (“?”) in qualsiasi punto della parola.
  Se il campo consente una ricerca su un intervallo di valori (per es. una data), è possibile indicare tale intervallo con la notazione {val1|val2} (per es. {01/01/2011|31/01/2011}).
  L'intervallo può anche essere aperto: {|val2} (fino a val2) o {val1|} (a partire da val1).
• <operatore>: operatore booleano AND, OR o ADJ
• [NON] : (elemento opzionale) negazione dell’espressione che segue.

Esempi:

• Ricerca del documento con numero di protocollo “2004-UNBOCLE-0000437”: ([docnumprot]=2004-UNBOCLE-0000437)
• Ricerca dei documenti del 2004 con oggetto che contiene “offerta Titulus 97”: ([doc_anno]=2004) AND ([doc_oggetto]=offerta Titulus 97)
• Ricerca dei documenti in cui Mario Rossi figura come RPA: ([doc_rifinternirifnomepersona]=” Rossi Mario”) adj ([doc_rifinternirifdiritto]=RPA)
• Ricerca dei documenti protocollati dal 1 Gennaio 2011 al 31 Gennaio 2011: ([docdataprot]={01/01/2011|31/01/2011})
• Ricerca dei documenti dell'albo ufficiale di ateneo da pubblicare il 2 Marzo 2011: ([/doc/repertorio/@cod/]=“ALBO”) AND ([/doc/pubblicazione/@dal/]={|02/03/2011}) AND ([/doc/pubblicazione/@al/]={02/03/2011|})

I principali canali di ricerca attivi sono i seguenti:

• [docnumprot]: numero protocollo nella forma <anno>-<cod.amm.+cod.aoo>-<numero 7 cifre>
• [doc_repertorionumero]: numero di repertorio nella forma <codice>^<cod.amm.+cod.aoo>-<anno><numero 7 cifre>
• [doc_tipo]: tipo documento (“partenza” o “arrivo” o “interno” o “varie”)
• [doc_anno]: anno
• [doc_bozza]: flag che individua le bozze di documento (“si”) [doc_codammaoo]: codice che individua in maniera univoca una AOO (concatenazione di codice amministrazione e codice AOO)
• [docdataprot]: data di protocollo (espresso nella forma aaaammgg oppure “gg/mm/aaaa”)
• [doc_dataarrivo]: data di arrivo di un documento (espresso nella forma aaaammgg oppure “gg/mm/aaaa”)
• [doc_annullato]: flag che individua un documento annullato (“si”)
• [doc_repertoriocod]: codice repertorio
• [doc_oggetto]: oggetto del documento
• [doc_classif]: classificazione del documento (es: VII/3 – varie) [doc_classifcod]: codice classificazione (03/04) [doc_filesfiletesto]: testo estratto dai file associati al documento
• [doc_note]: note registrate nel documento
• [doc_allegato]: info sugli allegati
• [doc_rifesternirifnome]: nome destinatario o mittente esterno (a seconda della tipologia di documento)
• [docrifesternirifdataprot]: data protocollo del documento per il mittente
• [docrifesternirifnprot]: numero protocollo del documento per il mittente
• [doc_rifesternirifreferentenominativo]: nome firmatario (se arrivo) o cortese attenzione (se partenza)
• [doc_postit]: testo nel post-it
• [doc_postitoperatore]: nome operatore che ha registrato il post-it
• [doc_autore]: autore per documenti non protocollati

Per una descrizione più dettagliata delle opzioni di ricerca si rimanda al documento: Sintassi di ricerca linguaggio nativo eXtraWay.

E’ inoltre previsto il passaggio di ulteriori parametri per:

• raffinare una ricerca sull’esito di una selezione precedente, avendo a disposizione dei metodi che restituiscono la storia delle ricerche effettuate sotto forma di vista gerarchica (XML). Ad ogni ricerca è quindi associato un Result-Set identificato univocamente da un nome logico: è anche possibile comporre query di ricerca specificando tra parentesi quadre il nome logico associato ad un Result-Set (es. [A] and [B] or [C]).
• stabilire la modalità di ordinamento (vedi Ordinamento ricerca)
• attivare una ricerca estesa alla forma maschile/femminile e singolare/plurale
• attivare la ricerca per somiglianza di termini
• attivare una ricerca probabilistica, che opera in modalità analoga ai principali motori di ricerca

Di seguito la specifica XML per impostare le opzioni di ricerca attraverso il metodo setSearchOprion():

   <?xml version="1.0"?>
   <SearchOption>
    <TermPresence>
     <AnyPosition active="true" />
     <WordDistance active="false" value="2" order="true" />
     <AtLeastOneTerm active="false" />
     <IgnoreStopList active="false" />
    </TermPresence>
    <ServerExtension>
     <GenderAndNumber active="false" />
     <Ranking active="false" />
     <Probabilistic active="false" />
     <SimilarDocument active="false" key="null" />
     <SimilarTerm active="false" error="1" character="3" prefix="1" />
    </ServerExtension>
    <ThesaurusExtension />
    <ApplicationLevel>
     <SearchComposition active="true" operator="and" />
     <SimilarTermProposal active="false" key="null" void_result="true" />
    </ApplicationLevel>
   </SearchOption>

• AnyPosition: significativa per le ricerche effettuate con l'operatore di adiacenza (ADJ), vengono selezionate le Information Unit che presentano i termini cercati in qualunque posizione, ADJ viene rilassato in AND.
• WordDistance: significativa per le ricerche effettuate con l'operatore di adiacenza (ADJ), vengono selezionate le Information Unit che presentano i termini cercati non più distanti del valore espresso dall'attributo “value” ed eventualmente nello stesso ordine espresso nella frase di ricerca (order=true).
• AtLeastOneTerm: è quella che viene definita ricerca probabilistica senza ranking (nessun ordinamento per peso), in sostanza la frase di ricerca risulta “appiattita”, tutti gli operatori mutano in OR.
• IgnoreStopList: normalmente nelle ricerche vengono ignorati articoli e preposizioni, alzando tale flag si chiede di rimuovere tale filtraggio.

• GenderAndNumber: si chiede al server Extraway di operare ricerche effettuando estensioni per genere e numero (maschile/femminile/singolare/plurale).
• Ranking: si chiede al server Extraway di operare ordinamenti (sulla base delle ricerche effettuate) in base al “peso” di ogni Information Unit.
• Probabilistic: è un ranking in cui la frase di ricerca risulta “appiattita”, tutti gli operatori mutano in OR.
• SimilarDocument: si chiede al server Extraway di operare ricerche estese a documenti (Information Unit) simili, la similitudine è decisa sulla base del contenuto di un canale specificato nell'attributo “key” (search_alias).
• SimilarTerm: si chiede al server Extraway di operare ricerche considerando anche termini simili a quelli espressi nella query. Il criterio di similitudine viene deciso in base al valore degli attributi: “error”, “character” e “prefix”.

Esempio:
...
<SimilarTerm active="true" error="1" character="3" prefix="1"/>
...

Il primo carattere del termine cercato deve risultare lo stesso (prefix=1) e si ammette un carattere errato ogni tre (error=1 e character=3), quindi su parole di quattro, cinque e sei caratteri si ammettono due errori, su parole di sette, otto e nove se ne ammettono tre ecc.

• SearchComposition: ha solo il fine di memorizzare nel pannello delle opzioni di ricerca lo specifico operatore con cui comporre i criteri di ricerca tra canali differenti.
• SimilarTermProposal: se è attiva le ricerca per termini simili si predispone la possibilità di proporre alternative alle ricerche effettuate su un dato canale (key). La proposta di alternative può avvenire solo nel caso di esito nullo della ricerca (void_result=true) o anche nel caso di esito nullo (void_result=false).

L’esito positivo di una ricerca produce una “busta XML” (envelope) contenente un estratto (titoli) dei primi N documenti rispondenti ai requisiti di ricerca. In alternativa, utilizzando il metodo getCurrentSet() è possibile ottenere una vista gerarchica (sempre in formato XML) della storia delle ricerche effettuate. Su tale vista gerarchica è possibile intervenire in raffinamento o rimozione di rami corrispondenti a ricerche non più ritenute interessanti.
Per navigare sui titoli di tutti i documenti trovati si fa uso dei metodi firstTitlePage(), nextTitlePage(), prevTitlePage(), lastTitlePage(): ognuno di essi restituisce un envelope XML contenente un estratto (risultati di sintesi) di un insieme di N documenti, ove la dimensione N di una pagina di titoli è un parametro configurabile.
Per navigare sui singoli documenti trovati si fa uso dei metodi loadFirstDocument(), loadNextDocument(), loadPrevDocument(), loadLastDocumento(): ognuno di essi restituisce un envelope XML contenente i metadati di registrazione di un documento.
È prevista anche una modalità di caricamento diretto di un documento, sulla base di un identificativo fisico univoco (idUnit): loadDocument(idUnit); il numero fisico di ogni documento è tra le informazioni presenti nei risultati di sintesi (titoli).

Ad ogni file (allegato multimediale) associato al metadato XML di un documento viene attribuito un id univoco di archivio. Il percorso XPath per recuperare tale identificativo nell'ambito del metadato XML è:

/doc/files/xw:file/@name    (per i file)
/doc/immagini/xw:file/@name (per le immagini)

All’interno di /doc/files e di /doc/immagini possono essere incapsulati 0 o più riferimenti ad allegati.
Per richiedere il download di uno di questi file si invoca il metodo getAttachment() (per i dettagli si rimanda al javadoc).
Di seguito si riporta un esempio in linguaggio Java, realizzato con la libreria Axis. Lo stub client usato (nel codice ”this.titulus”), è stato generato a partire dal wsdl del servizio, mediante il tool WSDL2Java.
Notare che l'allegato restituito da getAttachment() è contenuto nella risposta SOAP arrivata al client.

import org.apache.axis.attachments.AttachmentPart;
import org.dom4j.Document;
import org.dom4j.DocumentHelper;
 
...
 
...
 
this.titulus.init(null, null, "test-ws", null, "xdocwaydoc-test", -1, -1);
...
 
// loading document 00019099
this.titulus.executeQuery("[docnrecord]=00019099", null, false, false, false, false, -1);
 
String   resp    = this.titulus.loadFirstDocument(false, false, false);
Document respDoc = DocumentHelper.parseText(resp);
 
// checking attachment
List files = respDoc.selectNodes("//doc/files/*[name()='xw:file'][not(@der_from)]"); 
 
for (int j = 0; j < files.size(); j++) {
    Element file   = (Element)files.get(j);
    String  fileId = file.attributeValue("name", "");
 
    // downloading file
    this.titulus.getAttachment(fileId, false);
 
    Object[] attachments = ((TitulusSoapBindingStub)this.titulus).getAttachments();
 
    // attachment size: ((AttachmentPart)attachments[0]).getSize()
    // attachment name: ((AttachmentPart)attachments[0]).getAttachmentFile()
 
    // getting file's bytes
    ByteArrayOutputStream baos = new ByteArrayOutputStream();
 
    ((AttachmentPart)attachments[0]).getDataHandler().writeTo(baos);
 
    baos.flush();
    baos.close();
 
    byte[] attachment = baos.toByteArray();
    ...
}

La registrazione di un nuovo documento è gestita attraverso la chiamata al metodo saveDocument(), al quale inviare il documento (i suoi metadati) in formato XML. Il nuovo documento prima di essere salvato subisce un processo di validazione per mezzo di un modulo DTD (Document Type Definition) e successivamente una fase di controllo semantico per verificarne la consistenza in funzione della tipologia indicata. Di seguito riportiamo la specifica di inserimento sotto forma di modulo DTD:

<!ENTITY % proprietarioDTD SYSTEM "[PATH_PROPRIETARIO]/proprietario.dtd">
%proprietarioDTD;

<!ELEMENT doc ( visibilita?,
                prot_differito?, 
                repertorio?, 
                autore?, 
                minuta?, 
                oggetto, 
                tipologia?, 
                mezzo_trasmissione?, 
                classif?, 
                note?, 
                riferimenti?, 
                xlink*, 
                keywords?, 
                allegato*, 
                voce_indice?, 
                rif_interni, 
                rif_esterni?, 
                originale?, 
                extra? )>

<!ATTLIST doc      tipo (arrivo | partenza | interno | varie) #REQUIRED
            cod_amm_aoo CDATA #IMPLIED
                   anno CDATA #IMPLIED
              data_prot CDATA #IMPLIED
               num_prot CDATA #IMPLIED
              agli_atti CDATA #IMPLIED
              annullato (si | no) 'no'
                 scarto (01 | 05 | 10 | 99) '99'
data_valutazione_scarto CDATA #IMPLIED
                  bozza (si | no) #IMPLIED
            data_seduta CDATA #IMPLIED>

<!ELEMENT visibilita EMPTY>
<!ATTLIST visibilita cod (R | A | P) #IMPLIED
                    tipo (Riservato | Altamente_confidenziale)  #REQUIRED
                 fino_al CDATA #IMPLIED>

<!ELEMENT prot_differito (#PCDATA)>
<!ATTLIST prot_differito data_arrivo CDATA #REQUIRED>

<!ELEMENT repertorio (#PCDATA)>
<!ATTLIST repertorio cod CDATA #REQUIRED
                  numero CDATA #IMPLIED>
                  
<!ELEMENT autore (#PCDATA)>
<!ATTLIST autore xml:space (default|preserve)  'preserve'>

<!ELEMENT minuta ( classif, mittente? )> 
<!ATTLIST minuta scarto  (01 | 05 | 10 | 99) '99'>

<!ELEMENT classif (#PCDATA)>
<!ATTLIST classif xml:space (default|preserve)  'preserve' cod CDATA #REQUIRED>
 
<!ELEMENT mittente EMPTY> 
<!ATTLIST mittente  nome_uff CDATA #REQUIRED
                nome_persona CDATA #REQUIRED
                     cod_uff CDATA #IMPLIED
                 cod_persona CDATA #IMPLIED>
                 
<!ELEMENT oggetto (#PCDATA)>
<!ATTLIST oggetto xml:space (default | preserve) 'preserve'>

<!ELEMENT tipologia (#PCDATA)>
<!ATTLIST tipologia cod CDATA #REQUIRED>

<!ELEMENT mezzo_trasmissione (#PCDATA)>
<!ATTLIST mezzo_trasmissione cod CDATA #REQUIRED
                           costo CDATA #IMPLIED
                          valuta CDATA #IMPLIED>

<!ELEMENT note (#PCDATA)>
<!ATTLIST note  xml:space (default | preserve) 'preserve'>

<!ELEMENT riferimenti (#PCDATA)>
<!ATTLIST riferimenti xml:space (default | preserve) 'preserve'>

<!ELEMENT xlink (#PCDATA)>
<!ATTLIST xlink href CDATA
           xml:space #REQUIRED (default | preserve) 'preserve'>
           
<!ELEMENT keywords (#PCDATA)>
<!ATTLIST keywords  xml:space (default | preserve) 'preserve'>

<!ELEMENT allegato (#PCDATA)>
<!ATTLIST allegato  xml:space (default | preserve) 'preserve'>

<!ELEMENT voce_indice (#PCDATA)>
<!ATTLIST voce_indice xml:space (default | preserve)  'preserve'>

<!ELEMENT rif_interni (rif_interno)+>

<!ELEMENT rif_interno EMPTY>
<!ATTLIST rif_interno diritto (RPA | RPAM | CC | CDS ) #REQUIRED
                 nome_persona CDATA #REQUIRED
                     nome_uff CDATA #REQUIRED
                  cod_persona CDATA #IMPLIED
                      cod_uff CDATA #IMPLIED>
                      
<!ELEMENT rif_esterni (rif_esterno)+>

<!ELEMENT rif_esterno (nome, indirizzo, referente?)>
<!ATTLIST rif_esterno n_prot CDATA #IMPLIED
                   data_prot CDATA #IMPLIED
            copia_conoscenza CDATA #IMPLIED>
<!ELEMENT nome (#PCDATA)>
<!ATTLIST nome  cod CDATA #IMPLIED
          xml:space (default | preserve)  'preserve'>

<!ELEMENT indirizzo (#PCDATA)>
<!ATTLIST indirizzo xml:space (default | preserve) 'preserve'
                        email CDATA #IMPLIED
                          tel CDATA #IMPLIED
                          fax CDATA #IMPLIED>
<!ELEMENT referente EMPTY>
<!ATTLIST referente nominativo CDATA #REQUIRED
                           cod CDATA #IMPLIED>
                           
<!ELEMENT originale (#PCDATA)>
<!ATTLIST originale xml:space (default | preserve) 'preserve'>

<!ELEMENT extra ANY>
  
<!-- Formato Attributi DATA = aaaammgg -->

Da notare la presenza dell’elemento “extra”, allo scopo di fornire flessibilità nell’inserimento di informazioni di natura proprietaria e non contemplate dalla DTD; ovviamente per continuare a garantire la validazione del documento è necessario dichiarare le informazioni proprietarie in un modulo esterno denominato appunto “proprietario.dtd” e referenziato da quello in questione.
Di seguito riportiamo degli esempi di documenti da inviare per il salvataggio tramite il metodo sopra indicato.

Di seguito si riporta un esempio di estratto XML riferito alla richiesta di registrazione di un documento non protocollato (tipo=varie):

  <doc tipo="varie"
       anno="2004"
       cod_amm_aoo="KONCENT" 
       annullato="no" 
       data_prot="20040612" 
       scarto="99">
    <repertorio cod="RS" numero="RS^KONCENT-20040000006">Rassegna Stampa</repertorio>
    <autore xml:space="preserve">Dante Alighieri</autore>
    <oggetto xml:space="preserve">Invio bozza opera La Divina Commedia</oggetto>
    <tipologia cod="Dichiarazione"/>
    <classif cod="06/04" xml:space="preserve">06/04 - Documentazione</classif>
    <note xml:space="preserve">Note al documento</note>
    <riferimenti xml:space="preserve">Volumi Inferno, Purgatorio, Paradiso</riferimenti>
    <xlink href="http://www.link.it" xml:space="preserve">descrizione link</xlink>
    <allegato xml:space="preserve">0 - nessun allegato</allegato>
    <rif_interni>
      <rif_interno diritto="RPA" 
                   cod_persona="11111" 
                   cod_uff="SI000006" 
                   nome_persona="Ciampi Carlo Azeglio" 
                   nome_uff="Presidenza della Repubblica"/>
      <rif_interno diritto="CC" 
                   cod_persona="3" 
                   cod_uff="00003" 
                   nome_persona="Berlusconi Silvio" 
                   nome_uff="Presidenza Consiglio dei Ministri"/>
    </rif_interni>
  </doc>

Campi valorizzati in automatico dal servizio (solo in assenza di valori preimpostati):

• /doc/@anno
• /doc/@cod_amm_aoo
• /doc/@annullato
• /doc/@data_prot
• /doc/@scarto
• /doc/repertorio/@numero
• / /@xml:space
• /doc/classif
• /doc/allegato
• /doc/rif_interni/rif_interno/@cod_persona
• /doc/rif_interni/rif_interno/@cod_uff

L’elemento “repertorio” non è obbligatorio, tuttavia nel caso di registrazione di un documento appartenente ad un repertorio (ad esempio il repertorio dei verbali), diventa obbligatorio.

Di seguito si riporta un esempio di estratto XML riferito alla richiesta di registrazione di un documento in arrivo (tipo=arrivo):

  <doc tipo="arrivo" 
       anno="2004" 
       data_prot="20040610" 
       cod_amm_aoo="KONCENT" 
       annullato="no"
       num_prot="2004-KONCENT-0000112"
       scarto="99">
    <prot_differito data_arrivo="20040609" xml:space="preserve">
      Data conclusione presentazione domande. Il carico di lavoro ha superato le capacità  
      operative dell'ufficio.
    </prot_differito> 
    <repertorio cod="V_D_CDA" numero="V_D_CDA^KONCENT-20040000134">
      Verbali Consiglio di Amministrazione
    </repertorio>
    <oggetto xml:space="preserve">Richiesta documentazione protocollo informatico</oggetto>
    <tipologia cod="Dichiarazione"/>
    <mezzo_trasmissione cod="Posta Ordinaria"/>
    <classif cod="06/04" xml:space="preserve">06/04 - Documentazione</classif>
    <note xml:space="preserve">Note al documento</note>
    <riferimenti xml:space="preserve">CNIPA – Protocollo Informatico</riferimenti>
    <xlink href="http://www.link.it" xml:space="preserve">descrizione link</xlink>
    <allegato xml:space="preserve">0 - nessun allegato</allegato>
    <rif_interni>
      <rif_interno diritto="RPA"
                   cod_persona="11111" 
                   cod_uff="SI000006" 
                   nome_persona="Ciampi Carlo Azeglio"
                   nome_uff="Presidenza della Repubblica"/>
      <rif_interno diritto="CC" 
                   cod_persona="3" 
                   cod_uff="00003"
                   nome_persona="Berlusconi Silvio"
                   nome_uff="Presidenza Consiglio dei Ministri"/>
    </rif_interni>
    <rif_esterni>
      <rif_esterno data_prot="20040101" n_prot="1243">
        <nome cod="SE000095" xml:space="preserve">Ditta srl</nome>
        <referente cod="PE000928" nominativo="Mario Rossi"/>
        <indirizzo email="mrossi@ditta.it"
                   fax="051 451242" 
                   tel="051 452844"
                   xml:space="preserve">
           Via Manzoni 2 - 40033 Casalecchio di Reno - BO - Italia
        </indirizzo>
      </rif_esterno>
    </rif_esterni>
  </doc>

Campi valorizzati in automatico dal servizio (solo in assenza di valori preimpostati):

• /doc/@anno
• /doc/@cod_amm_aoo
• /doc/@annullato
• /doc/@data_prot
• /doc/@num_prot
• /doc/@scarto
• /doc/repertorio/@numero
• / /@xml:space
• /doc/classif
• /doc/allegato
• /doc/rif_interni/rif_interno/@cod_persona
• /doc/rif_interni/rif_interno/@cod_uff

L’elemento “repertorio” non è obbligatorio, tuttavia nel caso di registrazione di un documento appartenente ad un repertorio (ad esempio il repertorio dei verbali), diventa obbligatorio.

Di seguito si riporta un esempio di estratto XML riferito alla richiesta di registrazione di un documento in partenza (tipo=partenza):

  <doc tipo="partenza"
       anno="2004" 
       data_prot="20040610" 
       cod_amm_aoo="KONCENT" 
       annullato="no"
       num_prot="2004-KONCENT-0000246" 
       scarto="99">
    <repertorio cod="V_D_CDA" numero="V_D_CDA^KONCENT-20040000009">
      Verbali Consiglio di Amministrazione
    </repertorio>
    <oggetto xml:space="preserve">Richiesta documentazione protocollo informatico</oggetto>
    <tipologia cod="Dichiarazione"/>
    <mezzo_trasmissione cod="Posta Ordinaria"/>
    <classif cod="06/04" xml:space="preserve">06/04 - Documentazione</classif>
    <note xml:space="preserve">Note al documento</note>
    <riferimenti xml:space="preserve">CNIPA – Protocollo Informatico</riferimenti>
    <xlink href="http://www.link.it" xml:space="preserve">descrizione link</xlink>
    <allegato xml:space="preserve">0 - nessun allegato</allegato>
    <rif_interni>
      <rif_interno diritto="RPA"
                   cod_persona="11111" 
                   cod_uff="SI000006" 
                   nome_persona="Ciampi Carlo Azeglio"
                   nome_uff="Presidenza della Repubblica"/>
      <rif_interno diritto="CC"
                   cod_persona="3" 
                   cod_uff="00003" 
                   nome_persona="Berlusconi Silvio" 
                   nome_uff="Presidenza Consiglio dei Ministri"/> 
    </rif_interni>
    <rif_esterni>
      <rif_esterno>
        <nome cod="SE000095" xml:space="preserve">Ditta srl</nome>
        <referente cod="PE000928" nominativo="Mario Rossi"/>
        <indirizzo xml:space="preserve">
          Via Manzoni, 2 - 40033 Casalecchio di Reno (BO) - Italia
        </indirizzo>
      </rif_esterno>
      <rif_esterno copia_conoscenza="si">
        <nome cod="SE000095" xml:space="preserve">Ditta srl</nome>
        <referente cod="PE000928" nominativo="Ermete Verdi"/>
        <indirizzo xml:space="preserve">
          Via Manzoni, 2 - 40033 Casalecchio di Reno (BO) - Italia
        </indirizzo>
      </rif_esterno>
    </rif_esterni>
  </doc>

Campi valorizzati in automatico dal servizio (solo in assenza di valori preimpostati):

• /doc/@anno
• /doc/@cod_amm_aoo
• /doc/@annullato
• /doc/@data_prot
• /doc/@num_prot
• /doc/@scarto
• /doc/repertorio/@numero
• / /@xml:space
• /doc/classif
• /doc/allegato
• /doc/rif_interni/rif_interno/@cod_persona
• /doc/rif_interni/rif_interno/@cod_uff

L’elemento “repertorio” non è obbligatorio, tuttavia nel caso di registrazione di un documento appartenente ad un repertorio (ad esempio il repertorio dei verbali), diventa obbligatorio.

Di seguito si riporta un esempio di estratto XML riferito alla richiesta di registrazione di un documento tra uffici (tipo=interno):

  <doc tipo="interno" 
       anno="2004" 
       data_prot="20040610" 
       cod_amm_aoo="KONCENT" 
       annullato="no"
       num_prot="2004-KONCENT-0000008" 
       scarto="99">
    <repertorio cod="V_D_CDA" numero="V_D_CDA^KONCENT-20040000087">
      Verbali Consiglio di Amministrazione
    </repertorio>
    <minuta scarto="99">
      <classif cod="03/05" xml:space="preserve">03/05 – Assistenza telefonica</classif>
      <mittente nome_persona="Pera Marcello" 
                nome_uff="Presidenza Senato della Repubblica" 
                cod_persona="11123"
                cod_uff="SI000034" />
    </minuta>
    <oggetto xml:space="preserve">Richiesta documentazione protocollo informatico</oggetto>
    <tipologia cod="Dichiarazione"/>
    <mezzo_trasmissione cod="Fax"/>
    <classif cod="06/04" xml:space="preserve">06/04 - Documentazione</classif>
    <note xml:space="preserve">Note al documento</note>
    <riferimenti xml:space="preserve">CNIPA – Protocollo Informatico</riferimenti>
    <xlink href="http://www.link.it" xml:space="preserve">descrizione link</xlink>
    <allegato xml:space="preserve">0 - nessun allegato</allegato>
    <rif_interni>
      <rif_interno diritto="RPAM" 
                   cod_persona="11123" 
                   cod_uff="SI000034" 
                   nome_persona="Pera Marcello"
                   nome_uff="Presidenza Senato della Repubblica"/>
      <rif_interno diritto="RPA"
                   cod_persona="11111" 
                   cod_uff="SI000006" 
                   nome_persona="Ciampi Carlo Azeglio"
                   nome_uff="Presidenza della Repubblica"/> 
 
      <rif_interno diritto="CC" 
                   cod_persona="3" 
                   cod_uff="00003"
                   nome_persona="Berlusconi Silvio" 
                   nome_uff="Presidenza Consiglio dei Ministri"/>
    </rif_interni>
  </doc>

Campi valorizzati in automatico dal servizio (solo in assenza di valori preimpostati):

• /doc/@anno
• /doc/@cod_amm_aoo
• /doc/@annullato
• /doc/@data_prot
• /doc/@num_prot
• /doc/@scarto
• /doc/repertorio/@numero
• /doc/minuta/@scarto
• /doc/minuta/mittente/@*
• / /@xml:space
• / /classif
• /doc/allegato
• /doc/rif_interni/rif_interno/@cod_persona
• /doc/rif_interni/rif_interno/@cod_uff

L’elemento “repertorio” non è obbligatorio, tuttavia nel caso di registrazione di un documento appartenente ad un repertorio (ad esempio il repertorio dei verbali), diventa obbligatorio.
L’elemento “minuta” è obbligatorio. Se non viene specificato il responsabile di minuta (rif_interni) si assume automaticamente come RPAM l’operatore autenticato in inserimento.

Per aggiungere degli allegati ad un documento che ne è privo, occorre invocare il metodo checkInContentFiles() (per i dettagli si rimanda al javadoc).
Il contenuto binario dei file da allegare deve essere inserito nella richiesta SOAP e per ogni file deve essere indicato il nome che verrà presentato all'utente al momento della visualizzazione del documento.
Di seguito si riporta un esempio in linguaggio Java, realizzato con la libreria Axis. Lo stub client usato (nel codice ”this.titulus”), è stato generato a partire dal wsdl del servizio, mediante il tool WSDL2Java.
Nell'esempio vengono inseriti 2 allegati nel documento con id ”idUnit”, e di questi viene richiesta la conversione in pdf.

import org.apache.axis.client.Call;
import javax.activation.DataHandler;
import javax.activation.FileDataSource;
...
 
...
 
this.titulus.init(null, null, "test-ws", null, "xdocwaydoc-test", -1, -1);
...
 
// *** aggiunta degli allegati al documento idUnit ***
 
// meglio usare MIME (Call.ATTACHMENT_ENCAPSULATION_FORMAT_MIME) per l'incapsulamento
// degli allegati nella richiesta SOAP dato che con DIME si possono avere degli errori
// ("java.io.IOException: End of physical stream detected when XX more bytes expected.")
// in fase di conteggio (Attachments.getAttachmentCount()) degli allegati da parte del
// ricevente.
 
((TitulusSoapBindingStub)this.titulus)._setProperty(Call.ATTACHMENT_ENCAPSULATION_FORMAT,
                                                    Call.ATTACHMENT_ENCAPSULATION_FORMAT_MIME);
 
FileDataSource file1 = new FileDataSource(new File("Manuale_ACL.pdf"));
FileDataSource file2 = new FileDataSource(new File("doc.txt"));
 
((TitulusSoapBindingStub)this.titulus).addAttachment(new DataHandler(file1));
((TitulusSoapBindingStub)this.titulus).addAttachment(new DataHandler(file2));
 
String resp = this.titulus.checkInContentFiles(idUnit,
                                               new String[]{ "man_acl.pdf",
                                                             "documento_xml.txt" },
                                               null,
                                               true,
                                               false);
 
log.debug("document now is:\r\n\n" + resp + "\n");
 
// clears request attachments
((TitulusSoapBindingStub)this.titulus).clearAttachments();

Per i file associati ad un documento è attivo il versioning: gli operatori autorizzati possono richiedere il check-out del file da aggiornare, per poi introdurre la nuova versione del file con un'operazione di check-in. Questa opzione è disponibile solo per documenti non protocollati o per bozze di documenti protocollati. Inoltre, il versioning non è possibile per le immagini.
Ogni versione di file viene incapsulata come elemento figlio dell’elemento (xw:file) corrispondente alla versione precedente:

<files>
    <xw:file convert="remove" name="XXX.txt" title="test_versions.txt">
      <chkin cod_operatore="PI000056" data="20101028" operatore="TEST WS" ora="16:26:20"/>
      <chkout cod_operatore="PI000056" data="20101028" operatore="TEST WS" ora="16:26:21"/>
      <xw:file convert="remove" name="YYY.txt" title="test_versions1.txt">
        <chkin cod_operatore="PI000056" data="20101028" operatore="TEST WS" ora="16:26:21"/>
        <chkout cod_operatore="PI000056" data="20101028" operatore="TEST WS" ora="16:26:21"/>
 
        ...
 
        <xw:file convert="remove" name="ZZZ.txt" title="test_versionsN.txt">
          <chkin cod_operatore="PI000056" data="20101028" operatore="TEST WS" ora="16:26:22"/>
        </xw:file>
      </xw:file>
    </xw:file>
</files>

I metodi messi a disposizione per il versioning sono:

• checkOutContentFile(): per prenotare un file da modificare
• unlockContentFile(): per sbloccare un file precedentemente prenotato
• checkInContentFiles(): per aggiornare un file precedentemente prenotato.

Il numero massimo di versioni di un file accettate è 90 (nota: è possibile configurare Titulus in modo tale che accetti un numero massimo di versioni inferiore). Il superamento di questa soglia comporta un'eccezione in fase di check-in da intercettare lato client.

Di seguito si riporta un esempio in linguaggio Java, realizzato con la libreria Axis. Lo stub client usato (nel codice ”this.titulus”), è stato generato a partire dal wsdl del servizio, mediante il tool WSDL2Java.
Nell'esempio viene aggiunta una nuova versione dell'allegato con id ”attachID” nel documento ”idUnit”, e di questa viene richiesta la conversione in pdf.
Non sono state riportate l'estrazione dalla risposta SOAP dell'allegato restituito dal checkout, l'aggiornamento del file e la creazione del DataHandler (”attachDH”) per l'upload della nuova versione.
Queste operazioni sono state illustrate nei paragrafi Download file associati ed immagini e Aggiunta di allegati ad un documento.

import org.apache.axis.client.Call;
import javax.activation.DataHandler;
...
 
...
 
this.titulus.init(null, null, "test-ws", null, "xdocwaydoc-test", -1, -1);
...
 
// *** aggiunta di una nuova versione dell'allegato con id "attachID" nel documento idUnit ***
 
// checkout
String docXML = this.titulus.checkOutContentFile(idUnit, attachID, true, false);
 
System.out.println("document after checkout is:\r\n\n" + docXML + "\n");
 
// ***********************************************************************************
// Estrazione dalla risposta SOAP dell'allegato restituito dal checkout, aggiornamento
// del file e creazione del DataHandler ("attachDH") per l'upload della nuova versione
// ***********************************************************************************
...
 
// checkin
 
// clears attachments of checkOutContentFile
((TitulusSoapBindingStub)this.titulus).clearAttachments();
 
// meglio usare MIME (Call.ATTACHMENT_ENCAPSULATION_FORMAT_MIME) per l'incapsulamento
// degli allegati nella richiesta SOAP dato che con DIME si possono avere degli errori
// ("java.io.IOException: End of physical stream detected when XX more bytes expected.")
// in fase di conteggio (Attachments.getAttachmentCount()) degli allegati da parte del
// ricevente.
((TitulusSoapBindingStub)this.titulus)._setProperty(Call.ATTACHMENT_ENCAPSULATION_FORMAT,
                                                    Call.ATTACHMENT_ENCAPSULATION_FORMAT_MIME);
((TitulusSoapBindingStub)this.titulus).addAttachment(attachDH);
 
docXML = titulus.checkInContentFiles(idUnit,
                                     new String[]{ "nuova_versione.txt" },
                                     new String[]{ attachID }, 
                                     true,
                                     false);
 
// clears request attachments
((TitulusSoapBindingStub)titulus).clearAttachments();
 
System.out.println("document after checkin is:\r\n\n" + docXML + "\n");

Per modificare un documento è necessario caricare il documento bloccandolo attraverso il metodo loadDocument().
In seguito al caricamento con flag di lock attivo, qualora si intenda abbandonare il documento, è necessario sbloccarlo per mezzo del metodo unlockDocument().
Il salvataggio in modifica di un documento precedentemente caricato e bloccato, deve avvenire per mezzo del metodo saveModifiedDocument().
Alcuni attributi ed elementi non sono modificabili. Di seguito una sintesi degli XPath non modificabili:

/doc/@nrecord
/doc/@tipo
/doc/@num_prot
/doc/@cod_amm_aoo
/doc/storia
/doc/rif_interni
/doc/rif_esterni
/doc/files
/doc/immagini
/doc/impronta
/doc/minuta
/doc/wflow
/doc/repertorio

Per i documenti di protocollo, si aggiungono i seguenti percorsi fra quelli non modificabili:

/doc/@anno
/doc/@data_prot
/doc/oggetto
/doc/allegato 

La responsabilità di un documento viene assegnata in fase di registrazione dello stesso (si veda “Creare un nuovo documento”). In tale sede è necessario riportare gli estremi del responsabile all’interno dell’elemento /doc/rif_interni/rif_interno, impostando l’attributo diritto=”RPA”. Lo stesso dicasi per il responsabile della minuta (diritto=”RPAM”) e per i nominativi in copia conoscenza (diritto=”CC”).
Qualora in seguito alla registrazione si renda necessario il trasferimento del documento ad altro RPA, o l’aggiunta di nominativi fra i CC, si può far uso del metodo grantRight().
Ad esempio:

...
grantRight(<idIUnit>, “RPA”, “Ciampi Carlo Azeglio”, “Presidenza della Repubblica”,
           “KONCENT”, true);
...

trasferisce la responsabilità del documento individuato da idUnit a “Carlo Azeglio Ciampi”, inviando al nuovo RPA un'email di notifica dell'assegnazione di responsabilità.
Qualora si intenda rimuovere un nominativo dalle copie conoscenza di un documento, si può fare uso del metodo denyRight().
Entrambi i metodi (grantRight() e denyRight()) non richiedono il previo caricamento del documento (loadDocument()) ed il successivo salvataggio (saveDocument()), procedendo in autonomia a modificare i soli dati relativi a tali diritti nel documento.

È prevista la possibilità di aggiungere un post-it ad un documento già registrato. A tale scopo è stato previsto il metodo postIt() al quale è sufficiente trasmettere il numero fisico del documento ed il testo del post-it. Il metodo registra anche data, ora e nome dell’operatore che ha effettuato l’operazione.

È prevista la possibilità di annullare un documento già registrato. A tale scopo è stato previsto il metodo cancelDocument() al quale è sufficiente trasmettere il numero fisico del documento ed il motivo dell’annullamento. All’atto dell’annullamento vengono registrati anche data, ora e nome dell’operatore che ha effettuato l’operazione.

È possibile rimuovere un documento non protocollato e tutti i file ad esso associati per mezzo del metodo deleteDocument(). Non è possibile cancellare documenti protocollati.

È possibile inserire nel sistema un documento protocollato in versione bozza (/doc/@bozza=”si”) sul quale è possibile effettuare opportune operazioni di modifica fino al momento della registrazione ufficiale attraverso il metodo applyRegistrationToDraft().

Attraverso l'invocazione del metodo newFolder() è possibile creare un nuovo fascicolo. Di seguito un esempio della specifica XML da passare al metodo in questione:

  <?xml version="1.0"?>
  <fascicolo>
    <oggetto>Emissione fattura per primo workflow venduto</oggetto>
    <classif cod="7/3"/>
    <rif_interni>
      <rif diritto="RPA" nome_persona="Carlo Azeglio" nome_uff="Presidenza"/>
    </rif_interni>
  </fascicolo>

Anche in tale caso, come nella registrazione di documenti, alcuni “campi” (classificazione da titolario ed estremi RPA) vengono valorizzati in automatico.
Per popolare un fascicolo con dei documenti è stato predisposto il metodo addInFolder(), mentre attraverso l'invocazione del metodo newSubFolder() è possibile creare dei sottofascicoli originando una vera è propria gerarchia.
La consultazione di una gerarchia di fascicoli (in forma sintetica) avviene per mezzo del metodo getFolderHierarchy(), mentre il metodo getFolderContent() consente di recuperare la lista dei documenti contenuti e collegati ad un fascicolo.

Attraverso l'invocazione del metodo getDesktop() si ottengono una serie di Result-Set che identificano l'insieme dei documenti che soddisfano opportuni criteri di ricerca (su base personale o ufficio di appartenenza): documenti di cui si è responsabili (RPA) o di responsabilità dell'ufficio di appartenenza (UOR), documenti di cui si è in copia conoscenza (CC o CDS) ed altri.

Invocando il metodo getWorkflowId() si può accedere al/ai workflow associato/i ad un documento e con il metodo getWorkflowAction() si ottengono le eventuali azioni disponibili.
Il metodo startWorkflow() avvia un flusso su un documento, mentre continueWorkflow() fa avanzare un workflow attivo.

È prevista una serie di funzionalità per l'amministrazione del database degli utenti (ACL) ed i relativi diritti. Per creare un nuovo utente si ricorre al metodo addUser(), mentre la creazione di un ufficio avviene attraverso l'invocazione del metodo addInternalStructure(). Da sottolineare che l'organizzazione interna degli uffici assume le sembianze di una vera e propria gerarchia. Di seguito un esempio di specifica XML per la creazione di un nuovo ufficio in relazione gerarchica di figliolanza con l'ufficio identificato dal codice “00001” (cod_padre=”00001”):

  <?xml version="1.0"?>
  <struttura_interna cod_aoo="ENT" 
                     cod_amm="KONC" 
                     tipologia="Area" 
                     cod_padre="00001" 
                     cod_responsabile="1">
    <nome>Unità organizzativa XYZ</nome>
    <indirizzo nazione="Italia" 
               prov="BO" 
               cap="40033"
               comune="Casalecchio di Reno">
      Via Magnanelli, 2
    </indirizzo>
    <email addr="email1@dom.it" />
    <note>Alcune note...</note>
  </struttura_interna>

È possibile creare nuovi profili di utenza e modificarne di esistenti sfruttando i metodi addProfile() e modifyProfile().