Adlib API home page > Documentation > The adlibweb.xml file

The adlibweb.xml file

The adlibweb.xml file is used to configure your wwwopac. In it, you specify paths to the data folder, and other relevant folders, you configure image retrieval, and you list the fields that must be included in the search result.

Click here for an example of an adlibweb.xml file.


Configure the data server

In the globalConfiguration group in adlibweb.xml, the data server must be configured. The most relevant options available to you are the following:

Configuration options Possible values Meaning
authentication true or false This optional setting determines whether authentication by means of a login procedure should be used before users can retrieve certain data and implicitly it also determines under which user name access to data is requested. You can set the option to true or false or leave the option out altogether (in which case it implicitly defaults to true).
True (without login): when set to true (or is absent), any user executing a wwwopac.ashx request directly (without the expected login) will implicitly do so with the IIS application pool identity of the wwwopac.ashx service on the server, as his or her user name.
True (with login): when the user accesses the Adlib database through an Internet Server web application via the intended explicit login dialog, different users have different user and/or group names as specified in either Active Directory or some specific Adlib authentication database, which will be used to find out if access to records is granted. A specific login procedure can be set up in an <authenticationConfiguration> section (see the paragraph below this table for more information about that). Then both the user name and group name(s) will be used to determine which access rights the current user has to certain data.
Excluding records: if in Adlib, records have been protected by specified rights, in which case each record lists the users or groups and their access rights to that record, then records will only be accessible if the remote user has sufficient access rights to it. So if no login procedure has been followed, all users will approach the database with the application pool identity as their user name. Then in IIS, this identity must have been set to a general Active Directory account name under which all anonymous users enter the network. To shield records from being retrieved by these users you'll have to register this general Active Directory account name in these records as a "user" to exclude.
False (without login): on the other hand, if you set <authentication> to false, remote users will again approach the Adlib database with the application pool identity you set for it - you would assign the application pool identity its own Active Directory user account here, other than the general account for anonymous users - but the Active Directory group this specific user account belongs to can then be used in Adlib's access rights mechanism like you would expect, for instance to exclude this group from accessing certain records.
databasePath <path> Use this variable to refer to a physical location, seen from the web server, which holds the .inf files of the Adlib databases. For best performance of the web server, the data should be stored on a local disk of the web server. (It is sensible to enter only one absolute path in adlibweb.xml, although it is possible as well to speficy a databasePath per databaseConfiguration section, in which case the latter path has precendence over the globally specified path.) Example: <databasePath>\\server- d\databases\website\adlibapi\data</databasePath>
facetLimit <integer> Use this optional variable to limit the amount of retrieved facets for all databases at once.
highlight True or False Use this variable (set to True) to enclose the searched key in <highlight> tags by default, in the result XML. It is possible as well to submit this parameter with the search command. The latter may be preferred if the result XML must be handled differently from request to request.
indent True or False Use this variable (set to True) to apply a better layout to json output. The added white space makes the data easier to read by users, at the price of a less compact and small document The indent option is only meant for json output and will only be applied when you've selected this output format.
limit <integer> This variable specifies how many records of a search result will actually be retrieved. The variable is not supported in adlibweb.xml for wwwopac.ashx though, but it is in URLs. By adding e.g. &limit=5 to a wwwopac query, only the first five records of the search result will be retrieved. By default, wwwopac.ashx retrieves maximally 10 records.
xmlType grouped, structured, unstructured, diagnostic, raw In response to a query, the wwwopac.ashx can produce XML in various formats. The format is relevant for the XSLT stylesheets you apply to an XML file: a different format usually requires different stylesheets. The XSLT stylesheets implemented in the Internet Server 5 web application require the xmltype to be set to grouped. The other types are seldomly used. unstructured lists all fields and field occurrences in an indiscriminate list without field group information or grouping of occurrences of a single field, whilst structured arranges field groups and internal and external links in a tree structure. The wwwopac.ashx uses the structured type only for pointer files, it cannot be used with other functio- nality. The grouped type is a newer and more advanced version of the structured type. Further, the raw type retrieves the entire record: any specified brieffields or detailfields are ignored. And finally diagnostic: this only returns a number of hits, not records. It can offer extra and more efficient functionality for web applications, such as showing the number of hits for various databases first, before users choose to access the resulting records of one of those databases.
You can specify the XML type either or both in the <database- Configuration>, the <groupConfiguration> or <globalConfiguration> section of adlibweb.xml. Or you can specify it in your wwwopac.ashx query. The most detailed level of configuration always has precedence over more global levels, so an XML type specification in the search statement has precedence over an XML type specification on the <databaseConfiguration> level, which in turn has precedence over the <groupConfiguration> level which has has precedence over the <globalConfiguration> level.

So the Adlib API can return different forms of XML, but most XML output has some characteristics in common:

  • The root element is named adlibXML.
  • All records are contained in a child element from the root with the name recordList.
  • Each record in the result set is contained in the record list in a record element.
  • The recordList element is followed by a diagnostics element, which contains meta information about the search, such as the elapsed time and the number of records that were found.
  • The fields in the records are contained within each record element and have the English field name by which they are declared in the database .inf file

The most common Adlib XML output types are unstructured and grouped:

  • unstructured = flat structure: all fields and their occurrences are immediate children of the record element. If a field has multiple occurrences, then all those occurrences are listed directly below each other.
    Of a multilingual field, only the value of the currently searched data language is returned, and it is returned directly in the field node, without language or invariancy attributes.
    Of an enumerative field, only the neutral value is returned, directly in the enumerative field node, unless you specify the presentation language with the language parameter followed by a standard language code without square brackets around it, in which case only the relevant translation is returned, directly in the enumerative field node.
  • grouped = hierarchical structure: fields may be a child of the record element, or when a field group name has been defined in the data dictionary, a child of a group element with the name of the group. In this case the group element is a child of the record element. If at least one of the fields in a field group has multiple occurrences, then the entire field group is repeated as many times. Empty occurrences of fields in a field group are retrieved as well.
    Of a multilingual field, all language values are returned as value subnodes of the field node; the language code and invariancy flag per language value are returned as attributes to the value nodes.
    Of an enumerative field, both the neutral value and all available translations of the enumerative value are returned, in value subnodes underneath the enumerative field node; the presentation languages are attributes to the value nodes, and are indicated by an Adlib language number, not by their language code. The presentation language parameter does not apply to the grouped XML output type.
    The grouped XML format is also variable in some ways, especially for linked fields, dependent on the brieffields and detailfields listings here in adlibweb.xml. This is because from wwwopac.ashx version 3.6.327.0 it is possible to nest field nodes of linked fields in said listings, to retrieve data of your choice from linked records. This way you can even obtain data from records linked in the second or third degree. See the relevant topic for more information. Also note that the grouped XML as produced by adlwin.exe (running your Windows Adlib applications) always contains the nested linked field structure (although it doesn't retrieve any extra fields from linked records and does have some added linked field node attributes as well), whilst the grouped XML from the default adlibweb.xml doesn't contain the nested linked field structure; this means that XSLT stylesheets may not be readily exchangeable between adlwin.exe and wwwopac.ashx.

The structured xmltype, as could be used with wwwopac.exe, has not been implemented for searches in wwwopac.ashx, although it has been for pointer files. If you do use it with a search statement, the result will be unstructured XML, regardless of what the diagnostics may indicate. An overview of differences between the wwwopac.exe structured xmltype and the wwwopac.ashx grouped xmltype is documented here.

xsltScriptingAllowed true or false

Set this optional variable (available from API version 3.7.13308) to true to allow the XSLT document() function and embedded scripting to be used in your XSLT stylesheet to transform the XML returned from wwwopac.ashx. (In MSXML 6.0 this feature is disabled by default.)
The XSLT document() function provides a way to retrieve other XML resources from within the XSLT stylesheet beyond the initial data provided by the input stream. Allow scripting only if you require script support in the stylesheet and if you are working in a fully trusted environment: if scripts are allowed in the main stylesheet, they will be allowed in all the included files too.

A complete example of a globalConfiguration is the following:

<globalConfiguration>
<databasePath>\\server-d\databases\website\adlibapi\data</databasePath>
</globalConfiguration>

Configure the user authentication

With the optional <authenticationConfiguration> you can specify sources to be used to validate submitted login details. If you use an Adlib Internet Server web application or your own (web) application, this validation can be used to allow or disallow certain functionality in the web application, like being able to reserve library materials or to register (SDI) search profiles. Click here for more information about this topic.

Configure the databases

In the databaseConfiguration sections in adlibweb.xml, the databases available to wwwopac.ashx must be configured. Minimally, a database alias and the actual database name must be specified. The most relevant options available to you are the following:

Configuration options

Possible values

Meaning

adaplEnabled True or False

Set this variable to True to specify that when you write or update a record with the API, the adapl set as Storage procedure for the relevant database in Adlib Designer must be executed just before actual storage, just like it is executed before storage when you save a record in an adlwin.exe application. This variable is available from wwwopac.ashx version 3.6.1265.0. By default, for backwards compatibility with existing Adlib Internet Server applications, the storage procedure is not executed.
This variable can also be set in the groupConfiguration section (the shared section for multiple database configurations) and in the globalConfiguration section (the shared section for all database configurations).
A further requirement is that all fields to which the storage adapl should be able to write, have actually been defined in the data dictionary (the .inf file of the relevant database), otherwise the API will report that it has no access rights for the field.
Although all adapl binaries can be read and most common ADAPL functions have been implemented, not all functions are present yet (March 2012). This means that it is possible that on execution of a storage adapl the API can throw an exception when it encounters a function which hasn't been implemented yet. The adapl will not have been executed properly in that case, which leaves you no option than to switch the adaplEnabled variable for the relevant database off again: please contact our helpdesk if you have this problem. The goal of course, is to implement all ADAPL functions in future releases.

addToQuery <partial query>

With the <addToQuery> setting (available from wwwopac.ashx 3.7.13332.1) you can specify a partial search statement that must always be added to queries in the current database. This way you can shield certain content on field level, to prevent certain records from being retrieved. Note that a setting with the same name and function, that predates the adlibweb.xml setting, can also be made in the globalsettings.xml file of an Adlib Internet Server web application, but the adlibweb.xml setting does not only have the advantage of having the option available at the API level so that all software calling the API can be restricted with this setting, it may also allow you to use a q= search for simple searching multiple fields at once instead of a normal search= query, which can boost the performance of searching.
So, per <databaseConfiguration> here in the adlibweb.xml you can add the <addToQuery> setting and in it specify a partial search statement: this partial search statement will be combined with the search executed by the user, via an implicit Boolean AND. Do not enter any Boolean operators at the start of the partial search statement yourself. (Note that wwwopac.ashx versions until 2013-12-19 did require you to start your partial search statement with an explicit Boolean operator (AND, AND NOT, OR).) The added partial query can be different for each database and it applies to both search= and q= queries.
Note that a partial query for the <addToQuery> setting in the globalsettings.xml file for Internet Server also uses an implicit Boolean AND operator to combine the queries and that in the globalsettings.xml file, the setting is an optional one.

brieffields <field list> Use the brieffields variable to specify the fields you wish to see in the list display of the search result, for example:
<brieffields>
<field>lead_word</field>
<field>title</field>
<field>author.name</field>
<field>corporate_author</field>
<field>year_of_publication</field>
<field>digital_reference</field>
<field>copy.number</field>
<field>shelf_mark</field>
</brieffields>

For optimal performance of wwwopac.ashx it is definitely recommended to provide only the brieffields which you intend to actually use. This is because each submitted field will take up some processing time, and when you retrieve multiple records for a brief display, this will certainly add up.

From wwwopac.ashx version 3.6.327.0 it is possible to nest field nodes of linked fields, to retrieve data of your choice from linked records. This way you can even obtain data from records linked in the second or third degree. Using nesting field nodes does change the XML structure of linked fields in the required grouped XML format which wwwopac.ashx will produce. See the relevant topic for more information.

The wwwopac.exe type="richText" attribute for <field> nodes (no relation to RTF fields, by the way) is supported by wwwopac.ashx from version 3.6.13043.2. This attribute makes sure that any line breaks (\n) in field contents are replaced by HTML <br/> tags, so that the paragraph structure in field contents remains intact when presented on the website.

An optional attribute to the <field> element is includeIf. You can use this attribute to specify a condition (in the shape of a search statement) under which (an occurrence of) the relevant field must be included in the search result. Conditionally including fields in the search result this way has the advantage that specific data will never end up in the raw XML of a search result and that it doesn't need to be filtered out afterwards. An example of a single conditionally included field would be the following: <field includeIf="credit.type=Director">credit.name</field>
Click here for more information about this topic.

database <FACS-name>

Use this variable to identify the actual name of the database. If a database has been subdivided into datasets, you may point to the dataset by stating behind the database name, separated by an escaped greater-than symbol. Example: <database>document&gt;fullcatalogue</database>

defaultQuery <filter query>

Use this (optional) variable to filter all search queries submitted to wwwopac, by providing a filter query. Before execution of a search, the search statement or value submitted behind &search= will be passed on to any filter query set here. A filter query can be any value or normal search statement with the addition of the '{0}' parameter (include the quotes), to which the submitted search statement is passed on. Thus, if a <defaultQuery> has been specified, the submitted and the filter query will always be combined. So, a filter query like <defaultQuery>title = '{0}' or description = '{0}'</defaultQuery> will take any value passed on via the submitted search query and executes the resulting search. For example, the submitted query wwwopac.ashx?database=collect &search=amsterdam would result in the search statement title = 'amsterdam' or description = 'amsterdam' being executed.
Another example would be the filter query <defaultQuery>'{0}' and pointer 3</defaultQuery>. This would combine any submitted, normal search statement with and pointer 3. So wwwopac.ashx?database=collect&search=title=mill would result in title=mill and pointer 3 being executed.
If no search statement has been submitted, while a <defaultQuery> is present, then the filter query becomes the entire query (in which case the filter query should not contain the '{0}' parameter). So, a submitted query like wwwopac.ashx?database=collect (with no search statement), passed on to a filter query like <defaultQuery> all</defaultQuery> simply leads to the search statement all being executed in the collect database. If a filter query does not contain the '{0}' parameter, it will also always take precedence over whatever search statement you submit to wwwopac manually.
It may be obvious from the above that any <defaultQuery> (should you specify one), should accommodate most search statements passed on to it. If you can't be sure that the format of submitted queries is always what you want it to be, then reconsider the use of this option. However, wrong combinations resulting in incorrectly formatted search statements will simple produce an empty search result list: no errors will be reported.

detailfields <field list> Use the detailfields variable to specify the fields you wish to see in the detailed display of the search result. To retrieve all fields, use the * wild card. For optimal performance of wwwopac.ashx it is definitely recommended to provide only the detailfields which you intend to actually use.
Example 1:
<detailfields>
<field>lead_word</field>
<field>title</field>
<field>author.name</field>
<field>corporate_author</field>
<field>illustrator.name</field>
</detailfields>
Example 2:
<detailfields>
<field>*</field> 
</detailfields>

From wwwopac.ashx version 3.6.327.0 it is possible to nest field nodes of linked fields, to retrieve data of your choice from linked records. This way you can even obtain data from records linked in the second or third degree. Using nesting field nodes does change the XML structure of linked fields in the required grouped XML format which wwwopac.ashx will produce. See the relevant topic for more information.

The wwwopac.exe type="richText" attribute for <field> nodes (no relation to RTF fields, by the way) is supported by wwwopac.ashx from version 3.6.13043.2. This attribute makes sure that any line breaks (\n) in field contents are replaced by HTML <br/> tags, so that the paragraph structure in field contents remains intact when presented on the website.

An optional attribute to the <field> element is includeIf. You can use this attribute to specify a condition (in the shape of a search statement) under which (an occurrence of) the relevant field must be included in the search result. Conditionally including fields in the search result this way has the advantage that specific data will never end up in the raw XML of a search result and that it doesn't need to be filtered out afterwards. An example of a single conditionally included field would be the following: <field includeIf="credit.type=Director">credit.name</field>
Click here for more information about this topic.

facetFields <field list> Use the optional facetFields variable to limit the number of facets returned in the search result when requested in the URL. Facets are values found in one or more specific fields in the records of the search result, which are listed below the search result. The limit attribute is mandatory. For example:
<facetFields>
<field limit="25">creator</field>
<field limit="10">production.date.end</field>
</facetFields>
searchfields <field list> Use the searchFields variable to allow for a simple search option which is configured here on the server side. On the client you only to need specify a query with the syntax q=<seach_key>. This query must not be preceded by search= and you cannot (Boolean) combine it with another search. This simple search will search for the search key in all fields listed in this section, with an implicit OR relation: a record will be included in the search result if the search key appears in at least one of the search fields. The following is an example of a searchFields section:
<searchFields>
<field>title</field>
<field>creator</field>
<field>object_category</field>
</searchFields>

Prior to wwwopac.ashx version 3.7.14202.1, q= searches were always implicitly truncated. Later versions offer an optional truncation="true|false" attribute for the searchFields node, allowing you to switch truncation on explicitly for all q= searches, whilst by default truncation is off (false). For example:

<searchFields truncation="true">
<field>title</field>
<field>creator</field>
<field>object_category</field>
</searchFields>

For optimal performance of wwwopac.ashx it is definitely recommended to provide only a limited number of search fields. This is because each field to search will take up some processing time, so searching many fields could lower performance.

It is also possible (from wwwopac.ashx version of October 2016) to specify multiple searchFields sections to allow for different q= searches. To distinquish between the different searchFields specifications you must add an id="<myid>" attribute in each of your searchFields elements (and replace <myid> by an appropriate name for the type of search). For example:

<searchFields id="descriptions">
<field>title</field>
<field>description</field>
</searchFields>
<searchFields id="objectnames">
<field>object_name</field>
<field>object_category</field>
</searchFields>
On the client you need to include the id to specify which searchFields specification you'd like to search, e.g.: q=paint&id=descriptions
styleSheet <XSLT file name> Use this variable to specify your own XSLT stylesheet which the API must always use to transform the returned XML result from searches in the current database. This way you can use the API to automatically transform Adlib XML to another type of XML if that other type is more convenient for your API application, or you can transform the Adlib XML to HTML or any other text format if you like. Provide the full file name for this option, including the file extension, for example: <styleSheet>Marc21.xslt</styleSheet>
The output type of your transformation is specified with the <xsl:output method="html" indent="yes"/> statement, in which the method attribute can have the following values: “html”, “xml” or “text”. In some older versions of wwwopac.ashx though, it didn't set the mime type of the actual output according to these settings, so the output was always “text/xml” causing the browser to always interpret the result as XML. In the current wwwopac.ashx version, the transformation method used in the stylesheet is recognized by wwwopac.asxh and the mime type of the output is set accordingly: “Text/Xml” for “xml”, “Text/Html” for “html”, “Text/Plain” for “text”. This allows the browser to correctly render the transformed result.
Note that these stylesheets are loaded at application startup time to prevent unnecessary loading and compiling of the stylesheets. This means that you will have to restart the application (e.g. by recycling its application pool) to use a modified stylesheet.
This variable is available from wwwopac.ashx version 3.6.1173.0.
You need wwwopac.ashx version 3.7.15343.1 or higher if you'd like to use a custom XSLT stylesheet only to add one or more (compound) fields to the resulting XML while maintaining the AdlibXML format (this is required) and you wish to output it as JSON (using the output=json API command). Prior to this wwwopac.ashx version, output to JSON disregarded any custom stylesheet you had set. You can use this functionality if you want to output to JSON and you need some compounded field data, like an extra field containing the ISBD presentation of a publication, to be part of that output before it is processed any further.
writeAllowed True or False Use this variable to indicate whether writing and deleting of records are in principle allowed in this database. Further user authentication can be applied in other ways, to determine which users have which access rights. Example: <writeAllowed>True</writeAllowed>
If this variable is not present in the adlibweb.xml file at all, then writing or deleting records is not possible.

In each databaseConfiguration section, you specify one database. A database alias is assigned as a database attribute to the database- Configuration node. In only one of the databaseConfiguration nodes you may choose to include the default="true" attribute as well. Having a default database configuration means that you have the option to omit the database parameter from wwwopac.ashx queries: this will automatically search the default database. Below you can see an example of two database configurations in the same adlibweb.xml file:

<databaseConfiguration database="MyMuseumDB" default="true">
<database>collect&gt;intern</database>
<writeAllowed>True</writeAllowed>
<brieffields>
<field>object_number</field>
<field>title</field>
<field>creator</field>
<field>label.text</field>
<field>administration_name</field>
<field>reproduction.reference</field>
</brieffields>
<detailfields>
<field>*</field>
</detailfields>
</databaseConfiguration> 
<databaseConfiguration database="MyLibraryDB"> <database>document</database> <writeAllowed>False</writeAllowed> <brieffields> <field>*</field> </brieffields> <detailfields> <field>*</field> </detailfields> </databaseConfiguration>

If you want to create multiple <databaseConfiguration> sections that must have identical <brieffields> and <detailfields> listings (as would be the case for the library books, audio-visuals, articles and serials datasets, for instance), there's no need to repeat these listings per <databaseConfiguration>. Instead, you can define one (or more) <groupConfiguration> sections in which you list all detail and brief fields. By adding the identifier of the proper <groupConfiguration> as a groups attribute to each <databaseConfiguration>, you include the field lists implicitly. Here's how it would look:

<groupConfiguration group="defaultLibrary">
<brieffields>
<field>lead_word</field>
<field>title</field>
<field>author.name</field>
<field>copy.number</field>
<field>shelf_mark</field>
<field>digital_reference</field>
...
</brieffields>
<detailfields>
<field>lead_word</field>
<field>title</field>
<field>author.name</field>
<field>corporate_author</field>
<field>illustrator.name</field>
<field>edition</field>
...
</detailfields>
</groupConfiguration> 
<databaseConfiguration database="fullCatalogue" groups="defaultLibrary"> <database>document&gt;fullcatalogue</database> </databaseConfiguration> <databaseConfiguration database="Books" groups="defaultLibrary"> <database>document&gt;book</database> </databaseConfiguration> <databaseConfiguration database="audioVisuals" groups="defaultLibrary"> <database>document&gt;avm</database> </databaseConfiguration> ...

Configure the images server

In the imageServerConfiguration group in adlibweb.xml, the image handling functionality of wwwopac.ashx must be configured. The following options are available to you:

Configuration options

Possible values

Meaning

cachePath <path> specifies the network path (UNC) to the folder in which all images resized by wwwopac.ashx will be stored*; a local file system path is possible as well, but only if this cache folder is located on the same server as wwwopac.ashx, or has been mapped as drive on this server.
* The wwwopac.ashx does not resize the images to be retrieved for every request, but reduces or enlarges the image only when first requested, and then saves the result in a cache folder so that for a following identical request the next time a ready-made resized image can be retrieved. (Images retrieved using a URL as their id won't be cached.)
database <database name> specifies the Adlib SQL Server database or Adlib Oracle database from which images must be retrieved (this applies only if images aren’t stored in the file system).
defaultImage <image file name> specifies the image file which will be retrieved from path, if the link to a requested image in a record is broken. This avoids an error message for the broken link. The default image could represent a missing image symbol, for example.
folderMappingList

<folder mappings> If you wish to use a single image server within an enterprise environment where the different branches have their own application and images folder and their own reproductions dataset within a larger, common reproductions database, then specify a <folderMappingList> here, containing a <folderMapping> for every reproductions dataset the enterprise has. Each <folderMapping> must contain a <lowerLimit> and <upperLimit> to indicate the record number range of the particular reproductions dataset (although this range doesn't need to coincide with a specified dataset per se), and a <folder> node specifying the relative path to a branch-specific folder containing the images, relative to the path set in the <path> variable of this image server configuration. For example:
<folderMappingList>
<folderMapping>
 <lowerLimit>1</lowerLimit>
  <upperLimit>10000000</upperLimit>
  <folder>OurBranchImages-01\</folder>
 </folderMapping>
 <folderMapping>
  <lowerLimit>10000001</lowerLimit>
  <upperLimit>20000000</upperLimit>
  <folder>OurBranchImages-02\</folder>
 </folderMapping>
 <folderMapping>
  <lowerLimit>20000001</lowerLimit>
  <upperLimit>30000000</upperLimit>
  <folder>OurBranchImages-03\</folder>
 </folderMapping>
</folderMappingList>
To identify one of the folder mappings in a wwwopac.ashx getcontent call, use its folderId parameter and provide the record number of the relevant reproduction record as the id. It will be matched with the proper record number range automatically.
This functionality is available from October 2016.
ignoreScaleVideo

true or false When set to true this will make sure that the GetContent command ignores any image file specific arguments (like height, width, scalemode etc.) if the currently retrieved media file is not of an image type. Especially for the fixed retrieval path options in Designer it is handy to be able to specify image scaling arguments even though sometimes other media files will be linked in the same field.
If a requested media file cannot be found at all, the API first attempts to load an image with the same file name/id but with file extension .jpg. It that failes, the system tries to load the default image set in the <defaultImage> option. If that fails too, an exception is thrown.
imageOverlayBlend

<1-100> See the “Watermark all displayed images automatically” chapter in the WWWOPAC reference guide, for all information about applying overlays (watermarks).
imageOverlayFile <file name> See the “Watermark all displayed images automatically” chapter in the WWWOPAC reference guide, for all information about applying overlays (watermarks).
imageOverlayMinPixelSize <number of pixels> See the “Watermark all displayed images automatically” chapter in the WWWOPAC reference guide, for all information about applying overlays (watermarks).
imageOverlayPercentage <1-100> See the “Watermark all displayed images automatically” chapter in the WWWOPAC reference guide, for all information about applying overlays (watermarks).
imageOverlayPosition <0-4> See the “Watermark all displayed images automatically” chapter in the WWWOPAC reference guide, for all information about applying overlays (watermarks).
ImagePlugin See the Plugins section on the Documentation page for the available documentation on how to set up an image plugin for a DAMS server. (Note that for current wwwopac.ashx versions the <ImagePlugin> element and it sub-elements start with an upper case letter I, while prior to version 3.6.13151 the <imagePlugin> element began with a lower case letter i.)
maxHeight
maxWidth
<integer> Use these settings to limit the delivery size of high resolution originals, by specifying the maximum height and width in pixels. Limiting the delivery size of images can be important because of copyright issues and web server performance considerations.
If an image is requested without width and height (i.e. the original) then the image is returned within the rectangle that has been specified within maxHeight and maxWidth. If an image is requested with a size specification that is larger than specified with the maxHeight and maxWidth settings, the image will be resized until it fits the maximum rectangle whilst maintaining the original aspect ratio.
password <password> specifies the password with which, in combination with username, the images in an SQL or Oracle database can be accessed via wwwopac.ashx. A password is optional.
It concerns the same username and password which have been set in SQL Server or Oracle, for making a connection to the database.
path <path> specifies the network path (UNC) to the main images folder** (this applies only if your images have been stored in the file system, not in an Adlib SQL/Oracle database); a local file system path is possible as well, but only if this folder is located on the same server as wwwopac.ashx, or has been mapped as drive on this server. You cannot leave this setting empty: above instruction is valid as well if your reproduction records already contain a full or partial path to an image. Minimally, a UNC path should be of the form \\server\share.
server <server name> specifies the server on which your Adlib SQL Server database or Adlib Oracle database can be found.
servertype MsSql specifies the storage system (SQL, Oracle or the file system), from which images must be retrieved.
Oracle
FileSystem
username <user name> specifies the name with which, in combination with password, the images in an SQL or Oracle database can be accessed via wwwopac.ashx. A username is optional.
It concerns the same username and password which have been set in SQL Server or Oracle, for making a connection to the database.
writeContentAllowed True or False Use this variable to indicate whether the writing of image files (using the writecontent command) is allowed by this image server. Example: <writeContentAllowed>False</writeContentAllowed>
The variable can be set in individual imageServerConfiguration sections as well as in the globalConfiguration section. If it has only been set in the globalConfiguration section, it applies to all defined image servers, whilst if it has been set in both an imageServerConfiguration and the globalConfiguration, then the imageServerConfiguration setting takes precedence over the one in the globalConfiguration.
zoomifyPath <path> specifies the path in which Zoomify files will be stored if you use the zoomify=true parameter with the writecontent command.

** Grouping your images in subfolders

Normally, you will store all your images in a single folder. There is usually no need to structure your images folder into subfolders because with Adlib you search images by means of their metadata, not their physical location. A single images folder also allows you to write images to it easily, because the user doesn't need to know anything about any subdivisions of the folder. In some situations though, you may want the images to be grouped in subfolders anyway, because someone needs to be able to find and edit them outside of Adlib. In that case, and if you are not going to be writing images to these subfolders using the Adlib API, a hierarchical images folder is an option: the folder on your network which contains images linked to Adlib records, can indeed have subfolders also containing images, so you'll be able to group images of certain types in their own subfolders with Windows Explorer or with image processing software. For wwwopac.ashx to be able to retrieve images from any of the images folders, the following conditions must be met:

  • There must be one main images folder. This folder may have multiple subfolders on multiple levels, all containing images.
  • In adlibweb.xml, the <path> node in the <imageServerConfiguration> must contain the physical path to the main images folder. For example: <path>d:\test2.adlibsoft.com\Adlib-API\backend\sampleImages</path>
  • The Retrieval path property*** of the image field in de data dictionary must contain a call to wwwopac.ashx, like for instance: http://www.ourmuseum.com/Adlib/wwwopac.ashx?command=getcontent&server=adlibimages&value=%data%
  • The image field in a record may contain a partial path to an image file, like transport/cars/cabrio.jpg.

When the API retrieves a record, the full path to the linked image will be put together by adding the partial path plus file name from the image field to the physical path set in adlibweb.xml. With the full path, the image can be retrieved by wwwopac.ashx.

The subfolder structure is also maintained in the image cache(s).

*** The Retrieval path option can be found on the Image properties tab of the image field in the images database (e.g. PHOTO), in the Application Browser in Adlib Designer.

Multiple image server configurations

You may include multiple imageServerConfiguration sections in your adlibweb.xml file, for instance one for internal users who are allowed to retrieve images without watermark, and one for external users for whom all images must be watermarked.

User name and password for the FileSystem server type?

By the way, the options for user name and password, and for the database and server, do not apply if you set the servertype to FileSystem (in case your images are stored in the file system), and these are ignored because of that if they appear in the configuration anyway. So then you don’t have to comment those options out.

Example of two image server configurations