DOCFINDERWEB SERVICE E CLIENT

Transcript

1 DOCFINDERWEB SERVICE E CLIENT Specifiche tecniche di interfacciamento al Web Service esposto da DocPortal Versione : 1 Data : 10/03/2014 Redatto da: Approvato da: RICCARDO ROMAGNOLI 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 Mondolfo (PU) Italy info@multimediait.net P.Iva/Cod.Fisc.: Vat: IT Iscriz. Cciaa Pesaro n Pag. 1 di 13

2 Sommario 1. Introduzione Altri documenti utili Scopo del documento Campo di applicazione Metodo di autenticazione Oggetto della comunicazione DocFinder Web Service WSDL (web service description language) Metodo Documentrequest Descrizione di DocumentRequest in formato xml con protocollo SOAP Descrizione di DocumentRequestResponse in formato xml con protocollo SOAP Schema XML valido per DocumentRequest, DocumentRequestResponse e client DocFinderWeb Descrizione degli elementi comuni presenti nei documenti xml elemento Versione Sezione INPUT elemento DataOra elemento URL elemento Login elemento Password elemento ID_Database elemento SYS_Seriale elemento SYS_RECORD elemento Azione Sezione OUTPUT elemento DataOra elemento NomeFile elemento DescrFile elemento Errore Esempio xml degli elementi comuni DocFinder Web Client Esempio file di richiesta in formato XML Esempio file di risposta in formato XML Note amministrative e requisiti Licenze Requisiti Rilascio Pag. 2 di 13

3 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 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 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. 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. 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. OGGETTO DELLA COMUNICAZIONE I parametri di richiesta dei documenti sono gli stessi della soluzione DocFInder Client: ID_DATABASE Codice della base dati SYS_SERIALE Codice dell archivio SYS_RECORD 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) Pag. 3 di 13

4 2. DOCFINDER WEB SERVICE Il servizio web è raggiungibile come subrisorsa /DocFinderWebService.asmx dell URL del sever di DocPortal, esempio: 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 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 DESCRIZIONE DI DOCUMENTREQUEST 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=" xmlns:xsd=" xmlns:soap12=" <soap12:body> Pag. 4 di 13

5 <DocumentRequest xmlns=" <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> DESCRIZIONE DI DOCUMENTREQUESTRESPONSE 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=" xmlns:xsd=" xmlns:soap12=" <soap12:body> <DocumentRequestResponse xmlns=" <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> Pag. 5 di 13

6 </DocumentRequestResult> </DocumentRequestResponse> </soap12:body> </soap12:envelope> Pag. 6 di 13

7 2.2. SCHEMA XML VALIDO PER DOCUMENTREQUEST, DOCUMENTREQUESTRESPONSE E CLIENT DOCFINDERWEB Pag. 7 di 13

8 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: ELEMENTO VERSIONE Tipo intero: rappresenta la versione del documento attualmente da valorizzare con 0. SEZIONE INPUT Tutti gli elementi della sezione INPUT devono essere valorizzati prima di effettuare la richiesta ELEMENTO DATAORA Rappresenta la data e ora di effettuazione della richiesta ELEMENTO URL Indirizzo del servizio web da istanziare ELEMENTO LOGIN identificativo utente che effettua la richiesta (deve essere presente in Archivia Plus) ELEMENTO PASSWORD la password dell utente che effettua la richiesta ELEMENTO ID_DATABASE Matricola del database aziendale ELEMENTO SYS_SERIALE Numero di serie dell archivio contenente il documento richiesto ELEMENTO SYS_RECORD Numero di record all interno dell archivio ELEMENTO AZIONE 3.3. 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 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 ELEMENTO DATAORA Rappresenta la data e ora di effettuazione della risposta (in fase di richiesta deve essere valorizzato) ELEMENTO NOMEFILE Contiene il path del documento se l azione è GET altrimenti l URL del documento se l azione è VIEW ELEMENTO DESCRFILE Valore della descrizione del documento presente in archivio. Pag. 8 di 13

9 ELEMENTO ERRORE 3.4. Descrizione dell eventuale errore riscontrato durante l elaborazione della richiesta. ESEMPIO XML DEGLI ELEMENTI COMUNI <Versione>0</Versione> <INPUT> <DataOra> T16:31: :00</DataOra> <URL> <Login>MioApplicativo</Login> <Password>Segreto</Password> <ID_Database>AABBCCDDEEFFGGHH</ID_Database> <SYS_SERIALE> </SYS_SERIALE> <SYS_RECORD>153</SYS_RECORD> <Azione> VIEW </Azione> </INPUT> <OUTPUT> <DataOra> T16:31: :00</DataOra> <NomeFile> <DescrFile>Documento dimostrativo in formato pdf</descrfile> <Errore></Errore> </OUTPUT> Pag. 9 di 13

10 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 Pag. 10 di 13

11 4.1. ESEMPIO FILE DI RICHIESTA IN FORMATO XML <?xml version="1.0" encoding="utf-8"?> <DocFinderWeb> <Versione>0</Versione> <INPUT> <DataOra> T16:31: :00</DataOra> <URL> <Login>MioApplicativo</Login> <Password>segreto</Password> <ID_Database>AABBCCDDEEFFGGHH</ID_Database> <SYS_SERIALE> </SYS_SERIALE> <SYS_RECORD>153</SYS_RECORD> <Azione>VIEW</Azione> </INPUT> <OUTPUT> <DataOra> T16:31: :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> T16:31: :00</DataOra> <URL> <Login></Login> <Password></Password> <ID_Database>AABBCCDDEEFFGGHH</ID_Database> <SYS_SERIALE> </SYS_SERIALE> <SYS_RECORD>153</SYS_RECORD> <Azione> VIEW </Azione> </INPUT> <OUTPUT> <DataOra> T16:31: :00</DataOra> <NomeFile> <DescrFile>Documento dimostrativo in formato pdf</descrfile> <Errore></Errore> </OUTPUT> </DocFinderWeb> Pag. 11 di 13

12 5. NOTE AMMINISTRATIVE E REQUISITI 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. 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 Pag. 12 di 13

13 Pag. 13 di 13