Communication with Prizm Viewer

Prizm Viewer uses standard HTTP GET and POST requests through the browser that is hosting it. By channeling all communication through the browser, the session and security context already established between the browser and the web application server is preserved.

When Prizm Viewer receives an image from the browser, it requests the annotation data for that image from the annotation server, as long as the preference/property for annotating internet-based images is enabled.

For Prizm Viewer to communicate with an annotation server, it requires two pieces of information to know how to route the request:

The web server to contact
The path (location) of the annotation server application

Creating a Request

Prizm Viewer will perform the following steps when creating a request:

Identifies which Web Server needs to be contacted for annotation data. Prizm Viewer will look at the image's URL (e.g., http://www.accusoft.com/images/image.tif) and identifies the web server portion (web server name) of that URL (e.g., http;//www.accusoft.com). Note that if the URL contains "username:password@" as part of the server, that will be ignored for mapping purposes.
Prizm Viewer will then look at the annotation server mappings, to determine the web server and annotation server application path to send the request to. These mappings are established using the Prizm Viewer Preferences window, parameters in the object/embed tag, parameters in a list file, or by setting the AnnotationServers property in script. For more information, refer to the Preferences section in the Prizm Viewer User Help, or the AnnotationServers property information in the Prizm Viewer Admin Help. The mapping consists of the a web server name, and the location of the annotation server application to send annotation requests to.

If the path contains a server name, the server name in the mapping will not be pre-pended to the path.

For example, if you have an image ("http://www.accusoft.com/images/image.tif"), it would determine that the image's server name is "http://www.accusoft.com". It will then look at the mappings provided to find a matching entry. Let's say you had the following mappings:

Server Name	Annotation Server Path
http://www.accusoft.com	/PrizmAnnotServer/PrizmAnnotServer.aspx
http://www.yourserver1.com	http://www.yourserver2.com/AnnotServer/PrizmAnnotServer.aspx

Based on the image's server name, you can see that the corresponding annotation server path can be found at /PrizmAnnotServer/PrizmAnnotServer.aspx. Since no server was specified as part of the path, it will prepend the server name to the path to send the request to http://www.accusoft.com/PrizmAnnotServer/PrizmAnnotServer.aspx.

If you used the same approach for an image located at http://www.yourserver1.com/parts/images/block.tif, it would follow that the server name would be http://www.yourserver1.com/parts and it would find a mapping that contained a path of http://www.yourserver2.com/AnnotServer/PrizmAnnServer.aspx. In this case, however, there is a server name that is part of the annotation server path value, so it will not prepend the server name to the server path.

Your annotation server should disable caching for the content that it returns, to prevent proxies and browsers from using a cached version of the annotation data instead of the current data. The samples included with Prizm Annotation Server disable caching.

Retrieving Annotations

When Prizm Viewer makes a request for annotations, there are two parts of the conversation:

The request from Prizm Viewer
The response from Prizm Annotation Server

Prizm Viewer Annotation Request (GET)

When Prizm Viewer attempts to retrieve or save annotation data, it will make a request to the annotation server application. The annotation server is responsible for sending a response to each request.

Retrieving Annotation Data

To retrieve annotation data, Prizm Viewer sends an HTTP GET request to the annotation server application.

The format of the request is as follows:

(server path)?f=(image URL)p=(page)v=2.0
(server path) is constructed by Prizm Viewer using the mappings, as discussed in the previous section "Communication with Prizm Viewer"
(image url) is the URL of the image that the annotations apply to
(page) is the page number of the image within the image file. This value is 0-based, and can only be a value other than zero if you are dealing with multi-page image formats, such as TIFF or PDF.

Saving Annotations

To save annotation data, Prizm Viewer sends an HTTP "POST" request to the annotation server application. The format of the request is the same as a request to retrieve annotations, except that it will also send the annotation data stream as the post data.

Prizm Annotation Server Response (POST)

When the annotation server responds, the content of the response will indicate whether the request was successful, or if an error occurred.

In all cases, Prizm Annotation Server should set the HTTP response code to 200. If the status is set to any value other than 200, Prizm Viewer may not receive any useful information from the browser.

Success Response

Retrieving Annotations

The content-type should be set to "application/xml". The data returned shall be the XML conforming to the Prizm Viewer Annotation Schema.

Saving Annotations

The content-type should be set to "text/HTML", with "ErrorNumber: " followed by an error value (numeric string) set in the HTML document.

Error Response

When Prizm Annotation Server encounters an error processing an annotation request, it will return HTML content with some specific formatting requirements.

The <body> of the document needs to contain three pieces of information: an identifiable string, an error code and description. The error code should be one of the pre-defined values found in the table of errors below. The error description can be any string content that conveys information about the problem that caused the annotation server to fail performing the request.

The identifiable string must be "<head><title>Annotation Server Response</title></head>" (without the quotes). The case of each character is not important, but the spacing and wording must match exactly.

The error code content will consist of the string "ErrorNumber:" (without the quotes) followed by a string of numeric characters representing one of the numbers in the error table. The "ErrorNumber:" value must always be present.

The error description will consist of a string "Description:" (without the quotes) followed by a descriptive string that can provide additional information about the error encountered. This value does not have to be present.

The ErrorNumber: and Description: fields should be separated by at least one white space (blank, newline, tab, etc.) character.

Example HTML returned by Prizm Annotation Server (indicating an error occurred)	Copy Code
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1- transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" > <head><title>Annotation Server Response</title></head> <body> <pre>ErrorNumber: 501 Description: PrizmAnnotServer.AnnotException: Bad or missing parameter for the URL sent to Prizm Annotation Server at PrizmAnnotServer.RequestHandler.ProcessRequest()</pre> </body> </html>

Example HTML returned by Prizm Annotation Server (indicating an error occurred)

Copy Code

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-
transitional.dtd">
<html  xmlns="http://www.w3.org/1999/xhtml" >
    <head><title>Annotation Server Response</title></head>
    <body>
    <pre>ErrorNumber: 501  Description:  PrizmAnnotServer.AnnotException: Bad or missing parameter for the URL
sent to Prizm Annotation Server
         at PrizmAnnotServer.RequestHandler.ProcessRequest()</pre>
    </body>
</html>

Annotation Data

Prizm Viewer uses an XML-based format for representing annotation data. To work with the complete set of Prizm Viewer annotations, you must deploy an annotation server that is compatible with the Prizm Viewer annotation data format.

Data Markup

Prizm Viewer uses XML to store annotation data, based on Accusoft's NotateXpress technology. It must adhere to the Prizm Viewer Annotation schema, which is located in the Prizm Viewer Admin Help.

Storage

Prizm Annotation Server for Prizm Viewer samples require a persistent store for saving the annotation data. The samples included with the Prizm Viewer Development Kit demonstrate use of the file system or an ODBC compliant database as the persistent store.

Prizm Annotation Server samples are capable of using the file system as the persistent store, organizing annotations into files, including folders. Prizm Annotation Server samples create a mapping between the image URL that the annotations apply to, and the file system. The sample will store all the annotations in a designated folder, creating sub-folders that mirror the directory structure found in the image file URL's.

File

Prizm Annotation Server samples are capable of using the file system as the persistent store, organizing annotations into files, including folders. Prizm Annotation Server samples create a mapping between the image URL that the annotations apply to and the file system. The sample stores all the annotations in a designated folder creating sub-folders that mirror the directory structure found in the image file URL's.

Database

Prizm Annotation Server samples are capable of using an ODBC-compliant database as a persistent store. The samples have been tested using a Microsoft Access 2002 database, and should not require significant source code modification to work with high-performance database engines, such as Microsoft SQL Server, or Oracle.

The source code ODBC interfaces match the schema used in the included Access database. The schema used works well with an Access database, but better schemas are available with other database engines.