doc/pazpar2_conf.xml

   1 <?xml version="1.0" standalone="no"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
   3  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
   4 [
   5      <!ENTITY % local SYSTEM "local.ent">
   6      %local;
   7      <!ENTITY % entities SYSTEM "entities.ent">
   8      %entities;
   9      <!ENTITY % idcommon SYSTEM "common/common.ent">
  10      %idcommon;
  11 ]>
  12 <refentry id="pazpar2_conf">
  13  <refentryinfo>
  14   <productname>Pazpar2</productname>
  15   <productnumber>&version;</productnumber>
  16   <info><orgname>Index Data</orgname></info>
  17  </refentryinfo>
  18
  19  <refmeta>
  20   <refentrytitle>Pazpar2 conf</refentrytitle>
  21   <manvolnum>5</manvolnum>
  22   <refmiscinfo class="manual">File formats and conventions</refmiscinfo>
  23  </refmeta>
  24
  25  <refnamediv>
  26   <refname>pazpar2_conf</refname>
  27   <refpurpose>Pazpar2 Configuration</refpurpose>
  28  </refnamediv>
  29
  30  <refsynopsisdiv>
  31   <cmdsynopsis>
  32    <command>pazpar2.conf</command>
  33   </cmdsynopsis>
  34  </refsynopsisdiv>
  35
  36  <refsect1>
  37   <title>DESCRIPTION</title>
  38   <para>
  39    The Pazpar2 configuration file, together with any referenced XSLT files,
  40    govern Pazpar2's behavior as a client, and control the normalization and
  41    extraction of data elements from incoming result records, for the
  42    purposes of merging, sorting, facet analysis, and display.
  43   </para>
  44
  45   <para>
  46    The file is specified using the option -f on the Pazpar2 command line.
  47    There is not presently a way to reload the configuration file without
  48    restarting Pazpar2, although this will most likely be added some time
  49    in the future.
  50   </para>
  51  </refsect1>
  52
  53  <refsect1>
  54   <title>FORMAT</title>
  55   <para>
  56    The configuration file is XML-structured. It must be well-formed XML. All
  57    elements specific to Pazpar2 should belong to the namespace
  58    <literal>http://www.indexdata.com/pazpar2/1.0</literal>
  59    (this is assumed in the
  60    following examples). The root element is named "<literal>pazpar2</literal>".
  61    Under the  root element are a number of elements which group categories of
  62    information. The categories are described below.
  63   </para>
  64
  65   <refsect2 id="config-threads">
  66    <title>threads</title>
  67    <para>
  68     This section is optional and is supported for Pazpar2 version 1.3.1 and
  69     later . It is identified by element "<literal>threads</literal>" which
  70     may include one attribute "<literal>number</literal>" which specifies
  71     the number of worker-threads that the Pazpar2 instance is to use.
  72     A value of 0 (zero) disables worker-threads (all work is carried out
  73     in main thread).
  74    </para>
  75   </refsect2>
  76   <refsect2 id="config-server">
  77    <title>server</title>
  78    <para>
  79     This section governs overall behavior of a server endpoint. It is identified
  80     by the element "server" which takes an optional attribute, "id", which
  81     identifies this particular Pazpar2 server. Any string value for "id"
  82     may be given.
  83    </para>
  84    <para>
  85     The data
  86     elements are described below. From Pazpar2 version 1.2 this is
  87     a repeatable element.
  88    </para>
  89    <variablelist> <!-- level 1 -->
  90     <varlistentry>
  91      <term>listen</term>
  92      <listitem>
  93       <para>
  94        Configures the webservice -- this controls how you can connect
  95        to Pazpar2 from your browser or server-side code. The
  96        attributes 'host' and 'port' control the binding of the
  97        server. The 'host' attribute can be used to bind the server to
  98        a secondary IP address of your system, enabling you to run
  99        Pazpar2 on port 80 alongside a conventional web server. You
 100        can override this setting on the command line using the option -h.
 101       </para>
 102      </listitem>
 103     </varlistentry>
 104
 105     <varlistentry>
 106      <term>proxy</term>
 107      <listitem>
 108       <para>
 109        If this item is given, Pazpar2 will forward all incoming HTTP
 110        requests that do not contain the filename 'search.pz2' to the
 111        host and port specified using the 'host' and 'port'
 112        attributes. The 'myurl' attribute is required, and should provide
 113        the base URL of the server. Generally, the HTTP URL for the host
 114        specified in the 'listen' parameter. This functionality is
 115        crucial if you wish to use
 116        Pazpar2 in conjunction with browser-based code (JS, Flash,
 117        applets, etc.) which operates in a security sandbox. Such code
 118        can only connect to the same server from which the enclosing
 119        HTML page originated. Pazpar2s proxy functionality enables you
 120        to host all of the main pages (plus images, CSS, etc) of your
 121        application on a conventional webserver, while efficiently
 122        processing webservice requests for metasearch status, results,
 123        etc.
 124       </para>
 125      </listitem>
 126     </varlistentry>
 127
 128     <varlistentry>
 129      <term>icu_chain</term>
 130      <listitem>
 131       <para>
 132        Specifies character set normalization for relevancy / sorting /
 133        mergekey and facets - for the server. These definitions serves as
 134        default for services that don't have these given. For the meaning
 135        of these settings refer to the
 136        <xref linkend="icuchain"/> element inside service.
 137       </para>
 138      </listitem>
 139     </varlistentry>
 140
 141     <varlistentry>
 142      <term>relevance / sort / mergekey / facet</term>
 143      <listitem>
 144       <para>
 145        Obsolete. Use element icu_chain instead.
 146       </para>
 147      </listitem>
 148     </varlistentry>
 149
 150     <varlistentry>
 151      <term>settings</term>
 152      <listitem>
 153       <para>
 154        Specifies target settings for the server.. These settings serves
 155        as default for all services which don't have these given.
 156        The settings element requires one attribute 'src' which specifies
 157        a settings file or a directory . If a directory is given all
 158        files with suffix <filename>.xml</filename> is read from this
 159        directory. Refer to
 160        <xref linkend="target_settings"/> for more information.
 161       </para>
 162      </listitem>
 163     </varlistentry>
 164
 165     <varlistentry>
 166      <term>service</term>
 167      <listitem>
 168       <para>
 169        This nested element controls the behavior of Pazpar2 with
 170        respect to your data model. In Pazpar2, incoming records are
 171        normalized, using XSLT, into an internal representation.
 172        The 'service' section controls the further processing and
 173        extraction of data from the internal representation, primarily
 174        through the 'metadata' sub-element.
 175       </para>
 176       <para>
 177        Pazpar2 version 1.2 and later allows multiple service elements.
 178        Multiple services must be given a unique ID by specifying
 179        attribute <literal>id</literal>.
 180        A single service may be unnamed (service ID omitted). The
 181        service ID is referred to in the
 182        <link linkend="command-init"><literal>init</literal></link> webservice
 183        command's <literal>service</literal> parameter.
 184       </para>
 185
 186       <variablelist> <!-- Level 2 -->
 187        <varlistentry>
 188         <term>metadata</term>
 189         <listitem>
 190          <para>
 191           One of these elements is required for every data element in
 192           the internal representation of the record (see
 193           <xref linkend="data_model"/>. It governs
 194           subsequent processing as pertains to sorting, relevance
 195           ranking, merging, and display of data elements. It supports
 196           the following attributes:
 197          </para>
 198
 199          <variablelist> <!-- level 3 -->
 200           <varlistentry>
 201            <term>name</term>
 202            <listitem>
 203             <para>
 204              This is the name of the data element. It is matched
 205              against the 'type' attribute of the
 206              'metadata' element
 207              in the normalized record. A warning is produced if
 208              metadata elements with an unknown name are
 209              found in the
 210              normalized record. This name is also used to
 211              represent
 212              data elements in the records returned by the
 213              webservice API, and to name sort lists and browse
 214              facets.
 215             </para>
 216            </listitem>
 217           </varlistentry>
 218
 219           <varlistentry>
 220            <term>type</term>
 221            <listitem>
 222             <para>
 223              The type of data element. This value governs any
 224              normalization or special processing that might take
 225              place on an element. Possible values are 'generic'
 226              (basic string), 'year' (a range is computed if
 227              multiple years are found in the record). Note: This
 228              list is likely to increase in the future.
 229             </para>
 230            </listitem>
 231           </varlistentry>
 232
 233           <varlistentry>
 234            <term>brief</term>
 235            <listitem>
 236             <para>
 237              If this is set to 'yes', then the data element is
 238              includes in brief records in the webservice API. Note
 239              that this only makes sense for metadata elements that
 240              are merged (see below). The default value is 'no'.
 241             </para>
 242            </listitem>
 243           </varlistentry>
 244
 245           <varlistentry>
 246            <term>sortkey</term>
 247            <listitem>
 248             <para>
 249              Specifies that this data element is to be used for
 250              sorting. The possible values are 'numeric' (numeric
 251              value), 'skiparticle' (string; skip common, leading
 252              articles), and 'no' (no sorting). The default value is
 253              'no'.
 254             </para>
 255            </listitem>
 256           </varlistentry>
 257
 258           <varlistentry>
 259            <term>rank</term>
 260            <listitem>
 261             <para>
 262              Specifies that this element is to be used to
 263              help rank
 264              records against the user's query (when ranking is
 265              requested). The value is an integer, used as a
 266              multiplier against the basic TF*IDF score. A value of
 267              1 is the base, higher values give additional
 268              weight to
 269              elements of this type. The default is '0', which
 270              excludes this element from the rank calculation.
 271             </para>
 272            </listitem>
 273           </varlistentry>
 274
 275           <varlistentry>
 276            <term>termlist</term>
 277            <listitem>
 278             <para>
 279              Specifies that this element is to be used as a
 280              termlist, or browse facet. Values are tabulated from
 281              incoming records, and a highscore of values (with
 282              their associated frequency) is made available to the
 283              client through the webservice API.
 284              The possible values
 285              are 'yes' and 'no' (default).
 286             </para>
 287            </listitem>
 288           </varlistentry>
 289
 290           <varlistentry>
 291            <term>merge</term>
 292            <listitem>
 293             <para>
 294              This governs whether, and how elements are extracted
 295              from individual records and merged into cluster
 296              records. The possible values are: 'unique' (include
 297              all unique elements), 'longest' (include only the
 298              longest element (strlen), 'range' (calculate a range
 299              of values across all matching records), 'all' (include
 300              all elements), or 'no' (don't merge; this is the
 301              default);
 302             </para>
 303            </listitem>
 304           </varlistentry>
 305
 306           <varlistentry>
 307            <term>mergekey</term>
 308            <listitem>
 309             <para>
 310              If set to '<literal>required</literal>', the value of this
 311              metadata element is appended to the resulting mergekey if
 312              the metadata is present in a record instance.
 313              If the metadata element is not present, the a unique mergekey
 314              will be generated instead.
 315             </para>
 316             <para>
 317              If set to '<literal>optional</literal>', the value of this
 318              metadata element is appended to the resulting mergekey if the
 319              the metadata is present in a record instance. If the metadata
 320              is not present, it will be empty.
 321             </para>
 322             <para>
 323              If set to '<literal>no</literal>' or the mergekey attribute is
 324              omitted, the metadata will not be used in the creation of a
 325              mergekey.
 326             </para>
 327            </listitem>
 328           </varlistentry>
 329
 330           <varlistentry>
 331            <term id="facetrule">facetrule</term>
 332            <listitem>
 333             <para>
 334              Specifies the ICU rule set to be used for normalizing
 335              facets. If facetrule is omitted from metadata, the
 336              rule set 'facet' is used.
 337             </para>
 338            </listitem>
 339           </varlistentry>
 340
 341           <varlistentry>
 342            <term>setting</term>
 343            <listitem>
 344             <para>
 345              This attribute allows you to make use of static database
 346              settings in the processing of records. Three possible values
 347              are allowed. 'no' is the default and doesn't do anything.
 348              'postproc' copies the value of a setting with the same name
 349              into the output of the normalization stylesheet(s). 'parameter'
 350              makes the value of a setting with the same name available
 351              as a parameter to the normalization stylesheet, so you
 352              can further process the value inside of the stylesheet, or use
 353              the value to decide how to deal with other data values.
 354             </para>
 355             <para>
 356              The purpose of using settings in this way can either be to
 357              control the behavior of normalization stylesheet in a database-
 358              dependent way, or to easily make database-dependent values
 359              available to display-logic in your user interface, without having
 360              to implement complicated interactions between the user interface
 361              and your configuration system.
 362             </para>
 363            </listitem>
 364           </varlistentry>
 365
 366          </variablelist> <!-- attributes to metadata -->
 367
 368         </listitem>
 369        </varlistentry>
 370
 371        <varlistentry>
 372         <term id="servicexslt" xreflabel="xslt">xslt</term>
 373         <listitem>
 374          <para>
 375           Defines a XSLT stylesheet. The <literal>xslt</literal>
 376           element takes exactly one attribute <literal>id</literal>
 377           which names the stylesheet. This can be referred to in target
 378           settings <xref linkend="pzxslt"/>.
 379          </para>
 380          <para>
 381           The content of the xslt element is the embedded stylesheet XML
 382          </para>
 383         </listitem>
 384        </varlistentry>
 385        <varlistentry>
 386         <term id="icuchain" xreflabel="icu_chain">icu_chain</term>
 387         <listitem>
 388          <para>
 389           Specifies a named ICU rule set. The icu_chain element must include
 390           attribute 'id' which specifies the identifier (name) for the ICU
 391           rule set.
 392           Pazpar2 uses the particular rule sets for particular purposes.
 393           Rule set 'relevance' is used to normalize
 394           terms for relevance ranking. Rule set 'sort' is used to
 395           normalize terms for sorting. Rule set 'mergekey' is used to
 396           normalize terms for making a mergekey and, finally. Rule set 'facet'
 397           is normally used to normalize facet terms, unless
 398           <xref linkend="facetrule">facetrule</xref> is given for a
 399           metadata field.
 400          </para>
 401          <para>
 402           The icu_chain element must also include a 'locale'
 403           attribute which must be set to one of the locale strings
 404           defined in ICU. The child elements listed below can be
 405           in any order, except the 'index' element which logically
 406           belongs to the end of the list. The stated tokenization,
 407           transformation and charmapping instructions are performed
 408           in order from top to bottom.
 409          </para>
 410          <variablelist> <!-- Level 2 -->
 411           <varlistentry>
 412            <term>casemap</term>
 413            <listitem>
 414             <para>
 415              The attribute 'rule' defines the direction of the
 416              per-character casemapping, allowed values are "l"
 417              (lower), "u" (upper), "t" (title).
 418             </para>
 419            </listitem>
 420           </varlistentry>
 421           <varlistentry>
 422            <term>transform</term>
 423            <listitem>
 424             <para>
 425              Normalization and transformation of tokens follows
 426              the rules defined in the 'rule' attribute. For
 427              possible values we refer to the extensive ICU
 428              documentation found at the
 429              <ulink url="&url.icu.transform;">ICU
 430              transformation</ulink> home page. Set filtering
 431              principles are explained at the
 432              <ulink url="&url.icu.unicode.set;">ICU set and
 433              filtering</ulink> page.
 434             </para>
 435            </listitem>
 436           </varlistentry>
 437           <varlistentry>
 438            <term>tokenize</term>
 439            <listitem>
 440             <para>
 441              Tokenization is the only rule in the ICU chain
 442              which splits one token into multiple tokens. The
 443              'rule' attribute may have the following values:
 444              "s" (sentence), "l" (line-break), "w" (word), and
 445              "c" (character), the later probably not being
 446              very useful in a pruning Pazpar2 installation.
 447             </para>
 448            </listitem>
 449           </varlistentry>
 450          </variablelist>
 451          <para>
 452           From Pazpar2 version 1.1 the ICU wrapper from YAZ is used.
 453           Refer to the <ulink url="&url.yaz.yaz-icu;">yaz-icu</ulink>
 454           utility for more information.
 455          </para>
 456         </listitem>
 457        </varlistentry>
 458
 459        <varlistentry>
 460         <term>relevance</term>
 461         <listitem>
 462          <para>
 463           Specifies the ICU rule set used for relevance ranking.
 464           The child element of 'relevance' must be 'icu_chain' and the
 465           'id' attribute of the icu_chain is ignored. This
 466           definition is obsolete and should be replaced by the equivalent
 467           construct:
 468           <screen>
 469            &lt;icu_chain id="relevance" locale="en">..&lt;icu_chain>
 470           </screen>
 471          </para>
 472         </listitem>
 473        </varlistentry>
 474
 475        <varlistentry>
 476         <term>sort</term>
 477         <listitem>
 478          <para>
 479           Specifies the ICU rule set used for sorting.
 480           The child element of 'sort' must be 'icu_chain' and the
 481           'id' attribute of the icu_chain is ignored. This
 482           definition is obsolete and should be replaced by the equivalent
 483           construct:
 484           <screen>
 485            &lt;icu_chain id="sort" locale="en">..&lt;icu_chain>
 486           </screen>
 487          </para>
 488         </listitem>
 489        </varlistentry>
 490
 491        <varlistentry>
 492         <term>mergekey</term>
 493         <listitem>
 494          <para>
 495           Specifies ICU tokenization and transformation rules
 496           for tokens that are used in Pazpar2's mergekey.
 497           The child element of 'mergekey' must be 'icu_chain' and the
 498           'id' attribute of the icu_chain is ignored. This
 499           definition is obsolete and should be replaced by the equivalent
 500           construct:
 501           <screen>
 502            &lt;icu_chain id="mergekey" locale="en">..&lt;icu_chain>
 503           </screen>
 504          </para>
 505         </listitem>
 506        </varlistentry>
 507
 508        <varlistentry>
 509         <term>facet</term>
 510         <listitem>
 511          <para>
 512           Specifies ICU tokenization and transformation rules
 513           for tokens that are used in Pazpar2's facets.
 514           The child element of 'facet' must be 'icu_chain' and the
 515           'id' attribute of the icu_chain is ignored. This
 516           definition is obsolete and should be replaced by the equivalent
 517           construct:
 518           <screen>
 519            &lt;icu_chain id="facet" locale="en">..&lt;icu_chain>
 520           </screen>
 521          </para>
 522         </listitem>
 523        </varlistentry>
 524
 525        <varlistentry>
 526         <term>settings</term>
 527         <listitem>
 528          <para>
 529           Specifies target settings for this service. Refer to
 530           <xref linkend="target_settings"/>.
 531          </para>
 532         </listitem>
 533        </varlistentry>
 534
 535        <varlistentry>
 536         <term>timeout</term>
 537         <listitem>
 538          <para>
 539           Specifies timeout parameters for this service.
 540           The <literal>timeout</literal>
 541           element supports the following attributes:
 542           <literal>session</literal>, <literal>z3950_operation</literal>,
 543           <literal>z3950_session</literal> which specifies
 544           'session timeout', 'Z39.50 operation timeout',
 545           'Z39.50 session timeout' respectively. The Z39.50 operation
 546           timeout is the time Pazpar2 will wait for an active Z39.50/SRU
 547           operation before it gives up (times out). The Z39.50 session
 548           time out is the time Pazpar2 will keep the session alive for
 549           an idle session (no operation).
 550          </para>
 551          <para>
 552           The following is recommended but not required:
 553           z3950_operation (30) &lt; session (60) &lt; z3950_session (180) .
 554           The default values are given in parantheses.
 555          </para>
 556         </listitem>
 557        </varlistentry>
 558       </variablelist>     <!-- Data elements in service directive -->
 559      </listitem>
 560     </varlistentry>
 561    </variablelist>           <!-- Data elements in server directive -->
 562   </refsect2>
 563  </refsect1>
 564
 565  <refsect1>
 566   <title>EXAMPLE</title>
 567   <para>
 568    Below is a working example configuration:
 569   </para>
 570   <screen>
 571    <![CDATA[
 572 <?xml version="1.0" encoding="UTF-8"?>
 573 <pazpar2 xmlns="http://www.indexdata.com/pazpar2/1.0">
 574
 575  <threads number="10"/>
 576  <server>
 577   <listen port="9004"/>
 578   <service>
 579    <metadata name="title" brief="yes" sortkey="skiparticle"
 580              merge="longest" rank="6"/>
 581    <metadata name="isbn" merge="unique"/>
 582    <metadata name="date" brief="yes" sortkey="numeric"
 583              type="year" merge="range" termlist="yes"/>
 584    <metadata name="author" brief="yes" termlist="yes"
 585              merge="longest" rank="2"/>
 586    <metadata name="subject" merge="unique" termlist="yes" rank="3"/>
 587    <metadata name="url" merge="unique"/>
 588    <icu_chain id="relevance" locale="el">
 589     <transform rule="[:Control:] Any-Remove"/>
 590     <tokenize rule="l"/>
 591     <transform rule="[[:WhiteSpace:][:Punctuation:]] Remove"/>
 592     <casemap rule="l"/>
 593    </icu_chain>
 594    <settings src="mysettings"/>
 595    <timeout session="60"/>
 596   <service>
 597  </server>
 598 </pazpar2>
 599    ]]>
 600   </screen>
 601  </refsect1>
 602
 603  <refsect1 id="config-include">
 604   <title>INCLUDE FACILITY</title>
 605   <para>
 606    The XML configuration may be partitioned into multiple files by using
 607    the <literal>include</literal> element which takes a single attribute,
 608    <literal>src</literal>. The of the <literal>src</literal> attribute is
 609    regular Shell like glob-pattern. For example,
 610    <screen><![CDATA[
 611    <include src="/etc/pazpar2/conf.d/*.xml"/>
 612    ]]></screen>
 613   </para>
 614   <para>
 615    The include facility requires Pazpar2 version 1.2.
 616   </para>
 617  </refsect1>
 618
 619  <refsect1 id="target_settings">
 620   <title>TARGET SETTINGS</title>
 621   <para>
 622    Pazpar2 features a cunning scheme by which you can associate various
 623    kinds of attributes, or settings with search targets. This can be done
 624    through XML files which are read at startup; each file can associate
 625    one or more settings with one or more targets. The file format is generic
 626    in nature, designed to support a wide range of application requirements. The
 627    settings can be purely technical things, like, how to perform a title
 628    search against a given target, or it can associate arbitrary name=value
 629    pairs with groups of targets -- for instance, if you would like to
 630    place all commercial full-text bases in one group for selection
 631    purposes, or you would like to control what targets are accessible
 632    to users by default. Per-database settings values can even be used
 633    to drive sorting, facet/termlist generation, or end-user interface display
 634    logic.
 635   </para>
 636
 637   <para>
 638    During startup, Pazpar2 will recursively read a specified directory
 639    (can be identified in the pazpar2.cfg file or on the command line), and
 640    process any settings files found therein.
 641   </para>
 642
 643   <para>
 644    Clients of the Pazpar2 webservice interface can selectively override
 645    settings for individual targets within the scope of one session. This
 646    can be used in conjunction with an external authentication system to
 647    determine which resources are to be accessible to which users. Pazpar2
 648    itself has no notion of end-users, and so can be used in conjunction
 649    with any type of authentication system. Similarly, the authentication
 650    tokens submitted to access-controlled search targets can similarly be
 651    overridden, to allow use of Pazpar2 in a consortial or multi-library
 652    environment, where different end-users may need to be represented to
 653    some search targets in different ways. This, again, can be managed
 654    using an external database or other lookup mechanism. Setting overrides
 655    can be performed either using the
 656    <link linkend="command-init">init</link> or the
 657    <link linkend="command-settings">settings</link> webservice
 658    command.
 659   </para>
 660
 661   <para>
 662    In fact, every setting that applies to a database (except pz:id, which
 663    can only be used for filtering targets to use for a search) can be overridden
 664    on a per-session basis. This allows the client to override specific CCL fields
 665    for searching, etc., to meet the needs of a session or user.
 666   </para>
 667
 668   <para>
 669    Finally, as an extreme case of this, the webservice client can
 670    introduce entirely new targets, on the fly, as part of the
 671    <link linkend="command-init">init</link> or
 672    <link linkend="command-settings">settings</link> command.
 673    This is useful if you desire to manage information
 674    about your search targets in a separate application such as a database.
 675    You do not need any static settings file whatsoever to run Pazpar2 -- as
 676    long as the webservice client is prepared to supply the necessary
 677    information at the beginning of every session.
 678   </para>
 679
 680   <note>
 681    <para>
 682     The following discussion of practical issues related to session
 683     and settings management are cast in terms of a user interface based on
 684     Ajax/Javascript technology. It would apply equally well to many other
 685     kinds of browser-based logic.
 686    </para>
 687   </note>
 688
 689   <para>
 690    Typically, a Javascript client is not allowed to directly alter the
 691    parameters of a session. There are two reasons for this. One has to do
 692    with access to information; typically, information about a user will
 693    be stored in a system on the server side, or it will be accessible in
 694    some way from the server.  However, since the Javascript client cannot
 695    be entirely trusted (some hostile agent might in fact 'pretend' to be
 696    a regular ws client), it is more robust to control session settings
 697    from scripting that you run as part of your webserver. Typically, this
 698    can be handled during the session initialization, as follows:
 699   </para>
 700
 701   <para>
 702    Step 1: The Javascript client loads, and asks the webserver for a
 703    new Pazpar2 session ID. This can be done using a Javascript call, for
 704    instance. Note that it is possible to submit Ajax HTTPXmlRequest calls
 705    either to Pazpar2 or to the webserver that Pazpar2 is proxying
 706    for. See (XXX Insert link to Pazpar2 protocol).
 707   </para>
 708
 709   <para>
 710    Step 2: Code on the webserver authenticates the user, by database lookup,
 711    LDAP access, NCIP, etc. Determines which resources the user has access to,
 712    and any user-specific parameters that are to be applied during this session.
 713   </para>
 714
 715   <para>
 716    Step 3: The webserver initializes a new Pazpar2 settings, and sets
 717    user-specific parameters as necessary, using the init webservice
 718    command. A new session ID is returned.
 719   </para>
 720
 721   <para>
 722    Step 4: The webserver returns this session ID to the Javascript
 723    client, which then uses the session ID to submit searches, show
 724    results, etc.
 725   </para>
 726
 727   <para>
 728    Step 5: When the Javascript client ceases to use the session,
 729    Pazpar2 destroys any session-specific information.
 730   </para>
 731
 732   <refsect2>
 733    <title>SETTINGS FILE FORMAT</title>
 734    <para>
 735     Each file contains a root element named &lt;settings&gt;. It may
 736     contain one or more &lt;set&gt; elements. The settings and set
 737     elements may contain the following attributes. Attributes in the set
 738     node overrides those in the setting root element. Each set node must
 739     specify (directly, or inherited from the parent node) at least a
 740     target, name, and value.
 741    </para>
 742
 743    <variablelist>
 744     <varlistentry>
 745      <term>target</term>
 746      <listitem>
 747       <para>
 748        This specifies the search target to which this setting should be
 749        applied. Targets are identified by their Z39.50 URL, generally
 750        including the host, port, and database name, (e.g.
 751        <literal>bagel.indexdata.com:210/marc</literal>).
 752        Two wildcard forms are accepted:
 753        * (asterisk) matches all known targets;
 754        <literal>bagel.indexdata.com:210/*</literal> matches all
 755        known databases on the given host.
 756       </para>
 757       <para>
 758        A precedence system determines what happens if there are
 759        overlapping values for the same setting name for the same
 760        target. A setting for a specific target name overrides a
 761        setting which specifies target using a wildcard. This makes it
 762        easy to set defaults for all targets, and then override them
 763        for specific targets or hosts. If there are
 764        multiple overlapping settings with the same name and target
 765        value, the 'precedence' attribute determines what happens.
 766       </para>
 767       <para>
 768        For Pazpar2 1.6.4 or later, the target ID may be user-defined, in
 769        which case, the actual host, port, etc is given by setting
 770        <xref linkend="pzurl"/>.
 771       </para>
 772      </listitem>
 773     </varlistentry>
 774     <varlistentry>
 775      <term>name</term>
 776      <listitem>
 777       <para>
 778        The name of the setting. This can be anything you like.
 779        However, Pazpar2 reserves a number of setting names for
 780        specific purposes, all starting with 'pz:', and it is a good
 781        idea to avoid that prefix if you make up your own setting
 782        names. See below for a list of reserved variables.
 783       </para>
 784      </listitem>
 785     </varlistentry>
 786     <varlistentry>
 787      <term>value</term>
 788      <listitem>
 789       <para>
 790        The value of the setting. Generally, this can be anything you
 791        want -- however, some of the reserved settings may expect
 792        specific kinds of values.
 793       </para>
 794      </listitem>
 795     </varlistentry>
 796     <varlistentry>
 797      <term>precedence</term>
 798      <listitem>
 799       <para>
 800        This should be an integer. If not provided, the default value
 801        is 0. If two (or more) settings have the same content for
 802        target and name, the precedence value determines the outcome.
 803        If both settings have the same precedence value, they are both
 804        applied to the target(s). If one has a higher value, then the
 805        value of that setting is applied, and the other one is ignored.
 806       </para>
 807      </listitem>
 808     </varlistentry>
 809    </variablelist>
 810
 811    <para>
 812     By setting defaults for target, name, or value in the root
 813     settings node, you can use the settings files in many different
 814     ways. For instance, you can use a single file to set defaults for
 815     many different settings, like search fields, retrieval syntaxes,
 816     etc. You can have one file per server, which groups settings for
 817     that server or target. You could also have one file which associates
 818     a number of targets with a given setting, for instance, to associate
 819     many databases with a given category or class that makes sense
 820     within your application.
 821    </para>
 822
 823    <para>
 824     The following examples illustrate uses of the settings system to
 825     associate settings with targets to meet different requirements.
 826    </para>
 827
 828    <para>
 829     The example below associates a set of default values that can be
 830     used across many targets. Note the wildcard for targets.
 831     This associates the given settings with all targets for which no
 832     other information is provided.
 833     <screen><![CDATA[
 834     <settings target="*">
 835
 836     <!-- This file introduces default settings for pazpar2 -->
 837
 838     <!-- mapping for unqualified search -->
 839     <set name="pz:cclmap:term" value="u=1016 t=l,r s=al"/>
 840
 841     <!-- field-specific mappings -->
 842     <set name="pz:cclmap:ti" value="u=4 s=al"/>
 843     <set name="pz:cclmap:su" value="u=21 s=al"/>
 844     <set name="pz:cclmap:isbn" value="u=7"/>
 845     <set name="pz:cclmap:issn" value="u=8"/>
 846     <set name="pz:cclmap:date" value="u=30 r=r"/>
 847
 848     <set name="pz:limitmap:title" value="rpn:@attr 1=4 @attr 6=3"/>
 849     <set name="pz:limitmap:date" value="ccl:date"/>
 850
 851     <!-- Retrieval settings -->
 852
 853     <set name="pz:requestsyntax" value="marc21"/>
 854     <set name="pz:elements" value="F"/>
 855
 856     <!-- Query encoding -->
 857     <set name="pz:queryencoding" value="iso-8859-1"/>
 858
 859     <!-- Result normalization settings -->
 860
 861     <set name="pz:nativesyntax" value="iso2709"/>
 862     <set name="pz:xslt" value="../etc/marc21.xsl"/>
 863
 864     </settings>
 865
 866     ]]></screen>
 867    </para>
 868
 869    <para>
 870     The next example shows certain settings overridden for one target,
 871     one which returns XML records containing DublinCore elements, and
 872     which furthermore requires a username/password.
 873     <screen><![CDATA[
 874     <settings target="funkytarget.com:210/db1">
 875     <set name="pz:requestsyntax" value="xml"/>
 876     <set name="pz:nativesyntax" value="xml"/>
 877     <set name="pz:xslt" value="../etc/dublincore.xsl"/>
 878
 879     <set name="pz:authentication" value="myuser/password"/>
 880     </settings>
 881     ]]></screen>
 882    </para>
 883
 884    <para>
 885     The following example associates a specific name/value combination
 886     with a number of targets. The targets below are access-restricted,
 887     and can only be used by users with special credentials.
 888     <screen><![CDATA[
 889     <settings name="pz:allow" value="0">
 890     <set target="funkytarget.com:210/*"/>
 891     <set target="commercial.com:2100/expensiveDb"/>
 892     </settings>
 893     ]]></screen>
 894    </para>
 895
 896   </refsect2>
 897
 898   <refsect2>
 899    <title>RESERVED SETTING NAMES</title>
 900    <para>
 901     The following setting names are reserved by Pazpar2 to control the
 902     behavior of the client function.
 903    </para>
 904
 905    <variablelist>
 906     <varlistentry>
 907      <term>pz:cclmap:xxx</term>
 908      <listitem>
 909       <para>
 910        This establishes a CCL field definition or other setting, for
 911        the purpose of mapping end-user queries. XXX is the field or
 912        setting name, and the value of the setting provides parameters
 913        (e.g. parameters to send to the server, etc.). Please consult
 914        the YAZ manual for a full overview of the many capabilities of
 915        the powerful and flexible CCL parser.
 916       </para>
 917       <para>
 918        Note that it is easy to establish a set of default parameters,
 919        and then override them individually for a given target.
 920       </para>
 921      </listitem>
 922     </varlistentry>
 923     <varlistentry id="requestsyntax">
 924      <term>pz:requestsyntax</term>
 925      <listitem>
 926       <para>
 927        This specifies the record syntax to use when requesting
 928        records from a given server. The value can be a symbolic name like
 929        marc21 or xml, or it can be a Z39.50-style dot-separated OID.
 930       </para>
 931      </listitem>
 932     </varlistentry>
 933     <varlistentry>
 934      <term>pz:elements</term>
 935      <listitem>
 936       <para>
 937        The element set name to be used when retrieving records from a
 938        server.
 939       </para>
 940      </listitem>
 941     </varlistentry>
 942     <varlistentry>
 943      <term>pz:piggyback</term>
 944      <listitem>
 945       <para>
 946        Piggybacking enables the server to retrieve records from the
 947        server as part of the search response in Z39.50. Almost all
 948        servers support this (or fail it gracefully), but a few
 949        servers will produce undesirable results.
 950        Set to '1' to enable piggybacking, '0' to disable it. Default
 951        is 1 (piggybacking enabled).
 952       </para>
 953      </listitem>
 954     </varlistentry>
 955     <varlistentry>
 956      <term>pz:nativesyntax</term>
 957      <listitem>
 958       <para>
 959        Specifies how Pazpar2 shoule map retrieved records to XML. Currently
 960        supported values are <literal>xml</literal>,
 961        <literal>iso2709</literal> and <literal>txml</literal>.
 962       </para>
 963       <para>
 964        The value <literal>iso2709</literal> makes Pazpar2 convert retrieved
 965        MARC records to MARCXML. In order to convert to XML, the exact
 966        chacater set of the MARC must be known (if not, the resulting
 967        XML is probably not well-formed). The character set may be
 968        specified by adding:
 969        <literal>;charset=</literal><replaceable>charset</replaceable> to
 970        <literal>iso2709</literal>. If omitted, a charset of
 971        MARC-8 is assumed. This is correct for most MARC21/USMARC records.
 972       </para>
 973       <para>
 974        The value <literal>txml</literal> is like <literal>iso2709</literal>
 975        except that records are converted to TurboMARC instead of MARCXML.
 976       </para>
 977       <para>
 978        The value <literal>xml</literal> is used if Pazpar2 retrieves
 979        records that are already XML (no conversion takes place).
 980       </para>
 981      </listitem>
 982     </varlistentry>
 983
 984     <varlistentry>
 985      <term>pz:queryencoding</term>
 986      <listitem>
 987       <para>
 988        The encoding of the search terms that a target accepts. Most
 989        targets do not honor UTF-8 in which case this needs to be specified.
 990        Each term in a query will be converted if this setting is given.
 991       </para>
 992      </listitem>
 993     </varlistentry>
 994
 995     <varlistentry>
 996      <term>pz:negotiation_charset</term>
 997      <listitem>
 998       <para>
 999        Sets character set for Z39.50 negotiation. Most targets do not support
1000        this, and some will even close connection if set (crash on server
1001        side or similar). If set, you probably want to set it to
1002        <literal>UTF-8</literal>.
1003       </para>
1004      </listitem>
1005     </varlistentry>
1006
1007     <varlistentry>
1008      <term id="pzxslt" xreflabel="pz:xslt">pz:xslt</term>
1009      <listitem>
1010       <para>
1011        Is a comma separated list of of stylesheet names that specifies
1012        how to convert incoming records to the internal representation.
1013       </para>
1014       <para>
1015        For each name, the embedded stylesheets (XSL) that comes with the
1016        service definition are consulted first and takes precedence over
1017        external files; see <xref linkend="servicexslt"/>
1018        of service definition).
1019        If the name does not match an embedded stylesheet it is
1020        considered a filename.
1021       </para>
1022       <para>
1023        The suffix of each file specifies the kind of tranformation.
1024        Suffix "<literal>.xsl</literal>" makes an XSL transform. Suffix
1025        "<literal>.mmap</literal>" will use the MMAP transform (described below).
1026       </para>
1027       <para>
1028        The special value "<literal>auto</literal>" will use a file
1029        which is the <link linkend="requestsyntax">pz:requestsyntax's</link>
1030        value followed by
1031        <literal>'.xsl'</literal>.
1032       </para>
1033       <para>
1034        When mapping MARC records, XSLT can be bypassed for increased
1035        performance with the alternate "MARC map" format.  Provide the
1036        path of a file with extension ".mmap" containing on each line:
1037        <programlisting>
1038        &lt;field&gt; &lt;subfield&gt; &lt;metadata element&gt;</programlisting>
1039        For example:
1040        <programlisting>
1041         245 a title
1042         500 $ description
1043         773 * citation
1044        </programlisting>
1045        To map the field value specify a subfield of '$'.  To store a
1046        concatenation of all subfields, specify a subfield of '*'.
1047       </para>
1048      </listitem>
1049     </varlistentry>
1050     <varlistentry>
1051      <term>pz:authentication</term>
1052      <listitem>
1053       <para>
1054        Sets an authentication string for a given server. See the section on
1055        authorization and authentication for discussion.
1056       </para>
1057      </listitem>
1058     </varlistentry>
1059     <varlistentry>
1060      <term>pz:allow</term>
1061      <listitem>
1062       <para>
1063        Allows or denies access to the resources it is applied to. Possible
1064        values are '0' and '1'.
1065        The default is '1' (allow access to this resource).
1066        See the manual section on authorization and authentication for
1067        discussion about how to use this setting.
1068       </para>
1069      </listitem>
1070     </varlistentry>
1071     <varlistentry>
1072      <term>pz:maxrecs</term>
1073      <listitem>
1074       <para>
1075        Controls the maximum number of records to be retrieved from a
1076        server. The default is 100.
1077       </para>
1078      </listitem>
1079     </varlistentry>
1080     <varlistentry>
1081      <term>pz:id</term>
1082      <listitem>
1083       <para>
1084        This setting can't be 'set' -- it contains the ID (normally
1085        ZURL) for a given target, and is useful for filtering --
1086        specifically when you want to select one or more specific
1087        targets in the search command.
1088       </para>
1089      </listitem>
1090     </varlistentry>
1091     <varlistentry>
1092      <term>pz:zproxy</term>
1093      <listitem>
1094       <para>
1095        The 'pz:zproxy' setting has the value syntax
1096        'host.internet.adress:port', it is used to tunnel Z39.50
1097        requests through the named Z39.50 proxy.
1098       </para>
1099      </listitem>
1100     </varlistentry>
1101
1102     <varlistentry>
1103      <term>pz:apdulog</term>
1104      <listitem>
1105       <para>
1106        If the 'pz:apdulog' setting is defined and has other value than 0,
1107        then Z39.50 APDUs are written to the log.
1108       </para>
1109      </listitem>
1110     </varlistentry>
1111
1112     <varlistentry>
1113      <term>pz:sru</term>
1114      <listitem>
1115       <para>
1116        This setting enables
1117        <ulink url="&url.sru;">SRU</ulink>/<ulink url="&url.solr;">SOLR</ulink>
1118        support.
1119        It has four possible settings.
1120        'get', enables SRU access through GET requests. 'post' enables SRU/POST
1121        support, less commonly supported, but useful if very large requests are
1122        to be submitted. 'srw' enables the SRW (SRU over SOAP) variation of
1123        the protocol.
1124       </para>
1125       <para>
1126        A value of 'solr' anables SOLR client support. This is supported
1127        for Pazpar version 1.5.0 and later.
1128       </para>
1129      </listitem>
1130     </varlistentry>
1131
1132     <varlistentry>
1133      <term>pz:sru_version</term>
1134      <listitem>
1135       <para>
1136        This allows SRU version to be specified. If unset Pazpar2
1137        will the default of YAZ (currently 1.2). Should be set
1138        to 1.1 or 1.2. For SOLR, the current supported/tested version is 1.4
1139       </para>
1140      </listitem>
1141     </varlistentry>
1142
1143     <varlistentry>
1144      <term>pz:pqf_prefix</term>
1145      <listitem>
1146       <para>
1147        Allows you to specify an arbitrary PQF query language substring.
1148        The provided string is prefixed the user's query after it has been
1149        normalized to PQF internally in pazpar2.
1150        This allows you to attach complex 'filters' to queries for a given
1151        target, sometimes necessary to select sub-catalogs
1152        in union catalog systems, etc.
1153       </para>
1154      </listitem>
1155     </varlistentry>
1156
1157     <varlistentry>
1158      <term>pz:pqf_strftime</term>
1159      <listitem>
1160       <para>
1161        Allows you to extend a query with dates and operators.
1162        The provided string allows certain substitutions and serves as a
1163        format string.
1164        The special two character sequence '%%' gets converted to the
1165        original query. Other characters leading with the percent sign are
1166        conversions supported by strftime.
1167        All other characters are copied verbatim. For example, the string
1168        <literal>@and @attr 1=30 @attr 2=3 %Y %%</literal>
1169        would search for current year combined with the original PQF (%%).
1170       </para>
1171      </listitem>
1172     </varlistentry>
1173
1174     <varlistentry>
1175      <term>pz:sort</term>
1176      <listitem>
1177       <para>
1178        Specifies sort criteria to be applied to the result set.
1179        Only works for targets which support the sort service.
1180       </para>
1181      </listitem>
1182     </varlistentry>
1183
1184     <varlistentry>
1185      <term>pz:recordfilter</term>
1186      <listitem>
1187       <para>
1188        Specifies a filter which allows Pazpar2 to only include
1189        records that meet a certain criteria in a result.
1190        Unmatched records  will be ignored.
1191        The filter takes the form name, name~value, or name=value, which
1192        will include only records with metadata element (name) that has the
1193        substring (~value) given, or matches exactly (=value).
1194        If value is omitted all records with the named metadata element
1195        present will be included.
1196       </para>
1197      </listitem>
1198     </varlistentry>
1199
1200     <varlistentry>
1201      <term>pz:preferred</term>
1202      <listitem>
1203       <para>
1204        Specifies that a target is preferred, e.g. possible local, faster
1205        target. Using block=pref on show command will wait for all these
1206        targets to return records before releasing the block.
1207        If no target is preferred, the block=pref will identical to block=1,
1208        which release when one target has returned records.
1209       </para>
1210      </listitem>
1211     </varlistentry>
1212
1213     <varlistentry>
1214      <term>pz:block_timeout</term>
1215      <listitem>
1216       <para>
1217        (Not yet implemented).
1218        Specifies the time for which a block should be released anyway.
1219       </para>
1220      </listitem>
1221     </varlistentry>
1222
1223     <varlistentry>
1224      <term>pz:facetmap:<replaceable>name</replaceable></term>
1225      <listitem>
1226       <para>
1227        Specifies that for field <replaceable>name</replaceable>, the target
1228        supports (native) facets. The value is the name of the
1229        field on the target.
1230       </para>
1231       <note>
1232        <para>
1233         At this point only SOLR targets have been tested with this
1234         facility.
1235        </para>
1236       </note>
1237      </listitem>
1238     </varlistentry>
1239
1240     <varlistentry id="limitmap">
1241      <term>pz:limitmap:<replaceable>name</replaceable></term>
1242      <listitem>
1243       <para>
1244        Specifies attributes for limiting a search to a field - using
1245        the limit parameter for search. It can be used to filter locally
1246        or remotely (search in a target). In some cases the mapping of
1247        a field to a value is identical to an existing cclmap field; in
1248        other cases the field must be specified in a different way - for
1249        example to match a complete field (rather than parts of a subfield).
1250       </para>
1251       <para>
1252        The value of limitmap may have one of three forms: referral to
1253        an existing CCL field, a raw PQF string or a local limit. Leading string
1254        determines type; either <literal>ccl:</literal> for CCL field,
1255        <literal>rpn:</literal> for PQF/RPN, or <literal>local:</literal>
1256        for filtering in Pazpar2. The local filtering may be followed
1257        by a field a metadata field (default is to use the name of the
1258        limitmap itself).
1259       </para>
1260       <note>
1261        <para>
1262         The limitmap facility is supported for Pazpar2 version 1.6.0.
1263         Local filtering is supported in Pazpar2 1.6.6.
1264        </para>
1265       </note>
1266      </listitem>
1267     </varlistentry>
1268
1269     <varlistentry id="pzurl">
1270      <term>pz:url</term>
1271      <listitem>
1272       <para>
1273        Specifies URL for the target and overrides the target ID.
1274       </para>
1275       <note>
1276        <para>
1277         <literal>pz:url</literal> is only recognized for
1278         Pazpar2 1.6.4 and later.
1279        </para>
1280       </note>
1281      </listitem>
1282     </varlistentry>
1283
1284     <varlistentry id="pzsortmap">
1285      <term>pz:sortmap:<replaceable>field</replaceable></term>
1286      <listitem>
1287       <para>
1288        Specifies native sorting for a target where
1289        <replaceable>field</replaceable> is a sort criteria (see command
1290        show). The value has to components separated by colon: strategy and
1291        native-field. Strategy is one of <literal>z3950</literal>,
1292        <literal>type7</literal>, <literal>cql</literal>,
1293        <literal>sru11</literal>, or <literal>embed</literal>.
1294        The second component, native-field, is the field that is recognized
1295        by the target.
1296       </para>
1297       <note>
1298        <para>
1299         Only supported for Pazpar2 1.6.4 and later.
1300        </para>
1301       </note>
1302      </listitem>
1303     </varlistentry>
1304
1305    </variablelist>
1306
1307   </refsect2>
1308
1309  </refsect1>
1310  <refsect1>
1311   <title>SEE ALSO</title>
1312   <para>
1313    <citerefentry>
1314     <refentrytitle>pazpar2</refentrytitle>
1315     <manvolnum>8</manvolnum>
1316    </citerefentry>
1317    <citerefentry>
1318     <refentrytitle>yaz-icu</refentrytitle>
1319     <manvolnum>1</manvolnum>
1320    </citerefentry>
1321    <citerefentry>
1322     <refentrytitle>pazpar2_protocol</refentrytitle>
1323     <manvolnum>7</manvolnum>
1324    </citerefentry>
1325   </para>
1326  </refsect1>
1327 </refentry>
1328 <!-- Keep this comment at the end of the file
1329 Local variables:
1330 mode: nxml
1331 nxml-child-indent: 1
1332 End:
1333 -->