1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
2 "http://www.oasis-open.org/docbook/xml/4.1/docbookx.dtd"
4 <!ENTITY % local SYSTEM "local.ent">
6 <!ENTITY % entities SYSTEM "entities.ent">
8 <!ENTITY % idcommon SYSTEM "common/common.ent">
11 <!-- $Id: pazpar2_conf.xml,v 1.26 2007-06-06 12:02:48 marc Exp $ -->
12 <refentry id="pazpar2_conf">
14 <productname>Pazpar2</productname>
15 <productnumber>&version;</productnumber>
18 <refentrytitle>Pazpar2 conf</refentrytitle>
19 <manvolnum>5</manvolnum>
23 <refname>pazpar2_conf</refname>
24 <refpurpose>Pazpar2 Configuration</refpurpose>
29 <command>pazpar2.conf</command>
33 <refsect1><title>DESCRIPTION</title>
35 The pazpar2 configuration file, together with any referenced XSLT files,
36 govern pazpar2's behavior as a client, and control the normalization and
37 extraction of data elements from incoming result records, for the
38 purposes of merging, sorting, facet analysis, and display.
42 The file is specified using the option -f on the pazpar2 command line.
43 There is not presently a way to reload the configuration file without
44 restarting pazpar2, although this will most likely be added some time
49 <refsect1><title>FORMAT</title>
51 The configuration file is XML-structured. It must be valid XML. All
52 elements specific to pazpar2 should belong to the namespace
53 "http://www.indexdata.com/pazpar2/1.0" (this is assumed in the
54 following examples). The root element is named 'pazpar2'. Under the
55 root element are a number of elements which group categories of
56 information. The categories are described below.
59 <refsect2 id="config-server"><title>server</title>
61 This section governs overall behavior of the client. The data
62 elements are described below.
64 <variablelist> <!-- level 1 -->
69 Configures the webservice -- this controls how you can connect
70 to pazpar2 from your browser or server-side code. The
71 attributes 'host' and 'port' control the binding of the
72 server. The 'host' attribute can be used to bind the server to
73 a secondary IP address of your system, enabling you to run
74 pazpar2 on port 80 alongside a conventional web server. You
75 can override this setting on the command lineusing the option -h.
84 If this item is given, pazpar2 will forward all incoming HTTP
85 requests that do not contain the filename 'search.pz2' to the
86 host and port specified using the 'host' and 'port'
87 attributes. The 'myurl' attribute is required, and should provide
88 the base URL of the server. Generally, the HTTP URL for the host
89 specified in the 'listen' parameter. This functionality is
90 crucial if you wish to use
91 pazpar2 in conjunction with browser-based code (JS, Flash,
92 applets, etc.) which operates in a security sandbox. Such code
93 can only connect to the same server from which the enclosing
94 HTML page originated. Pazpar2s proxy functionality enables you
95 to host all of the main pages (plus images, CSS, etc) of your
96 application on a conventional webserver, while efficiently
97 processing webservice requests for metasearch status, results,
104 <term>icu_chain</term>
107 Definition of ICU tokenization and normalization rules
108 are used if ICU support is compiled in. The 'id'
109 attribute is currently not used, and the 'locale'
110 attribute must be set to one of the locale strings
111 defined in ICU. The child elements listed below can be
112 in any order, except the 'index' element which logically
113 belongs to the end of the list. The stated tokenization,
114 normalization and charmapping instructions are performed
115 in order from top to bottom.
117 <variablelist> <!-- Level 2 -->
118 <varlistentry><term>casemap</term>
121 The attribure 'rule' defines the direction of the
122 per-character casemapping, allowed values are "l"
123 (lower), "u" (upper), "t" (title).
127 <varlistentry><term>normalize</term>
130 Normalization and transformation of tokens follows
131 the rules defined in the 'rule' attribute. For
132 possible values we refer to the extensive ICU
133 documentation found at the
134 <ulink url="&url.icu.transform;">ICU
135 transformation</ulink> home page. Set filtering
136 principles are explained at the
137 <ulink url="&url.icu.unicode.set;">ICU set and
138 filtering</ulink> page.
142 <varlistentry><term>tokenize</term>
145 Tokenization is the only rule in the ICU chain
146 which splits one token into multiple tokens. The
147 'rule' attribute may have the following values:
148 "s" (sentence), "l" (line-break), "w" (word), and
149 "c" (character), the later probably not beeing
150 very useful in a runing pazpar2 installation.
154 <varlistentry><term>index</term>
157 Finally the 'index' element instruction - without
158 any 'rule' attribute - is used to store the tokens
159 after chain processing in the relevance ranking
160 unit of Pazpar2. It will always be the last
161 instruction in the chain.
173 This nested element controls the behavior of pazpar2 with
174 respect to your data model. In pazpar2, incoming records are
175 normalized, using XSLT, into an internal representation.
176 The 'service' section controls the further processing and
177 extraction of data from the internal representation, primarily
178 through the 'metdata' sub-element.
181 <variablelist> <!-- Level 2 -->
182 <varlistentry><term>metadata</term>
185 One of these elements is required for every data element in
186 the internal representation of the record (see
187 <xref linkend="data_model"/>. It governs
188 subsequent processing as pertains to sorting, relevance
189 ranking, merging, and display of data elements. It supports
190 the following attributes:
193 <variablelist> <!-- level 3 -->
194 <varlistentry><term>name</term>
197 This is the name of the data element. It is matched
198 against the 'type' attribute of the
200 in the normalized record. A warning is produced if
201 metdata elements with an unknown name are
203 normalized record. This name is also used to
205 data elements in the records returned by the
206 webservice API, and to name sort lists and browse
212 <varlistentry><term>type</term>
215 The type of data element. This value governs any
216 normalization or special processing that might take
217 place on an element. Possible values are 'generic'
218 (basic string), 'year' (a range is computed if
219 multiple years are found in the record). Note: This
220 list is likely to increase in the future.
225 <varlistentry><term>brief</term>
228 If this is set to 'yes', then the data element is
229 includes in brief records in the webservice API. Note
230 that this only makes sense for metadata elements that
231 are merged (see below). The default value is 'no'.
236 <varlistentry><term>sortkey</term>
239 Specifies that this data element is to be used for
240 sorting. The possible values are 'numeric' (numeric
241 value), 'skiparticle' (string; skip common, leading
242 articles), and 'no' (no sorting). The default value is
248 <varlistentry><term>rank</term>
251 Specifies that this element is to be used to
253 records against the user's query (when ranking is
254 requested). The value is an integer, used as a
255 multiplier against the basic TF*IDF score. A value of
256 1 is the base, higher values give additional
258 elements of this type. The default is '0', which
259 excludes this element from the rank calculation.
264 <varlistentry><term>termlist</term>
267 Specifies that this element is to be used as a
268 termlist, or browse facet. Values are tabulated from
269 incoming records, and a highscore of values (with
270 their associated frequency) is made available to the
271 client through the webservice API.
273 are 'yes' and 'no' (default).
278 <varlistentry><term>merge</term>
281 This governs whether, and how elements are extracted
282 from individual records and merged into cluster
283 records. The possible values are: 'unique' (include
284 all unique elements), 'longest' (include only the
285 longest element (strlen), 'range' (calculate a range
286 of values across al matching records), 'all' (include
287 all elements), or 'no' (don't merge; this is the
292 </variablelist> <!-- attributes to metadata -->
296 </variablelist> <!-- Data elements in service directive -->
299 </variablelist> <!-- Data elements in server directive -->
304 <refsect1><title>EXAMPLE</title>
305 <para>Below is a working example configuration:
307 <?xml version="1.0" encoding="UTF-8"?>
308 <pazpar2 xmlns="http://www.indexdata.com/pazpar2/1.0">
311 <listen port="9004"/>
312 <proxy host="us1.indexdata.com" myurl="us1.indexdata.com"/>
314 <!-- optional ICU ranking configuration example -->
316 <icu_chain id="el:word" locale="el">
317 <normalize rule="[:Control:] Any-Remove"/>
319 <normalize rule="[[:WhiteSpace:][:Punctuation:]] Remove"/>
326 <metadata name="title" brief="yes" sortkey="skiparticle" merge="longest" rank="6"/>
327 <metadata name="isbn" merge="unique"/>
328 <metadata name="date" brief="yes" sortkey="numeric" type="year" merge="range"
330 <metadata name="author" brief="yes" termlist="yes" merge="longest" rank="2"/>
331 <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
332 <metadata name="url" merge="unique"/>
341 <refsect1 id="target_settings"><title>TARGET SETTINGS</title>
343 Pazpar2 features a cunning scheme by which you can associate various
344 kinds of attributes, or settings with search targets. This can be done
345 through XML files which are read at startup; each file can associate
346 one or more settings with one or more targets. The file format is generic
347 in nature, designed to support a wide range of application requirements. The
348 settings can be purely technical things, like, how to perform a title
349 search against a given target, or it can associate arbitrary name=value
350 pairs with groups of targets -- for instance, if you would like to
351 place all commercial full-text bases in one group for selection
352 purposes, or you would like to control what targets are accessible
357 During startup, pazpar2 will recursively read a specified directory
358 (can be identified in the pazpar2.cfg file or on the command line), and
359 process any settings files found therein.
363 Clients of the pazpar2 webservice interface can selectively override
364 settings for individual targets within the scope of one session. This
365 can be used in conjunction with an external authentication system to
366 determine which resources are to be accessible to which users. Pazpar2
367 itself has no notion of end-users, and so can be used in conjunction
368 with any type of authentication system. Similarly, the authentication
369 tokens submitted to access-controlled search targets can similarly be
370 overriden, to allow use of pazpar2 in a consortial or multi-library
371 environment, where different end-users may need to be represented to
372 some search targets in different ways. This, again, can be managed
373 using an external database or other lookup mechanism. Setting overrides
374 can be performed either using the 'init' or the 'settings' webservice
375 command (see XXX ref to pazpar2 protocol).
379 In fact, every setting that applies to a database (except pz:id, which
380 can only be used for filtering targets to use for a search) can be overriden
381 on a per-session basis. This allows the client to override specific CCL fields
382 for searching, etc., to meet the needs of a session or user.
386 Finally, as an extreme case of this, the webservice client can
387 introduce entirely new targets, on the fly, as part of the init or
388 settings command. This is useful if you desire to manage information
389 about your search targets in a separate application such as a database.
390 You do not need any static settings file whatsoever to run pazpar2 -- as
391 long as the webservice client is prepared to supply the necessary
392 information at the beginning of every session.
396 NOTE: The following discussion of practical issues related to session and settings
397 management are cast in terms of a user interface based on Ajax/Javascript
398 technology. It would apply equally well to many other kinds of browser-based logic.
402 Typically, a Javascript client is not allowed to directly alter the parameters
403 of a session. There are two reasons for this. One has to do with access
404 to information; typically, information about a user will be stored in a
405 system on the server side, or it will be accessible in some way from the server.
406 However, since the Javascript client cannot be entirely trusted (some hostile
407 agent might in fact 'pretend' to be a regular ws client), it is more robust
408 to control session sesttings from scripting that you run as part of your
409 webserver. Typically, this can be handled during the session initialization,
414 Step 1: The Javascript client loads, and asks the webserver for a new pazpar2
415 session ID. This can be done using a Javascript call, for instance. Note that
416 it is possible to submit Ajax HTTPXmlRequest calls either to pazpar2 or to the
417 webserver that pazpar2 is proxying for. See (XXX Insert link to pazpar2 protocol).
421 Step 2: Code on the webserver authenticates the user, by database lookup,
422 LDAP access, NCIP, etc. Determines which resources the user has access to,
423 and any user-specific parameters that are to be applied during this session.
427 Step 3: The webserver initializes a new pazpar2 settings, and sets user-specific
428 parameters as necessary, using the init webservice command. A new session ID is
433 Step 4: The webserver returns this session ID to the Javascript client, which then
434 uses the session ID to submit searches, show results, etc.
438 Step 5: When the Javascript client ceases to use the session, pazpar2 destroys
439 any session-specific information.
442 <refsect2><title>SETTINGS FILE FORMAT</title>
444 Each file contains a root element named <settings>. It may
445 contain one or more <set> elements. The settings and set
446 elements may contain the following attributes. Attributes in the set node
447 overrides those in the setting root element. Each set node must
448 specify (directly, or inherited from the parent node) at least a
449 target, name, and value.
457 This specifies the search target to which this setting should be
458 applied. Targets are identified by their Z39.50 URL, generally
459 including the host, port, and database name, (e.g.
460 bagel.indexdata.com:210/marc). Two wildcard forms are accepted:
461 * (asterisk) matches all known targets;
462 bagel.indexdata.com:210/* matches all known databases on the given
466 A precedence system determines what happens if there are
467 overlapping values for the same setting name for the same
468 target. A setting for a specific target name overrides a
469 setting whch specifies target using a wildcard. This makes it
470 easy to set defaults for all targets, and then override them
471 for specific targets or hosts. If there are
472 multiple overlapping settings with the same name and target
473 value, the 'precedence' attribute determines what happens.
481 The name of the setting. This can be anything you like.
482 However, pazpar2 reserves a number of setting names for
483 specific purposes, all starting with 'pz:', and it is a good
484 idea to avoid that prefix if you make up your own setting
485 names. See below for a list of reserved variables.
493 The value of the setting. Generally, this can be anything you
494 want -- however, some of the reserved settings may expect
495 specific kinds of values.
500 <term>precedence</term>
503 This should be an integer. If not provided, the default value
504 is 0. If two (or more) settings have the same content for
505 target and name, the precedence value determines the outcome.
506 If both settings have the same precedence value, they are both
507 applied to the target(s). If one has a higher value, then the
508 value of that setting is applied, and the other one is ignored.
515 By setting defaults for target, name, or value in the root
516 settings node, you can use the settings files in many different
517 ways. For instance, you can use a single file to set defaults for
518 many different settings, like search fields, retrieval syntaxes,
519 etc. You can have one file per server, which groups settings for
520 that server or target. You could also have one file which associates
521 a number of targets with a given setting, for instance, to associate
522 many databases with a given category or class that makes sense
523 within your application.
527 The following examples illustrate uses of the settings system to
528 associate settings with targets to meet different requirements.
532 The example below associates a set of default values that can be
533 used across many targets. Note the wildcard for targets.
534 This associates the given settings with all targets for which no
535 other information is provided.
537 <settings target="*">
539 <!-- This file introduces default settings for pazpar2 -->
540 <!-- $Id: pazpar2_conf.xml,v 1.26 2007-06-06 12:02:48 marc Exp $ -->
542 <!-- mapping for unqualified search -->
543 <set name="pz:cclmap:term" value="u=1016 t=l,r s=al"/>
545 <!-- field-specific mappings -->
546 <set name="pz:cclmap:ti" value="u=4 s=al"/>
547 <set name="pz:cclmap:su" value="u=21 s=al"/>
548 <set name="pz:cclmap:isbn" value="u=7"/>
549 <set name="pz:cclmap:issn" value="u=8"/>
550 <set name="pz:cclmap:date" value="u=30 r=r"/>
552 <!-- Retrieval settings -->
554 <set name="pz:requestsyntax" value="marc21"/>
555 <!-- <set name="pz:elements" value="F"/> NOT YET IMPLEMENTED -->
557 <!-- Result normalization settings -->
559 <set name="pz:nativesyntax" value="iso2709"/>
560 <set name="pz:xslt" value="../etc/marc21.xsl"/>
568 The next example shows certain settings overriden for one target,
569 one which returns XML records containing DublinCore elements, and
570 which furthermore requires a username/password.
572 <settings target="funkytarget.com:210/db1">
573 <set name="pz:requestsyntax" value="xml"/>
574 <set name="pz:nativesyntax" value="xml"/>
575 <set name="pz:xslt" value="../etc/dublincore.xsl"/>
577 <set name="pz:authentication" value="myuser/password"/>
583 The following example associates a specific name/value combination
584 with a number of targets. The targets below are access-restricted,
585 and can only be used by users with special credentials.
587 <settings name="pz:allow" value="0">
588 <set target="funkytarget.com:210/*"/>
589 <set target="commercial.com:2100/expensiveDb"/>
596 <refsect2><title>RESERVED SETTING NAMES</title>
598 The following setting names are reserved by pazpar2 to control the
599 behavior of the client function.
604 <term>pz:cclmap:xxx</term>
607 This establishes a CCL field definition or other setting, for
608 the purpose of mapping end-user queries. XXX is the field or
609 setting name, and the value of the setting provides parameters
610 (e.g. parameters to send to the server, etc.). Please consult
611 the YAZ manual for a full overview of the many capabilities of
612 the powerful and flexible CCL parser.
615 Note that it is easy to etablish a set of default parameters,
616 and then override them individually for a given target.
621 <term>pz:requestsyntax</term>
624 This specifies the record syntax to use when requesting
625 records from a given server. The value can be a symbolic name like
626 marc21 or xml, or it can be a Z39.50-style dot-separated OID.
631 <term>pz:elements</term>
634 The element set name to be used when retrieving records from a
635 server (not yet implemented).
640 <term>pz:piggyback</term>
643 Piggybacking enables the server to retrieve records from the
644 server as part of the search response in Z39.50. Almost all
645 servers support this (or fail it gracefully), but a few
646 servers will produce undesirable results.
647 Set to '1' to enable piggybacking, '0' to disable it. Default
648 is 1 (piggybacking enabled).
653 <term>pz:nativesyntax</term>
656 The representation (syntax) of the retrieval records. Currently
657 recognized values are iso2709 and xml.
660 For iso2709, can also specify a native character set, e.g. "iso2709;latin-1".
661 If no character set is provided, MARC-8 is assumed.
669 Provides the path of an XSLT stylesheet which will be used to
670 map incoming records to the internal representation.
675 <term>pz:authentication</term>
678 Sets an authentication string for a given server. See the section on
679 authorization and authentication for discussion.
684 <term>pz:allow</term>
687 Allows or denies access to the resources it is applied to. Possible
688 values are '0' and '1'. The default is '1' (allow access to this resource).
689 See the manual section on authorization and authentication for discussion
690 about how to use this setting.
695 <term>pz:maxrecs</term>
698 Controls the maximum number of records to be retrieved from a
699 server. The default is 100 (not yet implemented).
707 This setting can't be 'set' -- it contains the ID (normally
708 ZURL) for a given target, and is useful for filtering --
709 specifically when you want to select one or more specific
710 targets in the search command.
715 <term>pz:zproxy</term>
718 The 'pz:zproxy' setting has the value syntax
719 'host.internet.adress:port', it is used to tunnel Z39.50
720 requests through the named Z39.50 proxy.
729 <!-- Keep this comment at the end of the file
734 sgml-minimize-attributes:nil
735 sgml-always-quote-attributes:t
738 sgml-parent-document:nil
739 sgml-local-catalogs: nil
740 sgml-namecase-general:t