CALM API Further Information

1. Introduction

CALM API is the interface or broker between CALM database(s), and a custom-built user (public) web interface.

The API employs Web Services/SOAP technology thus allowing it to be used by other SOAP compliant code. CALM API is written in a combination of Microsoft C# and Visual C++ and requires a Microsoft .NET framework in which to operate. It is best suited to a Windows 2000 Server environment or later operating system. Any other services which communicate with CALM API however need not necessarily be on a .NET platform.

The software is known to work with:

The API must be installed in 32 bit compatibility mode under 64 bit platforms.

NOTE: This document refers to CALM API for CALM V7.2 and later. The files supplied with this version are NOT compatible with the files supplied for earlier version of CALM API although the functionality of the web services remains the same.

1.1 Understanding

You should have a knowledge of:

To use CALM API from a development perspective, you should have a knowledge of how to write code that can call web services and manage XML.

1.2 Pre-requisites

Before you install the CALM API, you will require:

To verify whether you have IIS server installed: - go to the Windows Control panel, - go to the Administrative Tools - there should be an item called "Internet Information Server". If this icon does not exist, then IIS will need to be installed on the computer - please seek advice from your computer administration staff. Note that there are no additional Microsoft licences required for IIS.

1.3 Revision History

a) Initial version of CALM API was released with CALM V5 software.

b) Second release to support V6 CALM - fixed the CALM period date search via CALM API.

c) updates to documentation.

d) Release for CALM V7.1 - functionally identical to the release for V6 CALM.

e) Release for Calm v7.2 and Calm v7.3 - functionally identical to the release for v7.1. CALM API is now installed automatically using an installation program. Configuration tool introduced to configure the connection to the server, rather than edit the values directly in DatabaseList.xml.

f) Release for Calm v8. Image processing has been enhanced.  

2. Technical Description

The API is exposed through ContentService.asmx web service.

Note: More complex versions of the CALM API web services are used as a 'broker' in the Discovery product. Although the Discovery web services are also included with CALM API and are publically exposed as web services, customers are warned not use them because their behaviour is undocumented and they may be changed without warning in the future.

There are 5 web service methods which are defined as follows:

a) public string Search(string dbname, string ElementSet, string Expr)

b) public string Overview(string dbname, string ElementSet, string Elements, uint xfrom, uint n)

c) public string SummaryHeader(string dbname, uint HitLstPos)

d) public void Abandon()

e) public CachedImage GetCachedImage( string dbname, string id, uint crc, bool newImage )

a) Search

The "Search" Method Parameters required are:

the method returns the string value embedded in XML of the number of hits. When the Search method is called, a session is also created which is necessary in order to use the subsequent methods:

Example of return XML string: 

<?xml version="1.0" encoding="utf-8" ?>
<STRING xmlns="http://ds.co.uk/cs/webservices/">6</STRING>

Full SOAP post and return and non SOAP post for use in ordinary form based http are detailed in the search example page.

b) Overview

The "Overview" method. This method is used to retrieve a list of records from the result set created when the search method was created. User interfaces typically display (say) 10 records, displaying perhaps just the title and date. However, you can decide how many records to retrieve and which fields to retrieve and how many fields. Parameters required are:

Note, the first record in the result set is identified as record 0. Example of return XML string for 6 records. In this case, the parameters to the method would be: 

<?xml version="1.0" encoding="utf-8" ?>
<STRING xmlns="http://ds.co.uk/cs/webservices/">
	
	<OVERVIEW>
		<ROW Docno="0">
			<DATE>1250 - 1450</DATE>
		</ROW>
		<ROW Docno="1">
			<DATE>8th century</DATE>
		</ROW>
		<ROW Docno="2">
			<DATE>15th century</DATE>
		</ROW>
		<ROW Docno="3">
			<DATE>1200 - 1400</DATE>
		</ROW>
		<ROW Docno="4">
			<DATE>1200 - 1400</DATE>
		</ROW>
		<ROW Docno="5">
			<DATE>1200 - 1400</DATE>
		</ROW>
		<ROW Docno="6"></ROW>
		<ROW Docno="7"></ROW>
		<ROW Docno="8"></ROW>
		<ROW Docno="9"></ROW>
	</OVERVIEW>
</STRING>

Example SOAP post and return and non SOAP post for use in ordinary form based http are detailed in the overview example page.

c) SummaryHeader

This method returns all the fields for a single record in the result set created from the previous search method. Parameters required are:

Note, the first record in the result set is identified as record 0. Example of return XML string for record position 3 - i.e. fourth record: 

<?xml version="1.0" encoding="utf-8" ?>
<STRING xmlns="http://ds.co.uk/cs/webservices/">
	<SUMMARYLIST>
		<SUMMARY>
			<IDENTITY></IDENTITY>
			<LEVEL>Item</LEVEL>
			<REPOSITORY>Sample County Council: Archaeology </REPOSITORY>
			<REFNO>R & 
S/4/60</REFNO>
			<CATALOGUE_REFERENCE></CATALOGUE_REFERENCE>
			<ENTRYNO></ENTRYNO>
			<EXTENT></EXTENT>
			<SIMPLENAME></SIMPLENAME>
			<CLASS></CLASS>
			<DATE>1200 
- 1400</DATE>
			<PERIOD>Medieval</PERIOD>
			<CONTENT></CONTENT>
			<DESCRIPTION></DESCRIPTION>
			<NOITEMS></NOITEMS>
			<USER1></USER1>
			<RCN>R3027</RCN>
			<PHOTOGRAPH>egBOR-3.jpg" BORDER="0" /></PHOTOGRAPH>
			<NOTES>St Andrew's, 
Samplefield was declared redundant by the church over ten years ago, and an 
alternative use could not be found for it. It was eventually sold for conversion 
to a house. Building work never began and the church still lies unused.
Redundancy is potentially a major issue for rural churches.</NOTES>
			<SUBJECT>CHURCHES</SUBJECT>
			<PLACEKEY>Samplefield</PLACEKEY>
			<FORMAT>Transparency</FORMAT>
	<ACCESS></ACCESS>
	<CLOSEDUNTIL></CLOSEDUNTIL>
	<COPYRIGHT></COPYRIGHT>
	<PHYSDESC></PHYSDESC>
	<PHYSICALDESCRIPTION></PHYSICALDESCRIPTION>
	<MATERIALS></MATERIALS>
	<COLOUR></COLOUR>
	<DIMENSIONS></DIMENSIONS>
	<COMPLETENESS></COMPLETENESS>
	<CONDITION></CONDITION>
	<CONSERVATIONREQUIRED></CONSERVATIONREQUIRED>
	<CONSERVATIONSTATUS></CONSERVATIONSTATUS>
	<CONSERVATIONPRIORITY></CONSERVATIONPRIORITY>
	<VALUATION></VALUATION>
	<CONTEXT></CONTEXT>
	<PROVENANCE></PROVENANCE>
	<ACQTERMS></ACQTERMS>
	<ADMINHISTORY></ADMINHISTORY>
	<ALLIED_MATERIALS></ALLIED_MATERIALS>
	<RELATEDMATERIAL></RELATEDMATERIAL>
	</SUMMARY></SUMMARYLIST>
</STRING>

d) Abandon

The "Abandon" - takes no parameters and explicitly closes a session.

e) GetCachedImage

This method fetches an image from the Calm broker. This method is intended for users who want to build their own image cache. 

public CachedImage GetCachedImage( string dbname, string id, uint crc, bool newImage );

Parameters are:

This method returns a CachedImage object. The contents of which can be summarised by: 

	public class CachedImage
	{
		public byte [] Data;
		public uint Crc;
		public string Error;
		public string MimeType;
	}

If Data is null then either the CRC matches or an error has been returned.

3. Files used in configuration

All files are contained in two directories - the chosen root directory and a bin directory. Calm connection information is held in the DatabaseList.xml file in the root folder. The configuration utility can be used edit the Calm connection parameters contained within. Most users will not need to edit the configuration file directly.

4. Getting started

4.1 It is recommended CALM API is set-up on a Windows 2000 server platform and that all testing is conducted from the local machine i.e. "localhost". This allows you to undertake the Web Services testing.

4.2 The installation program will install the files and set up the IIS configuration for you. During installation, you will be prompted for the IIS virtual folder name under which CALM API will be installed. Shortcuts will be set up in the start menu.

4.3 Use the configuration utility to set the Calm connection options.

CALM API Configuration Utility

4.3 If you are using version 1 of the Discovery application then edit Web.config to set the address of the Discovery server. If you are not using the Discovery application then this step can be skipped. 

<add key="DiscoveryServiceUri" value="http://localhost/Discovery/DiscoveryService.asmx"/>

Review the following configuration entries to ensure they are correct:

<add key="ContentServiceUri"	value="http://localhost/CalmAPI/DScoveryBroker.asmx"/>
<add key="DiscoveryNotifyAppClose" value="true"/>

4.4 If you are using version 2 of the Discovery application then edit Web.config to set the address of the Discovery server. If you are not using the Discovery application then this step can be skipped. 

<add key="DiscoveryServiceUri2" value="http://localhost/Discovery2/DiscoveryService.asmx"/>

Review the following configuration entries to ensure they are correct:

<add key="ContentServiceUri2"	value="http://localhost/CalmAPI/DScoveryBroker2.asmx"/>
<add key="DiscoveryNotifyAppClose2" value="true"/>

4.5. Check that all settings are correct by using a browser to resolve the 'default.aspx' page. This page should return the following page:

Example Browser Page

Click on the 'CALM API' hyperlink - you should get a page listing the methods referred to above. If you are in "localhost", you can test the operation of the web services as follows:

Select 'Search' - you will be presented with the input boxes for the three method parameters. Enter 'Catalog' for dbname, 'DC' for ElementSet and a suitable search expression for 'Expr' (you can use '*' to retrieve all records) that you know will retrieve hits in the format detailed above.

If all is correctly connected you should receive an XML response containing the number of hits found displayed in a separate window as detailed above in 2a. If invalid XML is returned, check the configuration again and that the CALM database is correctly loaded.

After successfully retrieving the number of hits, go back to the list of four methods and select 'Overview'. You will be presented with five input boxes. Use the same entries for 'dbname' and 'ElementSet' as for your Search, for 'Elements' type in 'Title,Date' (i.e. a comma separated list), for 'xfrom' choose the input '0' and for 'n' choose '10'. Please note, no overviews will be returned if there were no successful hits at the Search stage. The overview will yield an XML output - similar to 2b above.

Assuming a successful overview result, go back again to the menu of four methods and select SummaryHeader. Enter the dbname - as chosen above, and make a choice for 'HitLstPos' between 0 and 9 - i.e. relating to one of the 10 records selected at the overview stage. A successful result will be an XML response similar to 2c above.

5. Writing code to use the web service

The approach that you take will depend on the development environment and languages that you are using. As such, it is difficult to offer anything other than general advice.

5.1. Maintaining session state

The web service interface is a stateful web service which requires clients to preserve the HTTP session state between function calls.

The Search method causes information to be stored in session on the server so that subsequent calls to Overview or SummaryHeader have access to the result set. If the .NET session is not preserved then calls to Overview or SummaryHeader will fail with the error message "No database session for xxxxx."

CALM API uses standard ASP.NET techniques on the server to maintain session state. By default, CALM API is configured to use cookies to preserve the session state. In practice, this means that users of the web service must capture cookies returned by the web server and forward them on for subsequent requests. The techniques for doing this are standard and there is plenty of information available on the Internet.

If you are using Visual Studio.NET to automatically generate Web Service proxy (using "Add Web Reference"), then you must set the CookieContainer property of the proxy in order for the proxy to maintain session state. The default behaviour of generated web service proxy classes are to be stateless. See the example for further information.

6. Image management

CALM API provides three methods of retrieving images stored within Calm databases.

6.1 GetImage.aspx

Using this option, the image processing is handled by an aspx page within the CalmAPI web application. Although this method involves you writing the least amount of code, we do not recommend that you expose the CalmAPI web application to the public. Therefore you will have to redirect the request in your public web application to the CALM API. This will result in at least two HTTP network hops before the image is served to the public.

Images can be retrieved from a Calm server and optionally resized and watermarked "on the fly". The cached images are stored in a location defined in the Web.config file of the CALM API web application.

To enable the built-in caching functionality, you will need to add the following setting to Web.config for the CALM API: 

<add key="ImageCacheDir" value="c:\ImageCache"/>

You will also need to edit the imagecache.config file in the bin folder to modify the cache behaviour. The default file is set up to stamp everything with a DS copyright and watermark as an example so you will need to modify this to suit your needs.


GetImage.aspx is the entry point for applications extracting images from Calm. You must pass the parameters via the URL. The URL parameters to GetImage.aspx are:

db Calm database
fname Calm ID for the image. This is the ID stored in the image field in the record.
page Page number to retrieve within the image. This is only applicable for multi-page image formats such as tiff.
type Type of image. This parameter relates to one of the "id" attributes in the ImageCache.config configuration file.

6.2 ImageCache image libary

This is only an option if you are using the Microsoft .NET environment for your development.

Axiell have implemented an image cache with dynamic watermarking as a .NET code library. This is the same cache engine as used in the CALM API web application. We have also supplied some sample code to help get you started.

6.3 Implement your own cache.

This offers the most flexibility, but you will have to implement your own caching and watermarking system.

You will need to use the CalmAPI GetCachedImage function to retrieve the full resolution from Calm. You are responsible for any caching, downsizing and watermarking.

7. Troubleshooting

If problems are experienced installing CALM API, Axiell are happy to offer advice via our helpdesk - please email to helpdesk@axiell.co.uk

Note - one of the most frequently asked questions is that a change is made that does not take effect. We advise that if you do make configuration changes then to restart the IIS web server. This has the effect of unloading the CALM DLLs and resetting the .NET web environment.

 

Return to home