WIBS Roadmap - *Draft* Sept. 30, 2004

1. Directories and files to start with

To begin with, you will need a servlet container and need to install Cocoon <http://xml.apache.org/cocoon/> and MySQL <http://www.mysql.com/>. I am going to assume the use of Tomcat for this document for servlet containers but there are other options, such as Jetty and Resin, which should also work.

Create the WIBS database by using the mysql.sql script to be found in the src/util/iCal directory. One simple way to do this is to open the MySQL client from the directory where mysql.sql is located and then issue a:

source mysql.sql;

from the mysql prompt. MySQL is well documented and lots of good starting points can be found at the MySQL site.

After the database has been created, copy the wibs directory into the cocoon folder that is defined by the servlet setup. In most cases, this will be something like jakarta-tomcat-5.0.25/webapps/cocoon. You can do a quick check that Cocoon is working by pointing your browser to whatever location your servlet container is using, for example:

http://127.0.0.1:8080/cocoon

Be aware that “127.0.0.1” is always your local machine. Often “localhost” works as well, but “127.0.0.1” normally gets you out of operating systems dependencies. Cocoon will initially take a while to load, but once you see it, the main operating environment for WIBS is in place.

Assuming that you have MySQL running and have created a userid/password for using with WIBS, you now need a way for Cocoon to communicate with the database. Look for the file cocoon.xconf in the WEB-INFO directory in the cocoon folder.

Look for the lines shown below:

<jdbc logger="core.datasources.mysqlpool" name="mysqlpool">

<!--

If you have an Oracle database, and are using the the

pool-controller below, you should add the attribute

"oradb" and set it to true.

<pool-controller min="5" max="10" oradb="true"/>

That way the test to see if the server has disconnected

the JdbcConnection will function properly.

-->

<pool-controller max="10" min="5"/>

<!--

If you need to ensure an autocommit is set to true or

false, then create the "auto-commit" element below.

<auto-commit>false</auto-commit>

The default is true.

-->

<dburl>jdbc:mysql://localhost:3306/wibs?autoReconnect=true</dburl>

<user>wibs</user>

<password>wibs</password>

</jdbc>

You will need to specify your MySQL username in the user tags, and the MySQL password in the password tags. You will also need to edit the file web.xml in the same directory in order to specify the JDBC driver for the database. Look for the init-param section that specifies load-class and change it to the following:

<init-param>

<param-name>load-class</param-name>

<param-value>

<!-- For Database Driver: -->

org.hsqldb.jdbcDriver

<!-- For MySQL Driver -->

com.mysql.jdbc.Driver

...

If you have additional databases you will need to talk to for authentication, each of them needs similar entries in web.xml and cocoon.xconf. The section above refers to Java classes that will be loaded with Cocoon, and you will need to download the appropriate JDBC driver for the version of MySQL that you are running. This can usually be found at <http://dev.mysql.com/downloads/connector/j> but the main MySQL web site is usually the source of the definitive link for this.

The Java classes are typically deployed in a jar file, and the mysql jar file can be placed in the cocoon/WEB-INF/lib directory. You normally need to reload Cocoon for this to kick in, either through the Tomcat management interface, or by restarting Tomcat, but WIBS has a number of Java classes it uses for day to day operation, and this is a good point to put them in place. Although they can be copied manually, like Cocoon itself, it is a good idea to use Java to compile them and put them into place to avoid platform/version issues. Java's most popular building tool is called ant, and you can normally find it in the Cocoon distribution directly in the tools/bin subdirectory. You can test it out by specifying the path followed by ant on the command line, e.g.

cocoon/tools/bin/ant (for unix/mac)

cocoon\tools\bin\ant (for windows)

If ant is ready to go, it will tell you it can't find the build.xml file and this is the file that sorts all of the nitty gritty Java dependencies that can even drive developers insane. WIBS comes with 5 applications that use ant and have a build.xml file. In each case, the process of deploying them is the same, you navigate to the directory where the application is located, and edit the build.xml file to reflect the directory structure of your setup. This involves changing two lines in each build.xml file as shown:

<property name="cocoon.home" value="/src/tomcat/webapps/cocoon"/>

<property name="catalina.home" value="/src/tomcat"/>

The “cocoon.home” directive specifies the directory for where cocoon is located while the “catalina.home” directive does the same for tomcat. One can normally be derived from the other but they are specified separately in case the servlet container uses a different directory convention for web applications. You can go through, modify build.xml, and then type the command to run ant for a deployment using the syntax:

ant deploy

This is done in each of the following directories off the main WIBS distribution:

dist/src/icsGenerator

dist/src/seth/sethTransform

dist/src/util/formsWibs

dist/src/ReportSerializer

dist/src/StartTime

Only the seth directory is optional, all of the other applications are needed by WIBS to carry out functions that are not directly support in Cocoon. The really curious can look in the src directory to see what these applications do.

If Cocoon restarts without any errors, copy the wibs folder to wherever Cocoon has been installed, making it a subfolder of Cocoon. From now on, you will mostly be working within the wibs directory structure. The heart of a Cocoon application is the sitemap.xmap file, and you will see these throughout many of the directories in Cocoon. The one to examine first is located in the root wibs folder as shown:

This file can be daunting at first, but the format of it is well documented at the Cocoon site. The section to focus on is contained with the global variables, as shown:

<global-variables>

<!-- hours - each branch needs entries for hours IF they are

different, these can be set here or in the subdirectory's

sitemap for the branch

please note: this is not a standard 24 hour clock, since

some libraries are open past midnight,

e.g. 26:00 represents 2 AM

-->

<central-sun-open>22:00</central-sun-open>

<central-sun-close>26:00</central-sun-close>

<central-mon-open>8:30</central-mon-open>

<central-mon-close>26:00</central-mon-close>

<central-tue-open>8:30</central-tue-open>

<central-tue-close>26:00</central-tue-close>

<central-wed-open>8:30</central-wed-open>

<central-wed-close>26:00</central-wed-close>

<central-thu-open>8:30</central-thu-open>

<central-thu-close>26:00</central-thu-close>

<central-fri-open>8:30</central-fri-open>

<central-fri-close>26:00</central-fri-close>

<central-sat-open>8:30</central-sat-open>

<central-sat-close>22:00</central-sat-close>

<!-- the number of days ahead allowed for booking,

this is the total number of days that the

calendar will show on the booking screen

-->

<num-days-ahead>7</num-days-ahead>

<!-- total number of minutes a patron can accumulate -->

<day-total>120</day-total>

<!-- first field to give focus to on the form for booking -->

<first-field>barcode</first-field>

<!-- threshold for signin (in minutes)

how long to wait for someone to show up for a pre-booking

-->

<threshold-time>15</threshold-time>

<!-- threshold for grace (in minutes)

how long to hold a pre-booked session before giving a station

to another patron

-->

<grace-time>10</grace-time>

<!-- default time (in minutes)

what timeframe to default to in a booking

-->

<default-time>60</default-time>

<!-- fallback time (in minutes)

if something goes wrong, like the booking database is unavailable,

how long to give a patron in the hope that when they sign in again,

the systems will all be available, i.e., generally a

shorter session than the default-time above

-->

<fallback-time>30</fallback-time>

<!-- rolling window for checking bookings after signin (in minutes)

when a patron signs on, the client station looks for a station

within this timeframe for the active booking

-->

<signin-time>30</signin-time>

<!-- how many minutes before end of session to warn user -->

<warn-time>5</warn-time>

<!-- how often (in minutes) to check server for messages,

this may put some load on the system for a lot of stations so don't

set to 1 unless you anticipate sending a lot of messages or

constantly kicking people off

-->

<message-offset>2</message-offset>

<!-- this defines the windows parameters for the browser window opened

when a session is started, you may want to tinker a bit withh the

width and height settings to match the screen real estate available

in your setup, for debugging, it is useful to make some of

the browser options available for functions like

'reveal source'

-->

<logon-window-opts>

width=500,height=350,status=yes,toolbar=no,menubar=yes

</logon-window-opts>

<!-- the absolute file path is needed in WIBS for the excel reports,

you should use forward slashes and short file-names in

windows systems though there are reports that this doesn't

always matter

-->

<absolutepath>

/home/ahyno/src/jakarta-tomcat-5.0.25/webapps/cocoon/wibs

</absolutepath>

<!-- put IP ranges here for access to iCal feeds, for example:

137.207 (would cover any IP from 137.207.0.1 to 137.207.255.255)

137.207.12.1,137.207.13.4 (only these 2 addresses allowed)

-->

<iplist>.</iplist>

<!-- home page for sending patrons to if there's no where else to go -->

<home-page>http://www.tbpl.thunder-bay.on.ca</home-page>

<!-- the following variables are used in timer.js so do not

change without checking the script,

these are never displayed and are used by the polling mechanism

-->

<message-width>5</message-width>

<no-message-width>7</no-message-width>

<zap-width>8</zap-width>

<!-- leave for webdav (iCal) use -->

<staging></staging>

</global-variables>

The main ones to start with are the hours specified in the tags that begin with central, these use a 24+ hour clock and designate the hours for whatever library will have stations for booking. Note that the sitemap.xmap file needs to contain valid XML, and comments are defined in XML syntax, e.g.

<!-- this is a comment -->

Many libraries now stay open after midnight, and this is reflected in times like 26:00, which indicates that the library is open until 2 AM. Every library that is part of the same system should have a set of hours identified and a “sub-sitemap” entry in the main sitemap. For example, “central” has a corresponding entry:

<map:match pattern="central/**">

<map:mount check-reload="yes" uri-prefix="central" src="central/sitemap.xmap"/>

</map:match>

You can copy the same sitemap.xmap file from central to the other directories with the names of the branches, and use whatever naming scheme makes sense for your setup. The only section that needs to be revised in each case are the hours, for example:

<map:transform src="../stylesheets/sortoutbookings.xsl">

<map:parameter name="threshold_time" value="{global:threshold-time}"/>

<map:parameter name="grace_time" value="{global:grace-time}"/>

<map:parameter name="default_time" value="{global:default-time}"/>

<map:parameter name="signin_time" value="{global:signin-time}"/>

<map:parameter name="sun_open" value="{global:central-sun-open}"/>

<map:parameter name="sun_close" value="{global:central-sun-close}"/>

<map:parameter name="mon_open" value="{global:central-mon-open}"/>

<map:parameter name="mon_close" value="{global:central-mon-close}"/>

<map:parameter name="tue_open" value="{global:central-tue-open}"/>

<map:parameter name="tue_close" value="{global:central-tue-close}"/>

<map:parameter name="wed_open" value="{global:central-wed-open}"/>

<map:parameter name="wed_close" value="{global:central-wed-close}"/>

<map:parameter name="thu_open" value="{global:central-thu-open}"/>

<map:parameter name="thu_close" value="{global:central-thu-close}"/>

<map:parameter name="fri_open" value="{global:central-fri-open}"/>

<map:parameter name="fri_close" value="{global:central-fri-close}"/>

<map:parameter name="sat_open" value="{global:central-sat-open}"/>

<map:parameter name="sat_close" value="{global:central-sat-close}"/>

</map:transform>

The global prefix indicates values set in the main site map, in this case, the hours for central. If you had more than one library with the same hours, you can choose to reuse one definition in as many sitemap definitions as you want. There is one other file to edit for setting the hours, and that is the hours-choices.xml file in the wibs/forms/forms-central directory.

The format of this file is shown below:

<wd:item value="15:00">

<wd:label>3:00 pm</wd:label>

</wd:item>

The value uses a 24 hour clock, but the label can be anything that you wish.It is possible to dynamically change the hours based on the day, but the best option here is to specify the hours for the longest range of hours you are open. WIBS will not let you book a slot that overlaps when the library is closed, but a future version may dynamically alter the hours based on the current day.

Test that your hours look okay by loading the booking page using a URL of the form:

http://127.0.0.1:8080/cocoon/wibs/forms/forms-central/form1

(If you are setting up multiple branches, then your booking form will follow this layout. For example, you could copy the forms-central folder in the forms subdirectory and rename it to forms-branch1 or whatever makes sense for your libraries. See below)

Look for the box entitled Time Controls and select the hours. The display should resemble the following:

Also check the calendar icon. If it displays a standard calendar, you are in good shape. You may notice that the times are not random for when a session will start. This is because WIBS uses a special program to calculate the next logical starting time. For example, at 7:48 PM, a pre-booking makes the most sense at 8:00 PM. This value can be changed by the user, but WIBS will not allow a pre-booking for a time that is in the past.

2. Understanding Branches

Branches in the context of WIBS are locations that are managed by one instance of Cocoon and share the same tables. If you had more than one location and if there was no need to coordinate bookings, then you could also choose to copy the wibs folder for each location within Cocoon. Although a "location" table is created in the WIBS database setup, the location choices are in fact governed by the contents of the location-choices.xml file in the wibs/forms/forms-common directory. The format is shown below :

<wd:selection-list xmlns:wd="http://apache.org/cocoon/woody/definition/1.0">

<wd:item value="1">

<wd:label>TBPL – Main Floor</wd:label>

</wd:item>

<wd:item value="2">

<wd:label>TBPL - Second Floor</wd:label>

</wd:item>

</wd:selection-list>

The values in this case are simple numbers, but this is not a requirement as long as these values are unique. For simplicity, numbers are probably easier. The reason for not using a database table is to simplify the SQL throughout the system and also because the forms definition is more consistent if defined like the other form values. The wibs/forms/forms-common directory contains definitions that are "common" to the forms for each branch, but this is somewhat arbitrary. For example, the hardware-choices.xml, software-choices.xml, and session-length-choices.xml could be varied for each branch by placing a copy of each in the branch subdirectory and refering to the one in question from the form1.xml and form1_template_action.xml files. However, the processing for forms is carried out by the *.xsp files in forms-common, and it is recommended that you leave these files in the current directory until you understand the forms model.

3. Default Values

In addition to the hours, the wibs/sitemap.xmap file contains the default settings and are commented in the sitemap, but some additional information may be useful. The num-days-ahead tag refers to how many days in advance that a pre-booking is allowed. The threshold-time refers to how many minutes a session is considered long enough to make it worthwhile for a booking to occur, while the grace-time tag sets the amount of time that the system will "wait" a signin before making a station available for another patron. The fallback-time paramter refers to the length of time to book a station if it is not possible to talk to the booking database. You should not have to change the fallback-time tag unless you are are trying to offer 15 minute bookings, though it is recommended you have at least a 30 minute minimum timeslot. There are enough variances between timepieces to make it difficult to sort out tight booking timeframes. The message-offset tag refers to how often to check the server for messages or for a go ahead to terminate a session. In most cases, 2 minutes will be acceptable, but 1 minute might be preferable for an extremely busy lab where sending messages to stations is common.

The logon-window-opts defines the browser window that appears when you log on to a station. It is managed here so that you can easily choose to perform activities like "reveal source" in case you need to do station troubleshooting and then later choose to hide the menu bar for example. The absolutepath tag indeed refers to the absolute path, which is needed for producing Excel reports. Cocoon offers a model for doing this that works totally within stylesheets, but the template setup, which is used here, is much simpler in terms of formatting. Basically, an excel "template" is opened for being populated from the database, and formatting can be carried out in the file instead of being hand-coded in the stylesheet. Please note that you should use forward slashes ("/"), even on windows systems. Also, use short filenames if you are running the servlet environment on windows.

The calendar feed in WIBS uses IP authentication. In the iplist tagset, you would put the domain(s) or IP address(es) that you want to have the ability to receive iCal updates. Some calendar systems allow the user of IDs and passwords, but in many setups, IPs will be an easier mechanism to work with, and may be the only option for some calendar systems. Note that you can use http authentication, but this is set within the servlet container and not by Cocoon.

Finally, the home-page tag refers to the URL to use when WIBS has displayed some information, such as the booking details for a patron, and it will be where the patron is sent after they select the "OK" button in such a display.

There are a few other values that are used by WIBS itself and it is preferable to leave these as set.

4. Authentication

WIBS is very flexible in terms of authtentication but it does require that you do some homework on the options that are available to you. Many library systems offer SIP access, which WIBS supports, however, SIP is usually only available for an additional cost with most library systems so this may depend on whether SIP support has been acquired at some point in the past. WIBS can also talk directly to SQL-enabled databases and LDAP servers, but the most common means of authentication tends to be via the library system web interface to the catalogue (WebCat). This is done with a special stylesheet mechanism and it's important to remember that there are two points of authentication in WIBS. One for a pre-booking, and one for when a patron signs in on a station. In both cases, some information (typically a barcode and PIN number) are passed to WIBS, and it is up to WIBS to check that the patron has the appropriate privileges for using the workstation.

There is a slight difference in the input and output formats in these two instances since a patron who is pre-booking is on the web and using WIBS directly, whereas the client station (see below) uses SOAP to carry identification and status information back and forth. The non-SOAP entry point is in the wibs/stylesheets directory and is called bind.xsl, while the SOAP version is entitled soapbind.xsl. The stylesheets look quite similar, and perform very similar functions. The difference is that one is set up to handle SOAP syntax, and also works from the starting point that the station is already known, i.e., if you are signing into a station, then presumably, this is the station your session should be associated with. A snippet from soapbind.xsl is shown:

<xsl:stylesheet version="1.0"

xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ns1="urn:WibsCheck"

xmlns="http://seth.sourceforge.net">

<xsl:variable name="station"

select="SOAP-ENV:Body/ns1:getBooking/station"/>

Despite the verboseness of SOAP, the idea is quite simple, a sequence of information is sent in an XML format (SOAP) and the stylesheet extracts that format. Now consider a WebCat that uses a form to specify identification information for patrons. We use a transformer in Cocoon parlance to pass the information we need to the WebCat. Our sitemap entry for SOAP handling could look like this:

<!-- main SOAP handler -->

<map:match pattern="wibssoap">

<map:generate type="stream"/>

<map:transform src="stylesheets/soapbind.xsl"/>

<map:transform type="sethTransform"/>

It is highly advised that you read an introductory article on Cocoon to better understand Cocoon's generate-transform-serilize model, but what is happening here is that soapbind.xsl is reformating the information from the SOAP request into a format that is used by the transformer, in this case called sethTransform. The format looks like the following:

<execute-retrieval xmlns="http://seth.sourceforge.net">

<url>http://thelibrary/web2/tramp2.exe/log_in</url>

<method>GET</method>

<nvp name="SETTING_KEY">ssr_ep</nvp>

<limit>a</limit>

<station><xsl:value-of select="$station"/></station>

<barcode><xsl:value-of select="$orig_ident"/></barcode>

<pin><xsl:value-of select="$orig_pin"/></pin>

<debug>TRUE</debug>

</execute-retrieval>

sethTransform uses an XML-based syntax to specify the URL to be retrieved (http://thelibrary/web2/tramp2.exe/log_in), the method to retrieve the URL (GET or POST), any number of name-value pairs (SETTING_KEY), whether only certain tags need to be examed on what is returned from the URL target (the anchor or a tag), and the values that identify what the user has specified, as well as the station and whether the session should run in debug mode (TRUE). Setting debug to true is recommended while you sort out interactions with a web site. The soapbind spreadsheet produces this output and the transformer carries out the transformation. In this case, and typically, the "patron information" part of a web site will involve one or more steps for zeroing in on the point that allows identification information to be specified. So we might need to add an additional stylesheet to go through the retrieved content and then set up a second pass at the web target. The sitemap would then look like:

<map:match pattern="wibssoap">

<map:generate type="stream"/>

<map:transform src="stylesheets/soapbind.xsl"/>

<map:transform type="sethTransform"/>

<map:transform src="stylesheets/ssrl1.xsl"/>

<map:transform type="sethTransform"/>

You need to study the examples to fully appreciate this process, but stylesheets are well suited to this kind of "back and forth" with a remote web site. For example, if we need to extract the URL for a link with a particular title used in an attribute, we can do so with the following kinds of expressions:

<xsl:value-of select="contents/a[contains(@title,'View your library account')]/@href"/>

Stylesheets use a mechanism called XPath that shines at drilling into XML/XHTML content. Many web catalogues now use dynamic URLs and session parameters, but it is possible with this approach to navigate very intricate web applications and extract needed portions for use in authentication.

WIBS also contains an administrative layer and uses a user/password mechanism. In the wibs/content directory there is a file called userlist.xml that uses the following syntax to specify userid/password information:

<user type="admin">

<users>

<user type="admin">

<name>wibs</name>

<password>wibs</password>

</user>

<user type="student">

<name>student</name>

<password>student</password>

</user>

</users>

</user>

The admin interface and the authentication used to access it are laid out in the wibs/forms/sitemap.xmap file. It would be trivial to switch this authentication to IP-based or other mechanisms. It would also be possible to look for certain status information in patron records and so on for designating who can have access. There is some provision for different levels of access, for example, a user with “student” access can clear bookings, and send messages to particular sessions, but they can't add stations or purge entries.

Changing the functions that are available to different roles is tied to the form2 and form3 XML files located in the wibs/forms/forms-common directory, and it is here you can specify what options should be available.

5. Admin Interface

The main Admin interface of WIBS is available by using a URL of the form:

http://localhost:8080/cocoon/wibs/forms/admin/form2

Right now, the Admin interface assumes the use of one database in WIBS, but it would be possible to both have one admin layer talk to multiple databases, or multiple admin layers to talk to one database. Using the admin/admin combination described before, you should be able to log in and will get a menu of options, as show below:

The first option is where the most things happen in WIBS. By default, it looks like the following:

The database creation script adds a few entries to the WIBS tables, so you can select a few of the List/Review options at the bottom of the form to get a sense of how the Admin interface handles viewing/editing items, even before any bookings have occurred. In general, the philosophy is to select the Search option if you are trying to drill down to the database, and then select Next, or otherwise, selecting Next indicates that you want to add an entry to the database. You can view or purge Events based on a date range, or search and also preemptively add patrons by selecting the Patrons tab. One common scenario might be to “block” a particular patron (maybe he/she owes a lot of fine money!), in which case you would fill out the form for the patron, and then change the block_flag in the resulting display to true.

Note that you can send a message to specific stations by identifying the current session in the Events listing. You can also set a message to appear when someone logs on, or choose to kick someone off. This uses a polling mechanism on the station itself, so it might take a minute or two for either the message or station shutdown to occur. [I need to explain how this communication takes place, maybe a section on “stupid browser tricks”?]

6. Setting up Client Workstations – Browser-based in Windows

WIBS uses pluggable authentication on client stations, for Windows, this takes the form of a pGina module <see http://pgina.xpasystems.com/> while for Linux, other derivatives of Unix, and also for Mac OS/X, there is an option to take advantage of PAM. Whatever the platform, the basic goals are the same:

minimize the amount and complexity of software required on the desktop

use a common authentication mechanism on the server

leverage web browsers for managing the session as much as possible

To achieve these goals, WIBS uses SOAP for communicating with the server (or whatever you want to call the machine running your servlet container), while relying on a series of helper applications to work with the browser on the desktop. One major advantage of using SOAP is that the authentication can be swapped on the server at any time, and if you have ever installed ODBC drivers and similar layers on a desktop, you can readily appreciate a simple base of software for login security.

pGina is an implementation of GINA <see http://www.cswl.com/whiteppr/white/gina.html> and follows some strict rules on what types of operations it can carry out when running. One consequence of this is that when the browser is loaded after a patron has logged on and been assigned a session, the browser ends up asking the server what session it is working with. In other words, there is no easy way for the authentication layer to pass session information on to a desktop application like a Web browser (this isn't as true for PAM but it also somewhat complicates things to hand-off values to an application). This is important to understand when setting up WIBS because you will probably want to experiment with the helper applications and to do this, it is easiest to work with an existing session.

What I often do is book a session, and then change the parstat value in the events table from “T” (which stands for Tentative) to “I” (which stands for In-Progress). The reason to do this is that the browser will ask WIBS for the session that involves the station it is running on and the server will combine the station identification with the partstat value to identify the session. As part of authenticating a user, WIBS will mark the session as in-progress, and normally the browser will follow up within seconds or minutes to pick up the session. If you want to see what happens up close, do a pre-booking, change the parstat flag in MySQL, or, get your hands on the “xmlhttp” application (see <http://webservices.xml.com/lpt/a/ws/2003/03/18/cocoon.html>), and uncomment the section in the wibs/sitemap.xmap file as shown:

<map:transformer

name="xmlhttp"

label="tran-xmlhttp-lbl"

logger="sitemap.transformer.xmlhttp"

src="com.clsw.cocoon.XmlHttpTransformer">

</map:transformer>

With this in place, you can then uncomment the SOAP “test” section of the same sitemap.xmap file and issue a URL in the following format:

http://127.0.0.1:8080/cocoon/wibs/soaptest

to set up the session defined in the wibs/content/wibs.xml file. By default, this file creates a session for a station named TEST01 and the system treats the session as if it were coming from any SOAP-enabled system like pGina. At this point, you can then open your browser with a URL of the form:

http://127.0.0.1:8080/cocoon/wibs/central/wibslogon?station=TEST01

You may notice that if you don't have an existing session where the parstat value has been set to “I”, you will be given a short session or whatever you have defined fallback-time to be in global variables. The reason for this is that WIBS doesn't have any way to identify the session without the parstat value and this scenario would most likely happen in a case where a station couldn't communicate with the server because of a network problem at the time of signin. The short booking is an attempt to provide some level of access in the face of not knowing anything about a session. You don't normally want this sequence for testing because the browser really needs a valid session id in order to tell the server when a session has ended. It also won't allow a station to ask for more time unless the session is already in the Events table.

The initial browser window looks like the following:

Note that you will have to “unblock” the site that is hosting WIBS if you are using FireFox or any other browser/helper/toolbar mechanism that doesn't allow subwindows. The browser relies on three “helpers”:

one to put the browser window in front of the user when needed (initial logon, warning when the session is close to ending, messages sent from Admin)

one to minimize the browser window and move it out of the way

one to terminate the session

There is also one additional application run when the desktop is loaded to make sure that a user doesn't simply close the browser before it has time to load the initial settings.

The helper applications are invoked like any others within a browser. The idea is define a unique MIME type, and the operating system will run the helper application when the browser indicates it has an object of this type. Note that WIBS helper applications need to be set to run automatically, the browser can manage the session, but it takes platform-specific tools to enforce its directives.

We will add a few entries to the File Types supported by Windows using these programs. These can be set in Windows Explorer under Folder Options as shown:

This will bring up a list of file types supported by the system.

c:\wibs\wibstart.exe browser.exe TEST01 40 \wibs\restart.exe

7. Setting up Client Workstations – SOAP-based for all platforms

WIBS exposes booking information via SOAP so that generic client software can be developed. Like the browser-based client, the assumption is that a patron has cleared the login security layer and and a session has been recorded for the station, using the methods outlined above. You can then use the station identification through SOAP via the services defined in the session.wsdl file:

http://127.0.0.1:8080/cocoon/wibs/session.wsdl

to get information about the session. You should get back 3 values:

sessionID	the id of the session, which you will need for checking with the server from this point on
sessionLength	the length (in minutes) of the session
sessionEnd	a datetime string of when the session ends, you probably don't need this with most languages, it might be easier to get the string from the server to display to the user

In the current implementation, these are all strings due to some pecularities we have run into with some SOAP toolkits, but this may change in the future. The basic idea is that you will get a valid sessionID (or -1 if the server can't find it), a sessionLength (the server should always be able to come up with this), and the sessionEnd string (e.g. 11:00:00 AM).

The other service is at:

http://127.0.0.1:8080/cocoon/wibs/poll.wsdl

It has three values it requests:

session	the id of the session on the station.
extend	either 'Y' or 'N'. If 'Y', you are asking to extend the session.
signoff	either 'Y' or 'N'. If 'Y', you telling the server that the session is over

On some sort of pre-set schedule, my sense is that your program will send a session ID and the value of 'N' for extend and signoff so that you can get an update from the server about whether a message is waiting. The values that come back are:

sessionStatus	either '0' - no message waiting, '1' - message needs to be displayed, or '2' - please terminate session.
sessionLength	if you are requesting an extension of the session, this value indicates how many minutes the session has been extended by (a value of '0' means it can't be done).
sessionMessage	if a message is waiting, or if an extension has been requested and it can't be provided, the text to display to the user is also placed here.

Note, that when you inform the server that the session is over, it does send back a response of '0' for the sessionStatus, and 'Goodbye' for the sessionMessage. My thought is you will likely inform the server, but not bother waiting for a response since the program will be busy initiating a logout/restart.

You will also want to work with the admin interface so that you can set the message/zap options to see what happens on the client. You can also see the server recording the end of the session. These services have all been tested against the generic SOAP client at:

http://soapclient.com/soaptest.html

But your milage may differ depending on your SOAP tools.

8. Using SVG for Workstation Maps

Scalable Vector Graphics (see <http://www.w3.org/Graphics/SVG/>) are a neat way to deal with dynamic graphics. There is a very nice OSS “platform-independent” SVG editor called InkScape at <http://www.inkscape.org/>. The way this works in WIBS is that a stylesheet modifies the base graphic and uses Cocoon's supplied SVG tools to render the image in JPEG format. The sitemap for each location, e.g. wibs/central, contains a snippet like the following:

<map:match pattern="showlocation">

<map:generate type="file" src="../content/location.xml" />

<map:transform src="../stylesheets/location2html.xsl">

<map:parameter name="use-request-parameters" value="true"/>

<map:parameter name="home_page" value="{global:home-page}"/>

</map:transform>

<map:serialize type="html"/>

</map:match>

<map:match pattern="drawlocation/**">

<map:generate type="file" src="../svg/{1}.svg" />

<map:transform src="../svg/stylesheets/{1}.xsl">

<map:parameter name="use-request-parameters" value="true"/>

</map:transform>

<!--

<map:serialize type="xml"/>

-->

<map:serialize type="svg2jpeg"/>

</map:match>

What this does is associate an SVG file with an XSLT file of the same name, in the distribution, you can find examples of this in the 1.svg and the 1.xsl files in svg directory. This can be invoked with a URL of the form:

http://127.0.0.1:8080/cocoon/wibs/central/showlocation?station_name=TEST01&location=1

In this case, the sitemap entry for showlocation will make sure the generated JPEG is contained within an HTML file. This can be important because browsers can be a little strange about receiving images directly, and this method allows you to set the width and the height of the image within the HTML output rather than letting the browser define a rendering. In some environments, you may be able to deliver SVG directly, there are browser plug-ins for this type of support, but the most wide ranging option for browsers is to convert the file on the server.

9. Using Dynamic Spreadsheets for Statistics

Art Rhyno

2004-07-21T18:28:55

Art Rhyno