Importazione

Top Previous Next

Invocazione del servizio di importazione

L’aggiornamento dei dati in Check&In viene invocato mediante una chiamata http alla pagina integrazione.aspx. I dati da importare sono letti da un file esterno, oppure fanno parte del corpo della chiamata, oppure ancora sono caricati da un database.

I parametri forniti alla pagina sono i seguenti:

•

template: path del file contenente i parametri dell’importazione; questo parametro è obbligatorio. Per indicare i percorsi vale sempre la seguente regola: se il percorso inizia con “/”, allora deve essere un percorso virtuale completo (cioè un percorso che individua il file a partire da una condivisione web), altrimenti è un percorso relativo alla directory principale del sito di Check&In.

•	datafile: path del file contenente i dati da caricare; necessario per una chiamata di tipo http get; non va indicato invece quando gli stessi dati sono passati nel corpo della chiamata di tipo post oppure ricavati con una query su un database.

•	username e password: credenziali di un utente dell’applicazione Check&In; la pagina integrazione.aspx è progettata per essere chiamata da altre applicazioni e quindi non utilizza la modalità di autenticazione standard basata su form di login. La password è criptata mediante l’utility pwdcrypt

Le modalità di chiamata del servizio sono quindi:

•	l’applicazione compone una richiesta http post

o	indica come parametri il path del file di definizione dei parametri, posto in una cartella accessibile dal server di Check&In

o	indica come parametri username e password

o	invia i dati nel corpo della richiesta; i dati possono essere in formato testo oppure xml

•	l’applicazione compone una richiesta http get

o	scrive i dati su un file di testo in una cartella accessibile al server di Check&In

o	indica come parametri della chiamata http il path di questo file insieme agli altri parametri già illustrati

•	l’applicazione compone una richiesta http get, i dati sono letti da un database

Ecco un esempio di URL di invocazione di tipo http get:

http://localhost/CheckAndIn/Integrazione.aspx?template=Temp/impEsterni.xml&datafile=Temp/Esterni.txt&username=super&password=G

In questo esempio il file di template è “Temp\impEsterni.xml”, il file di dati è “Temp\Esterni.txt”, username è “super” e la password è vuota.

Il file di definizione dei parametri

Il formato dei dati da caricare è specificato nel file contenente i parametri dell’importazione. Questo file è in formato xml ed ha il seguente formato

<import

mode=modalità di importazione

format=formato dei dati di input: vedi note

<!—- significativi solo se il format=“database” -->

dbType=tipo di database

DSN=stringa di connessione

query=query di estrazione dei dati

<!—- significativi solo se il format è “fixed” o “xml” -->

encoding=stringa che identifica la codifica del file (ASCII, UTF8, …)

<!—- significativi solo se il format è “custom” -->

assembly=nome di un assembly .NET esterno

type=nome della classe dell’assembly

primary-key=campo che identifica univocamente i record

missing-pk=comportamento a fronte di record non presenti in Check&In

missing-fk=comportamento a fronte di una foreign key mancante

selecting=generazione di comandi ai terminali

<fieldlist> tag che indica l’elenco dei campi

<nome campo

pos=colonna inizio

len=lunghezza del campo

/> parametri per un campo in caso di importazione da un file di testo

<nome campo

alias=nome del tag nel file dati

/> parametri per un campo in caso di importazione da un file xml

<nome campo

default=valore di default

/> parametri per un campo non passato ma da valorizzare comunque

Più precisamente, il significato dei campi è il seguente:

•	mode: può valere replace oppure append; nel primo caso se il record anagrafico è già presente nel db questo viene aggiornato mentre se non è presente viene inserito; nel secondo caso è possibile solo inserire nuovi record; record già presenti vengono ignorati

•	format: può valere fixed, xml, database, custom; indica se i dati sono letti da un file con formato a colonne fisse, con formato xml, da un database, oppure da un modulo assembly esterno;

•	se format="database":

o	dbType: è una stringa che indica il tipo di database e può essere una fra "MSDE", "SQLSERVER", "ORACLE";

o	DSN: è la stringa di connessione, la sua struttura dipende dal tipo di database;

o	query: è il comando SQL per l’estrazione dei dati che sono oggetto dell’importazione;

•	se format="fixed" o format="xml":

o	encoding: stringa con la descrizione della codifica usata per produrre il file dei dati: non è un dato obbligatorio , se non è indicato è il valore di default di Windows, in genere UTF-8;

•	se format="custom":

o	assembly: è il nome di un assembly .NET, esterno a Check&In, che implementa le procedure necessarie per leggere in successione i dati da elaborare durante l’importazione; es.: “Importazione.dll”;

o	type: è il nome della classe che esegue l’importazione e che è implementata nel modulo indicato, es.: “Importazione.MyImporter”.

•

primary-key: indica il nome del campo che identifica univocamente l’anagrafica, solitamente il codice fiscale oppure la matricola. Deve essere un campo omonimo di un campo dell’archivio anagrafico di Check&In, non sono quindi ammessi i campi con nome composto, cioè badge-codice, badge-datainizio, ecc.

•	missing-pk: indica il comportamento a fronte di un record non presente nel db: può valere skip oppure insert; nel primo caso il record viene ignorato, nel secondo viene creata la nuova anagrafica

•	missing-fk: indica il comportamento a fronte di una foreign key non presente nel db: può valere skip, ignore oppure insert; nel primo caso l’intero record viene ignorato, nel secondo viene ignorato il campo, nel terzo creato un record con valori di default e chiave uguale al valore passato

•	selecting: indica se a fronte di aggiornamenti delle anagrafiche e dei badge devono essere generati dei comandi di aggiornamento per i terminali dell’impianto; può valere true o false

Definizione dell’elenco dei campi

Ogni campo facente parte dell’aggiornamento è definito nel seguente formato:

•	il nome del tag xml corrisponde al nome del campo nel db di Check&In.

•	Sono inoltre ammessi i seguenti valori per identificare i dati del badge:

o	badge-codice

o	badge-datainizio

o	badge-datafine

o	badge-idpolicyaccesso

•	Altri dati legati all’anagrafica definiti dall’utente vengono modellati mediante i concetti di titoli ed elementi. Questi valori possono essere passati identificando il campo come titolo-codice del titolo (es. titolo-tipodip per identificare il tipo dipendente)

•	Se il badge oppure il valore per il titolo specificato non sono presenti in archivio si applica il comportamento definito dal parametro missing-fk nell’intestazione.

•	Caso particolare è l’indicazione della politica di accesso, che è il contenuto del campo “idpolicyaccesso” oppure nel campo “badge-idpolicyaccesso”: si veda il paragrafo successivo

•	in caso di importazione da file di testo a posizioni fisse vanno valorizzati i parametri pos e len che indicano la posizione del primo carattere (a partire dalla colonna 0) e la lunghezza del campo

•	in caso di importazione da file xml o database, può essere valorizzato il parametro alias che indica il nome del tag relativo al campo nel file dei dati; se non è presente si assume il valore del campo per Check&In

•

format: per valori di tipo data, questo attributo indica il formato per la conversione da stringa; sono valide tutte le stringhe che contengono le sequenze GG, MM, AA, AAAA, HH, NN, SS, dove AAAA è l’anno a 4 cifre, MM è il mese a 2 cifre o i minuti, NN sono i minuti; ad esempio: GGMMAAAA (giorno mese anno), GGMMAAAAHHNNSS (giorno, mese, anno, ore, minuti, secondi), GG/MM/AA/HH:MM:SS (giorno, mese, anno, ore, minuti, secondi)

•	nel caso si voglia dare un valore di default ad un campo non passato ma necessario per Check&In si può usare il parametro default che ne indica il valore

Importazione da database

Ecco un file di configurazione per l’importazione dal database Northwind di SqlServer.

<import mode="replace" format="database"

dbType="SQLSERVER"

DSN="Persist Security Info=True;User ID=sa;Password=;Initial Catalog=Northwind;Data Source=."

query="SELECT * FROM Employees ORDER BY EmployeeID"

primary-key="matricola" missing-pk="insert" missing-fk="insert" selecting="true">

<badge-codice alias="EmployeeID" len="8" />

<badge-datainizio alias="HireDate" />

<badge-datafine alias="FireDate" missing="skip" />

<badge-idpolicyaccesso default="2003" />

</fieldlist>

</import>

Note sull’importazione delle politiche di accesso

La politica di accesso è specificata nel campo “idpolicyaccesso” oppure nel campo “badge-idpolicyaccesso”, se relativa al singolo badge. E’ possibile indicare una lista di valori anziché un solo valore: il primo valore indicato diventa la politica principale, gli altri valori diventano le politiche aggiuntive. Per riferirsi ad una politica si può usare, in qualsiasi posizione dell’elenco, sia l’identificativo numerico univoco della tabella Policy, cioè il campo Id, sia il valore “Codice esterno”, quindi il campo CodEst.

Esempi di come indicare le politiche

Valore letto dal file	Significato
“2”	La policy con Id=2, oppure con CodEst=“2”
“002”	La policy con Id=2, oppure con CodEst=“002”
“Ingresso”	La policy con CodEst= “Ingresso”
“2,Ingresso”	Le policy con Id=2 (diventa la principale) e con CodEst= “Ingresso” (policy aggiuntiva)
“Dip,IngressoA,IngressoB”	Policy con CodEst=“Dip” (la principale), e le 2 policy con CodEst=“IngressoA” e “IngressoB”

Dato un riferimento ad una policy, la procedura di importazione cerca di ricavare la policy facendo prima la ricerca sul campo Id, poi sul campo CodEst.

La ricerca per Id può restituire una policy solo se il valore letto è un numero, in tal caso è interpretato nel suo contenuto numerico, cioè ignorando eventuali spazi e zeri iniziali (nell’esempio, “002” diventa “2”); la ricerca per CodEst usa invece il valore letto dal file senza modifiche (nell’esempio, “002” resta “002”). Per evitare confusione, è importante che il codice esterno delle definizioni delle policy sia univoco e che non sia di tipo numerico (perché non coincida casualmente con valori di Id).

Altre note:

•	evitare spazi di separazione dopo la virgola (verrebbero trattati come facenti parte del codice esterno);

•	per indicare il codice esterno, non è importante distinguere fra maiuscole e minuscole (se una politica ha codice esterno “POL2”, nel file posso indicare “Pol2” oppure “pol2”).

Caso di un riferimento inesistente

Se il riferimento ad una politica non è valido, perché non si trova una politica con quel valore di Id o di codice esterno, la procedura si comporta diversamente a seconda del valore del parametro missing-fk:

•	se vale “insert”, l’importazione crea una nuova definizione di una politica con la descrizione ed il codice esterno uguali al valore letto da file, questa politica è usata per risolvere il riferimento appena letto;

•	se vale “skip” o “ignore”, ignora l’errore e procede, il file di log registra questa situazione.

La policy definita sui badge

Quando la procedura di importazione crea un nuovo badge, gli attribuisce le politiche di accesso (una o più) indicate nel campo “badge-idpolicyaccesso” o il valore di default. Se il file non contiene indicazioni a proposito, il badge prenderà la politica attribuita all’anagrafica (eventualmente più di una nel caso di una anagrafica con politiche multiple). Valgono inoltre le seguenti regole:

•	l’inizio validità del badge, se non indicato, è il 01/01/1900;

•	se nei dati di input si indica la data fine validità senza l’ora (perché il formato non la prevede), questa viene messa alle 23:59.

Comportamento in situazioni di errore

Per ogni record letto dai dati di input, la procedura esegue una singola transazione sul database. In questo modo, o si completa correttamente l’elaborazione del record (con tutte le operazioni di inserimento o modifica necessarie), oppure, a causa di qualche errore, l’operazione viene annullata del tutto. Se l’importazione è eseguita in modalità “get”, al termine l’operatore vedrà un riepilogo dei risultati dell’elaborazione e degli errori riscontrati.