Altre API e protocolli

SIP2

SIP2 (Session Initiation Protocol) è un protocollo per la comunicazione tra sistemi.

In Koha, il SIP2 è usato per la comunicazione tra macchine di Self-Check (autoprestito) SC e il sistema di Circolazione Automatica (noto anche come ACS, che è poi il server stesso di Koha).

Le comunicazioni SIP2 sono richieste e risposte.

Le macchine di autoprestito sono “tonte” e spediscono richieste al server Koha che esegue una certa logica per dare una risposta alla macchina, che la passa all’utente.

Avvertimento

Informazioni di sicurezza sul servizio SIP2: per assicurarsi che il traffico SIP2 in internet sia criptato devi usare una VPN o stunnel.

Impostare SIP2

Suggerimento

Helpful hints can be found on the Koha wiki:

Koha SIP2 server set up and SIP2 configuration.

Se hai installato Koha usando Debian, allora SIP2 è facile da installare, seguendo questi passi:

1. In your terminal (in the root Koha directory) write in: sudo koha-enable-sip <instancename>

2. Now you need to configure the SIP2 settings, to do this you need to edit the SIPconfig.xml file which exists in the /etc/koha/sites/<instancename>/ directory. You will need to edit this file as root because it contains passwords (to do so write ‘sudo’ at the start of your command).

es. sudo vi /etc/koha/sites/<instancename>/SIPconfig.xml

Nota

Nota importante: ci sono tre aree di interesse nel file SIPconfig.xml. Sono: service, account e institution.

Servizio

2.1 modificare il valore della porta nella parte superiore del file SIPconfig.xml (identificato con il numero 1 nella schermata sottostante), che abbia ha lo stesso indirizzo IP come più in basso nel file di SIPconfig.xml identificato da 2.

Nota

Assicurarsi che i valori di due porta non hanno lo stesso numero di porta, dato che non si può avere la stessa porta per due diversi servizi. Quando si decide il numero di porta usare un numero elevato (cioè sopra 1000) perché tutte le porte sotto 1000 richiedono permessi di root.

image1122

Account

L’account definito/i nel file SIPconfig.xml è semplicemente l’account autorizzato/i a utilizzare il servizio SIP2 cioè stai indicando chi può inviare e ricevere comandi SIP2.

Avvertimento

Account information that you write here must also exist in the Koha database i.e. you need to create a patron in the Koha staff interface with the same username, password (making sure to assign them the circulate permission) as the user account you write into the SIPconfig.xml file.

Nota

It is highly recommended that you only write in Koha user accounts with the circulate permission.

The reason we want SIP2 users to only have the circulate permission rather than the superlibrarian permission is to reduce the access SIP2 users have to confidential patron data in case the system was compromised.

If the ACS or the SC were compromised then having all SIP2 users only having the circulate permission means that an intruder would only be able to access patron data via the terminal rather than the web interface as well (which would be available with the superlibrarian permission). So it is simply a matter of protecting your users.

image1119

Definizioni dei valori dell’account:

  1. Login id: È lo username dell’account. - Modificarlo opportumanente

  2. Password: Account password - Modificare opportunamente

  3. Delimiter: il tipo di delimitatore per le informazioni dell’account - Lasciare il default

  4. error-detect - Leave as default

  5. Istituzione: Questo è il branchcode della biblioteca a cui l’utente appartiene. Nota: Questa istituzione deve essere definita ulteriormente nell’area istituzione del file SIPconfig.xml e deve esistere anche nel database di Koha. cioè è necessario creare una biblioteca con la stessa branchcode nell’interfaccia staff di Koha.

  6. encoding: Questo è lo standard usato per codificare i dati dell’account

  7. Terminator: Questo deve corrispondere al valore di terminator del server SIP2. - Modificare questa opzione se si conosce il valore di terminator del server SIP2.

È anche possibile aggiungere attributi personalizzati utente ai profili SIP2 usando un formato del tipo:

<patron_attribute field=»XX» code=»CODE1» /> <patron_attribute field=»XY» code=»CODE2» /> <patron_attribute field=»XZ» code=»CODE3» />

Istituzione

L’informazione di una istituzione che definisci qui deve coincidere con una biblioteca creata in Koha.

Avvertimento

È necessario accertarsi che tutte le istituzioni a cui vengono assegnati gli account ulteriormente nel file SIPconfig.xml siano definite anche nell’area istituzione dello stesso file.

image1120

Definizioni valori per l’istituzione:

  1. Institution id: The branchcode of the library. - Modify this accordingly.

    Must be the same as created in Koha and the account area.

  2. Implementazione: Definisce il codice che verrà eseguito. - Lasciare come default

  3. Policy: Policy defines the permitted SIP2 commands allowed from SC’s in this institution. For example: renewal=”true” means that SC’s at that institution have permission to send renewal item SIP2 commands.

  4. Starting SIP2

Simply write in the command:

sudo koha-start-sip <instancename>

Nota

Ora hai un server SIP2 funzionante.

Nota

Optionally, you can configure sorting bin behavior, using the UseLocationAsAQInSIP and SIP2SortBinMapping system preferences.

Usare SIP2

SIP2 è un protocollo di comunicazione. I messaggi spediti via SIP2 sono richieste o risposte. L’SC spedisce richieste all’ACS che esegue una certa logica e restituisce un valore all’SC in un messaggio di risposta.

I messaggi di richiesta contengono argomenti, che sono valori di dati utilizzati dall’ACS nelle sue funzioni per eseguire il compito richiesto come rinnovare i prestiti.

Comandi SIP2

Se vuoi usare/testare SIP2 manualmente, dovrai scrivere e ricevere messaggi tramite il terminal Linux.

Per essere in grado di inviare e ricevere messaggi con il server SIP2 è necessario utilizzare telnet per aprire una connessione SIP2. È necessario specificare il numero di porta che si desidera telnet da utilizzare.

Per trovare queste informazioni vedere nell’area di servizio nella parte superiore del file SIPconfig.xml (cercare il numero di porta come indicato dalla freccia nella schermata qui sotto).

image1121

  1. Scrivi sul terminale

    telnet localhost <portnumber>

    es. telnet localhost 8023

  2. Now write in the username and password set in one of the accounts in the SIPconfig.xml file.

  3. Now you are connected to the SIP2 server you can start writing and sending request commands. The connection to the SIP2 server does time out fast so if haven’t finished writing and receiving commands simply write in: telnet localhost <portnumber> to restart the SIP2 connection.

Comandi sintassi SIP2

Ogni comando SIP2 ha un prefisso di due caratteri numerici che definiscono cosa fa il comando.

ad esempio per ottenere informazioni su un utente si avvia il comando con il prefisso: 63. La risposta dal server ha anche un prefisso numerico corrispondente.

Sotto c’è un esempio di richiesta SIP2 di informazione di un utente (un account Koha con username “joe”, password “joes” e numero tessera “y76t5r43” è stato creato nello interfaccia di Koha).

Additionally a library with the branchcode of ‘WEL’ has been created in the Koha staff interface and is also defined in the institution area of the SIPconfig.xml file:

image1123

Per cui il formato per questo messaggio SIP2 è:

image1124

Nota

Il valore di riepilogo è di 10 caratteri. Se si usa Y allora si sarà in grado di ottenere un riepilogo e più dettagliate informazioni di output.

Il valore in <YYYYMMDD> <HHMMSS> è la data e ora corrente, e lasciando 4 spazi tra YYYYMMDD e HHMMSS si indica di usare il local time invece di UTC.

Nota

In questo manuale i codici a lettere nei diversi campi sono usati quando possibile per descrivere i campi del messaggio SIP2, per esempio AO <institutionid>.

Questi codici possono essere usati nei comandi SIP2 dal terminale Linux, ma non vanno riportate le <> parentesi uncinate, solo i valori tra <>.

Messaggi SIP2

Blocco utente

Usa il prefisso 01 del messaggio di richiesta e il prefisso 24 del messaggio di risposta.

Messaggio di richiesta:

image1125

Nota

Card retained is a single character field of either ‘Y’ or ‘N’ which tells the ACS that a card has been retained by the self checkout machine.

Messaggio di risposta:

image1126

Nota

<patronstatus> è una stringa di 14 caratteri. Il valore Y nella stringa indica vero. Ogni posizione nella stringa (a partire da 0) ha un valore (Y or N).

es. un Y in posizione 1 (il secondo valore nella stringa) indica che non sono concessi i privilegi di rinnovo all’account

Rientro copie

Usa il prefisso 09 del messaggio di richiesta (messaggi inviati a ACS e il prefisso 10 del messaggio di risposta (inviati a SC).

Messaggio di richiesta:

image1127

Nota

  • <no block (Offline)> è ‘Y’ o ‘N’ che indica se la transazione è avvenuta offline. Le transazioni offline non sono supportate, per cui devi scrivere ‘N’ se stai testando questo messaggio manualmente.

  • <transactiondate> un campo di 18 caratteri con formato: YYYYMMDDZZZZHHMMSS.

ZZZZ è la timezone, Se vuoi impostarlo a locale, usa 4 spazi, se vuoi impostarlo a UTC UTC (Coordinated Universal Time) scrivi 3 spazi e una Z.

Messaggio di risposta:

image1128

Nota

Alert type could have one of several values: 00 : Unknown

01: local hold

02: remote hold

03: ILL Transfer

04: transfer

99: Other

Se la copia viene magnetizzata allora il valore di <resensitize> deve essere Y altrimenti N. Magnetizzare copie riattiva l’antitaccheggio.

Prestito copie

Usa il prefisso 11 del messaggio di richiesta e il prefisso 12 del messaggio di risposta. Ha una sintassi simile a quella del comando di restituzione visto prima, ma con prefissi diversi.

Prenotazione - Potrebbe non essere supportato su alcuni sistemi. Usa il prefisso 15 del messaggio di richiesta e il prefisso 16 del messaggio di risposta.

Messaggio di richiesta:

image1129

Nota

<holdmode> è un carattere. + indica di aggiungere una prenotazione, - indica di cancellarla e * indica di modificarla.

Messaggio di risposta:

image1130

Nota

  • <ok> è un carattere numerico che può essere 0 (prenotazione non permessa o fallita) o 1 (prenotazione permessa e riuscita).

  • <available> può essere Y o N. Y significa che la copia è attualmente in biblioteca, N significa che la copia è attualmente è in prestito o in prenotata.

Informazioni della copia: Usa il prefisso 17 del messaggio di richiesta e il prefisso 18 del messaggio di risposta

Messaggio di richiesta:

image1131

Nota

Si veda il comando restituzione copie (descritto sopra) per capire il valore di <xact_date>.

La password del terminale è opzionale.

Messaggio di risposta:

image1132

Item status update: This uses the request message prefix of 19 and the response message prefix of 20

Messaggio di richiesta:

image1133

Nota

<itemproperties> non è un valore di lunghezza fissa, e puoi opzionalmente indicare valori come dimensione della copia e questi valori verranno conservati copia per copia nel database di Koha.

Messaggio di risposta:

image1134

Nota

<itempropertiesok> è 0 o 1. 1 indica che il valore <itemproperties> definito nel messaggio di aggiornamento dello stato della copia è stato conservato correttamente nel database di Koha.

Stato utente

Usa il prefisso 23 del messaggio di richiesta e il prefisso 24 del messaggio di risposta.

Messaggio di richiesta:

image1135

Messaggio di risposta:

image1136

Nota

The value displayed for <patronvalidity> is Y (valid) and N (invalid). The value in the <YYYYMMDD> < HHMMSS> is the current date/time.

Il motivo dello spazio tra i due valori è indicare che si vuole usare il local time invece di UTC.

Attivazione utente - Non ancora supportata. Usa il prefisso 25 del messaggio di richiesta e il prefisso 26 del messaggio di risposta

Nota

Questo comando annulla quello di blocco dell’utente.

Messaggio di richiesta:

image1137

Messaggio di risposta:

image1138

Renew: This uses the request message prefix of 29 and the response message prefix of 30

Messaggio di richiesta:

image1139

Nota

  • <thirdpartyallowed> is a single character value which is either Y or N. If it is Y then third parties can renew items.

  • <noblock> è Y o N. Se Y, la copia è stata prestata/restituita quando l’ACD era offline.

  • <nbduedate> è la data della transazione di prestito/restituzione quando il sistema ACS era offline.

  • <feeacknowledged> è Y o N. Indica se l’utente accetta il costo associato con la copia che sta rinnovando.

Messaggio di risposta:

image1140

Nota

  • <ok> è 0 o 1. Il valore 1 indica rinnovo avvenuto, 0 indica rinnovo fallito.

  • <renewalok> è Y o N. La logica per impostare il valore di <renewalok> è: Y si usa quando la copia è già prestata all’utente e deve essere smagnetizzata e quindi rinnovata, mentre N si usa quando la copia non è già prestata all’utente e non deve essere rinnovata.

In altre parole non permettere all’utente di rinnovare ciò che non ha in prestito.

Fine sessione

Usa il prefisso 35 del messaggio di richiesta e il prefisso 36 del messaggio di risposta

Messaggio di richiesta:

image1141

Messaggio di risposta:

image1142

Nota

<success_or_failure> è Y per ok o N per ko.

Tassa pagata - Potrebbe non essere ancora implementata. Usa il prefisso 37 del messaggio di richiesta e il prefisso 38 del messaggio di risposta

Messaggio di richiesta:

image1143

Nota

  • <feetype> è un numero di due cifre tra 01 e 99. Per vedere una lista dei tipi di costi vai a http://multimedia.3m.com/mws/media/355361O/sip2-protocol.pdf

  • <paymenttype> sono due cifre da 00 a 99. 00 è contante, 01 è Visa, 02 è carta di credito.

  • <currencytype> is a 3 alphanumeric character long value identifying the currency the fee was paid in.

Messaggio di risposta:

image1144

Nota

<paymentaccepted> è Y (pagamento accettato) o N (pagamento non accettato).

Informazioni utente

Usa il prefisso 63 del messaggio di richiesta e il prefisso 64 del messaggio di risposta

Messaggio di richiesta:

image1145

Messaggio di risposta:

image1146

Nota

<valid patron> è Y per valido e N per non valido.

Nota

<hold itemcount><overdueitemcount><chargeditemscount><fienitemscount><recallitemscount><unavaliableholdscount> sono tutti di 4 caratteri numerici.

Rinnova tutto

This uses the request message prefix of 65 and the response message prefix of 66.

Messaggio di richiesta:

image1147

Messaggio di risposta:

image1148

Nota

  • <renewedcount> è un valore di 4 cifre che indica il numero delle copie rinnovate.

  • <unrenewedcount> ha lo stesso formato di <renewedcount> ma indica il numero di copie non rinnovate.

Login

Usa il prefisso 93 del messaggio di richiesta e il prefisso 94 del messaggio di risposta.

Messaggio di richiesta:

image1149

Nota

<UIDalgorithm> e <PWDalgorithm> sono lunghi un carattere e indicano il tipo di algoritmo da usare per criptare loginuserid e loginpassword.

Il valore 0 indica che questi valori non saranno criptati.

Response message: 941 is a successful login

940 is an unsuccessful login

[connection closed by foreign host.] is a unsuccessful login

Rispedisci

Così viene chiesto al sistema ricevente di rispedire l’ultimo messaggio.

SC -> ACS rispedire la richiesta è 97

ACS -> SC rispedire la richiesta è 96

Status di ACS e SC

Questo ha il prefisso di richiesta 99 e il prefisso di risposta di 98.

Messaggio di richiesta:

image1150

Nota

The status code is one of 3 values. - 0: SC is ok

  • 1: SC is out of paper

  • 2: SC is shutting down

  • max print width is a 3 character long value which is the integer number of characters the client can print

  • Protocol version is a 4 character value in the format x.xx

Messaggio di risposta:

image1151

Nota

Se la risposta è “96”, il messaggio di richiesta è non valido/non compreso.

Risoluzione problemi con SIP2

Impossibile connettersi all’host usando il comando telnet localhost <portnumber>

le 3 soluzioni da tentare per questo problema sono:

  1. Controllare che il numero di porta usato nel comando precedente sia il numero di porta scritto nel file SIPconfig.xml nella posizione indicata dal numero 1. cioè nell’esempio seguente se il numero di porta è 6001 il comando corretto sarebbe: telnet localhost 6001.

  2. Verificare se qualsiasi userid è scritto più di una volta nel file SIPconfig.xml. L’ID utente (che è semplicemente il nome utente dell’utente Koha) deve essere univoco all’interno del file SIPconfig.xml. Se hai lo stesso ID utente più volte nel file SIPconfig.xml, farà sì che la connessione a SIP2 fallisca prima dell’autenticazione.

  3. Check the account defined in the SIPconfig.xml file also exists in the Koha database with the same username, password and has the circulate permission. If you have dropped and recreated the Koha database after creating the patron account in the Koha staff interface and the SIPconfig.xml file then that patron account will not exist in the Koha database and so you will need to recreate them in the Koha staff interface.

Per vedere il log di SIP2 vai alla directory: /var/log/koha/<instancename>

Poi vedi i log sip-error.log e sip-output.log che riportano informazioni più precise sugli errori di SIP2.

  • cat sip-error.log

  • cat sip-output.log

Link utili per i comandi SIP2

http://multimedia.3m.com/mws/media/355361O/sip2-protocol.pdf

LDAP

Impostare LDAP () per Koha permette di conservare l’informazione di tutti gli utenti in un database centrale accessibile per autenticarsi in Koha e in altri server della tua istituzione.

LDAP è un protocollo per trovare file sulle reti e per l’autenticazione.

LDAP configurations are powerful allowing you to customise how Koha and LDAP interact. LDAP can be configured so that new accounts created in LDAP can be synced down into the Koha database, additionally updates to the LDAP user account are synced down to the Koha database.

Comunque Koha non può sincronizzare i dati sul server LDAP, cioè il traffico verso Koha dal server LDAP è in sola lettura.

Auth_By_Bind è 1 se un sistema Microsoft Windows Active Directory è usato nel database LDAP.

Prima di procedere alla configurazione di LDAP, ti servono le seguenti informazioni/azioni da parte della tua istituzione

  • L’organizzazione dovrà aprire una porta per permettere l’accesso al loro AD dal server.

  • Informazione per accedere al server AD (IP address/hostname, port, SSL info)

  • Informazioni sulla configurazione del server AD (sono rilevanti OUs, DCs, i formati CN relativi agli usernames)

  • Mappatura tra campi AD e campi Koha, inclusi i default

  • Valori di default per quanto non fornito da AD (categorycode, branchcode per esempio)

  • Per autenticare un utente facciamo un bind come sembra essere comune per AD oppure usiamo un nostro login e poi controlliamo ? Se usiamo la seconda opzione abbiamo bisogno dei dettagli di come fare log on

  • I nomi utente esistenti in Koha corrispondono ai nomi utente che useremo per cercarli in AD? Se è così, bene. Se così non fosse, come verranno trattati utenti duplicati?

Passi per configurare LDAP per la tua istanza di Koha

1 In Linux terminal navigate to the directory containing the koha-conf.xml file which will either be in:
  • /etc/koha/sites/<instance-name>/

    OR

  • /etc/koha/

2 Apri il file koha-conf.xml con i permessi di root: sudo vi koha-conf.xml

3 Andare alla linea che contiene ‘<useldapserver>0</useldapserver>’ e cambiarlo in: <useldapserver>1</useldapserver>

4 Then in the next line below write in the LDAP configurations below:

      <ldapserver id="<ldapserverid>">

      <hostname><hostname></hostname>

      <base>dc=<domaincontroller>,dc=<domaincontroller></base>

      <user>cn=<nameofuser>, dc=<domaincontroller>,dc=<domaincontroller></user> <!--This is the username of user account with permissions to query the LDAP server -->

      <pass><password></pass> <!-- This is password of the user account with permissions to query the LDAP server-->

      <replicate><either0or1></replicate> <!-- add new users from LDAP to Koha database -->

<welcome><either0or1></welcome> <!-- send new users the welcome email when added via replicate -->

      <update><either0or1></update> <!-- update existing users in Koha database -->

      <auth_by_bind><either0or1></auth_by_bind> <!-- set to 1 to authenticate by binding instead of password comparison, e.g., to use Active Directory -->

      <principal_name><principalname></principal_name> <!-- optional, for     auth_by_bind: a printf format to make userPrincipalName from koha userid        -->

      <mapping> <!-- match koha SQL field names to your LDAP record field names-->

      <firstname is="givenname"></firstname>

      <surname is="sn"></surname>

      <address is="postaladdress"></address>

      <city is="l">Athens, OH</city>    <!-- Athens,OH is the default value for
      city of all users logging into Koha -->

      <zipcode is="postalcode"></zipcode>

      <branchcode is="branch">Central</branchcode>

      <userid is="uid"></userid>

      <password is="userpassword"></password>

      <email is="mail"></email>

      <categorycode is="employeetype">EM</categorycode>

      <phone is="telephonenumber"></phone>

      </mapping>

      </ldapserver>

Salva ed esci dal file koha-conf.xml

6 Controlla che la connessione LDAP funzioni scrivendo:

ldapsearch -H ldaps://host.name -s base -x -w «» -d 1

Nota

Note about hostname:

Hostname can either be a alphanumerical name or it can be the LDAP server IP address (its optional to write port number).

By default the ldaps default port number is 636, whilst ldap default port number is 389.

Nota

Note about the replicate and update fields:

The replicate LDAP config field for LDAP in the koha-conf.xml file allow the Koha database to be added to with a new borrower account whenever a user logs into Koha (either the staff client or OPAC) with their LDAP username and password (assuming the same username and password does not already exist in the Koha database).

Whereas the update LDAP config field (in the same file allows) allows for user information in the LDAP database to be synced down to the Koha database.

e.g. if someone gets married and their surname changes then the new surname only needs to be updated in the existing LDAP database and that will be synced down to the Koha database automatically if the update configuration is set to 1.

Riguardo ai campi di mappatura (i campi evidenziati inverde) <city is=»l»>Athens, OH</city>

Il nome di colonna a sinistra (in giallo) è il nome della colonna nel database LDAP.

Il nome della colonna all’interno di virgolette (evidenziata in color magenta) è il nome della colonna nel database di Koha. Nota: Questo può essere riempito con qualsiasi valore se non esiste alcun nome di colonna equivalente nel database Koha come esiste nel database LDAP.

Il valore evidenziato in ciano è il valore predefinito per le colonne specificate di Koha e LDAP. Così nell’esempio sopra tutti i record utente nel database di Koha e LDAP per impostazione predefinita avrà il valore di città di “Atene, OH”.

Esempi delle configurazioni LDAP:

<useldapserver>1</useldapserver><!-- see C4::Auth_with_ldap for extra configs you must add if you want to turn this on -->

<ldapserver id="ldapserver" listenref="ldapserver">

<hostname>ldaps://example.co.au</hostname>

<base>ou=employees,dc=companya,dc=com,dc=au</base>

<user></user> <!-- DN, if not anonymous -->

<pass></pass> <!-- password, if not anonymous -->

<auth_by_bind>1</auth_by_bind>

<replicate>1</replicate> <!-- add new users from LDAP to Koha database -->

<update>0</update> <!-- update existing users in Koha database -->

<principal_name>ou=employees,dc=companya,dc=com,dc=au</principal_name>

<mapping>

<userid       is="uid"            ></userid>

<cardnumber   is="uid"            ></cardnumber>

<email        is="mail"           ></email>

<surname      is="sn"             ></surname>

<firstname    is="givenname"      ></firstname>

<categorycode is="1">EM</categorycode>

<branchcode   is="1">SYD</branchcode>

</mapping>

</ldapserver>

I valori nell’area di mappatura non sono sempre gli stessi, dipendono da come è fatto il sistema LDAP della tua istituzione. Per esempio alcune istituzioni non usano <userid> ma ogni utente è identificato dal campo <email>; quindi <userid> non viene scritto.

Risoluzione problemi con LDAP

La stampa del log degli errori di LDAP dipende da diversi fattori:

If plack is not disabled then LDAP errors are displayed in the plack-error.log file. If plack is disabled then the location that LDAP errors are printed to is either the opac-error.log file (if the user is logging into the OPAC) or the intranet-error.log file (if the user is logging into the staff client) All of these three log files are accessible in the following directory:

/var/log/koha/<instance>/