DocFinder Web servizio di richiesta documenti per

DOCFINDERWEB SERVICE E CLIENT
Specifiche tecniche di interfacciamento al Web Service esposto
da DocPortal
Versione :
1
Data
10/03/2014
:
Redatto da:
RICCARDO ROMAGNOLI
Approvato da:
CLAUDIO CAPRARA
Categoria:
Documenti tecnici
Destinatari:
Terze parti
Elenco delle versioni
Versione draft TeamSystem
20/02/2014
Versione 1
10/03/2014
TAG
DocFInder, web, Collegamento software esterni, consultazione remota documenti conservati.
MultiMedia it Snc di Romagnoli R. e Caprara C. Via Piemonte 6 Marotta 61037 Mondolfo (PU) Italy [email protected]
P.Iva/Cod.Fisc.: 01317580411-Vat: IT01317580411 Iscriz. Cciaa Pesaro n. 122739 www.multimediait.com
Pag. 1 di 13
Sommario
1.
Introduzione ........................................................................................................................................- 3 1.1. Altri documenti utili .............................................................................................................................- 3 1.2. Scopo del documento ..........................................................................................................................- 3 1.3. Campo di applicazione .........................................................................................................................- 3 1.4. Metodo di autenticazione ...................................................................................................................- 3 1.5. Oggetto della comunicazione ..............................................................................................................- 3 2.
DocFinder Web Service .......................................................................................................................- 4 2.1. WSDL (web service description language) ..........................................................................................- 4 2.1.1.
Metodo Documentrequest ..........................................................................................................- 4 2.1.2.
Descrizione di DocumentRequest in formato xml con protocollo SOAP 1.2 ...............................- 4 -
2.1.3.
Descrizione di DocumentRequestResponse in formato xml con protocollo SOAP 1.2 ...............- 5 -
2.2. Schema XML valido per DocumentRequest, DocumentRequestResponse e client DocFinderWeb ...- 7 3.
Descrizione degli elementi comuni presenti nei documenti xml .......................................................- 8 3.1. elemento Versione ..............................................................................................................................- 8 3.2. Sezione INPUT......................................................................................................................................- 8 3.2.1.
elemento DataOra .......................................................................................................................- 8 3.2.2.
elemento URL ..............................................................................................................................- 8 -
3.2.3.
elemento Login ............................................................................................................................- 8 -
3.2.4.
elemento Password .....................................................................................................................- 8 -
3.2.5.
elemento ID_Database ................................................................................................................- 8 -
3.2.6.
elemento SYS_Seriale ..................................................................................................................- 8 -
3.2.7.
elemento SYS_RECORD ...............................................................................................................- 8 -
3.2.8.
elemento Azione..........................................................................................................................- 8 -
3.3. Sezione OUTPUT ..................................................................................................................................- 8 3.3.1.
elemento DataOra .......................................................................................................................- 8 3.3.2.
elemento NomeFile .....................................................................................................................- 8 -
3.3.3.
elemento DescrFile ......................................................................................................................- 8 -
3.3.4.
elemento Errore ..........................................................................................................................- 9 -
3.4.
4.
4.1.
4.2.
5.
5.1.
5.2.
5.3.
Esempio xml degli elementi comuni....................................................................................................- 9 DocFinder Web Client ........................................................................................................................- 10 Esempio file di richiesta in formato XML ...........................................................................................- 11 Esempio file di risposta in formato XML............................................................................................- 11 Note amministrative e requisiti .........................................................................................................- 12 Licenze ...............................................................................................................................................- 12 Requisiti .............................................................................................................................................- 12 Rilascio ...............................................................................................................................................- 12 -
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 2 di 13
1. INTRODUZIONE
DocPortal è un servizio che consente di consultare tramite browser web, gli archivi digitali creati con i
programmi ArchiMedia e Archivia Plus .
DocFinderWeb Service è un servizio che consente a programmi esterni di richiedere la visualizzazione di
documenti.
La presente specifica tecnica è rivolta agli sviluppatori di terze parti che intendano interfacciare i loro
applicativi con DocPortal.
1.1. ALTRI DOCUMENTI UTILI
Annuncio DocPortal e DocFInderWeb vedi docportal-annuncio
Per l’installazione e la configurazione di DocPortal vedi docportal installazione
Per l’implementazione di DocFinderWeb negli applicativi Vedi questo documento
1.2. SCOPO DEL DOCUMENTO
Il documento affronta gli aspetti relativi alle tecniche di richiamo del metodo DocumentRequest
esposto dal web service DocFinderWebService.asmx disponibile su DocPortal.
1.3. CAMPO DI APPLICAZIONE
Il protocollo di comunicazione è basato su WSDL e SOAP e prevede l’esistenza di un server WEB nel
quale sia installato e configurato l’applicativo DocPortal e di uno o più client remoti, i quali
effettuano la chiamata al metodo DocumentRequest ed ottengono la risposta in formato xml.
1.4. METODO DI AUTENTICAZIONE
Il servizio web richiede e verifica le credenziali di accesso, al fine di ottenere un’autenticazione sicura
(e semplice da gestire) si consiglia la creazione di un utente virtuale provvisto di password che sia
abilitato alla consultazione web e che rappresenti l’applicativo esterno, ad esempio un identificativo
utente potrebbe essere “MioApplicativo” e tutte le richieste indicheranno come credenziali di
accesso sempre “MioApplicativo”.
1.5. OGGETTO DELLA COMUNICAZIONE
I parametri di richiesta dei documenti sono gli stessi della soluzione DocFInder Client:



ID_DATABASE
SYS_SERIALE
SYS_RECORD
Codice della base dati
Codice dell ‘archivio
Codice del record
DocPortal sulla base dei parametri di richiesta, provvede a ricercare ed estrarre il documento
indipendentemente dal fatto che sia ancora in fase di archiviazione o sia già stato passato in
conservazione definitiva, e lo invia al richiedente.
Per Inviare all’applicativo esterno i parametri di ricerca dei documenti , si utilizzano le stesse funzioni
disponibili per DocFInder (Esportazione dati per Applicativi Esterni)
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 3 di 13
2. DOCFINDER WEB SERVICE
Il servizio web è raggiungibile come subrisorsa /DocFinderWebService.asmx dell’URL del sever di DocPortal ,
esempio:
https://docportal.miodominio.dom/ DocFinderWebService.asmx
2.1. WSDL (WEB SERVICE DESCRIPTION LANGUAGE )
La descrizione formale del servizio web è reperibile tramite l’apposito link, queste informazioni sono
necessarie solo per chi intende sviluppare in proprio il client e/o colloquiare direttamente con il
servizio web.
2.1.1.
METODO DOCUMENTREQUEST
Questo metodo accetta come parametro un documento in formato XML contenente le informazioni
necessarie per l’autenticazione del client e per il reperimento di uno specifico documento
informatico in funzione degli indici specificati. Il client invia con protocollo SOAP 1.1, 1.2 o HTTP il
documento xml contenente la richiesta “DocumentRequest” ed ottiene in risposta un
“DocumentRequestResponse” sempre in formato xml.
2.1.2.
DESCRIZIONE DI DOCUMENT REQUEST IN FORMATO XML CON PROTOCOLLO SOAP 1.2
I segnaposto evidenziati in rosso rappresentano il tipo di valore
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 4 di 13
<DocumentRequest xmlns="http://www.multimediait.com/DocFinderWebService/2014/01">
<docFinderWebXML xmlns="DocFinderWebService">
<Versione xmlns="">int</Versione>
<INPUT xmlns="">
<DataOra>dateTime</DataOra>
<URL>string</URL>
<Login>string</Login>
<Password>string</Password>
<ID_Database>string</ID_Database>
<SYS_SERIALE>string</SYS_SERIALE>
<SYS_RECORD>long</SYS_RECORD>
<Azione>string</Azione>
</INPUT>
<OUTPUT xmlns="">
<DataOra>dateTime</DataOra>
<NomeFile>string</NomeFile>
<DescrFile>string</DescrFile>
<Errore>string</Errore>
</OUTPUT>
</docFinderWebXML>
</DocumentRequest>
</soap12:Body>
</soap12:Envelope>
2.1.3.
DESCRIZIONE DI DOCUMENT REQUESTRESPONSE IN FORMATO XML CON PROTOCOLLO SOAP 1.2
I segnaposto evidenziati in rosso rappresentano il tipo di valore
<?xml version="1.0" encoding="utf-8"?>
<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<DocumentRequestResponse
xmlns="http://www.multimediait.com/DocFinderWebService/2014/01">
<DocumentRequestResult xmlns="DocFinderWebService">
<Versione xmlns="">int</Versione>
<INPUT xmlns="">
<DataOra>dateTime</DataOra>
<URL>string</URL>
<Login>string</Login>
<Password>string</Password>
<ID_Database>string</ID_Database>
<SYS_SERIALE>string</SYS_SERIALE>
<SYS_RECORD>long</SYS_RECORD>
<Azione>string</Azione>
</INPUT>
<OUTPUT xmlns="">
<DataOra>dateTime</DataOra>
<NomeFile>string</NomeFile>
<DescrFile>string</DescrFile>
<Errore>string</Errore>
</OUTPUT>
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 5 di 13
</DocumentRequestResult>
</DocumentRequestResponse>
</soap12:Body>
</soap12:Envelope>
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 6 di 13
2.2. SCHEMA XML VALIDO PER DOCUMENTREQUEST, DOCUMENTREQUESTRESPONSE E CLIENT DOCFINDERWEB
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 7 di 13
3. DESCRIZIONE DEGLI ELEMENTI COMUNI
PRESENTI NEI DOCUMENTI XML
Al fine di agevolare lo sviluppo e la manutenzione del software tutti i documenti xml contengono i medesimi
elementi di sotto specificati:
3.1. ELEMENTO VERSIONE
Tipo intero: rappresenta la versione del documento attualmente da valorizzare con 0.
3.2. SEZIONE INPUT
Tutti gli elementi della sezione INPUT devono essere valorizzati prima di effettuare la richiesta.
3.2.1.
ELEMENTO DATA ORA
Rappresenta la data e ora di effettuazione della richiesta
3.2.2.
ELEMENTO URL
Indirizzo del servizio web da istanziare
3.2.3.
ELEMENTO LOGIN
identificativo utente che effettua la richiesta (deve essere presente in Archivia Plus)
3.2.4.
ELEMENTO PASSWORD
la password dell’utente che effettua la richiesta
3.2.5.
ELEMENTO ID_D ATABASE
Matricola del database aziendale
3.2.6.
ELEMENTO SYS_S ERIALE
Numero di serie dell’archivio contenente il documento richiesto
3.2.7.
ELEMENTO SYS_RECORD
Numero di record all’interno dell’archivio
3.2.8.
ELEMENTO AZIONE
Indica l’azione che il client DocFinderWeb deve compiere con il documento richiesto, può assumere
due valori rispettivamente GET per effettuare il download del documento e VIEW per avviare il
browser con il documento
3.3. SEZIONE OUTPUT
Gli elementi della sezione output sono valorizzati del servizio web in risposta alla richiesta ad
eccezione dell’elemento DataOra che in fase di richiesta deve assumere lo stesso valore presente
nella sezione INPUT.
3.3.1.
ELEMENTO DATA ORA
Rappresenta la data e ora di effettuazione della risposta (in fase di richiesta deve essere valorizzato).
3.3.2.
ELEMENTO N OMEFILE
Contiene il path del documento se l’azione è GET altrimenti l’URL del documento se l’azione è VIEW.
3.3.3.
ELEMENTO DESCRFILE
Valore della descrizione del documento presente in archivio.
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 8 di 13
3.3.4.
ELEMENTO E RRORE
Descrizione dell’eventuale errore riscontrato durante l’elaborazione della richiesta.
3.4. ESEMPIO XML DEGLI ELEMENTI COMUNI
<Versione>0</Versione>
<INPUT>
<DataOra>2014-01-20T16:31:51.4211175+01:00</DataOra>
<URL>https://docportal.miodominio.dom/DocFinderWebService.asmx</URL>
<Login>MioApplicativo</Login>
<Password>Segreto</Password>
<ID_Database>AABBCCDDEEFFGGHH</ID_Database>
<SYS_SERIALE>1234567890123456</SYS_SERIALE>
<SYS_RECORD>153</SYS_RECORD>
<Azione> VIEW </Azione>
</INPUT>
<OUTPUT>
<DataOra>2014-01-20T16:31:55.84515547+01:00</DataOra>
<NomeFile>https://docportal.miodominio.com/temp/service/file.pdf</NomeFile>
<DescrFile>Documento dimostrativo in formato pdf</DescrFile>
<Errore></Errore>
</OUTPUT>
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 9 di 13
4. DOCFINDER WEB CLIENT
Per gli sviluppatori che operano in ambiente MS Windows e che non intendono sviluppare l’interfaccia tramite
protocollo SOAP possono instanziare il client denominato DocFinderWeb.exe che consente la fruizione del
servizio web tramite la scrittura e la lettura diretta di un file XML nel formato descritto al capitolo 3. Unico pre
requisito per il funzionamento del client è Microsoft Dot Net Framework 4.0 o successivi.
La fruizione del servizio web è semplificata al massimo in quanto dall’applicativo esterno si deve istanziare
l’eseguibile specificando come parametro il nome del file xml contenente la richiesta e successivamente
leggere lo stesso file xml contenente sia la richiesta che la risposta. Per motivi di sicurezza nella risposta le
credenziali di accesso non sono presenti.
La sintassi è la seguente:
C:\>DocFinderWeb.exe <fileXml> [/windows] [/open]
<file xml> path completo del file xml contenente i parametri di ricerca.
/windows Mostra finestra per interazione utente. Forma breve: /w."
/open Apre automaticamente il documento al termine della elaborazione della richiesta. Forma breve: /o.";
Esempio da riga di comando:
C:\>DocFinderWeb.exe c:\temp\richiesta.xml /w /o
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 10 di 13
4.1. ESEMPIO FILE DI RICHIESTA IN FORMATO XML
<?xml version="1.0" encoding="UTF-8"?>
<DocFinderWeb>
<Versione>0</Versione>
<INPUT>
<DataOra>2014-01-20T16:31:51.4211175+01:00</DataOra>
<URL>https://docportal.miodominio.dom/DocFinderWebService.asmx</URL>
<Login>MioApplicativo</Login>
<Password>segreto</Password>
<ID_Database>AABBCCDDEEFFGGHH</ID_Database>
<SYS_SERIALE>1234567890123456</SYS_SERIALE>
<SYS_RECORD>153</SYS_RECORD>
<Azione>VIEW</Azione>
</INPUT>
<OUTPUT>
<DataOra>2014-01-20T16:31:51.4211175+01:00</DataOra>
<NomeFile></NomeFile>
<DescrFile> </DescrFile>
<Errore></Errore>
</OUTPUT>
</DocFinderWeb>
4.2. ESEMPIO FILE DI RISPOSTA IN FORMATO XML
<?xml version="1.0" encoding="UTF-8"?>
<DocFinderWeb>
<Versione>0</Versione>
<INPUT>
<DataOra>2014-01-20T16:31:51.4211175+01:00</DataOra>
<URL>https://docportal.miodominio.dom/DocFinderWebService.asmx</URL>
<Login></Login>
<Password></Password>
<ID_Database>AABBCCDDEEFFGGHH</ID_Database>
<SYS_SERIALE>1234567890123456</SYS_SERIALE>
<SYS_RECORD>153</SYS_RECORD>
<Azione> VIEW </Azione>
</INPUT>
<OUTPUT>
<DataOra>2014-01-20T16:31:55.84515547+01:00</DataOra>
<NomeFile>https://docportal.miodominio.com/temp/service/file.pdf</NomeFile>
<DescrFile>Documento dimostrativo in formato pdf</DescrFile>
<Errore></Errore>
</OUTPUT>
</DocFinderWeb>
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 11 di 13
5. NOTE AMMINISTRATIVE E REQUISITI
5.1. LICENZE
DocFinderWeb è incluso nella licenza di DocPortal
La richiesta DocFinderWeb non comporta l’uso di licenza client.
L’avvio delle funzioni estese di DocPortal richiede una licenza client libera.
5.2. REQUISITI
Requisiti per l’esecuzione del servizio

Infrastruttura
o Server windows 2008 o superiore
o Microsoft .net 4.0 o superiore
o Sql Server Express o superiore
o Internet Information Server 7.0 o superiore
o Un indirizzo ip raggiungibile

Software Applicativo
o ArchiMedia / Archivia Plus Suite Universal
o ArchiMedia / Archivia Plus Estensione Sql Express o superiore
o DocPortal
o Un numero di licenze Client adeguato alle richieste
5.3. RILASCIO
Marzo 2014
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 12 di 13
Documenti Tecnici – DocFInderWebService&Client – specifiche tecniche
Pag. 13 di 13

Download Report