File:		LibData_Intro.rtf
Title:		LibData Introduction & Functional Description
Author:	Paul F. Bramscher brams006@umn.edu
Date:		July 20, 2004

Table of Contents

1.0	Introduction
2.0	System Accounts
3.0	Resources
4.0	Subjects
5.0	Authoring Environments
5.1	Research QuickStart (RQS)
5.2	PageScribe (PS)
5.3	CourseLib (CL)
6.0	Manager Functions
7.0	DBA Tools
8.0	Statistics
9.0	Patron Interfaces
10.0	Conclusion / Credits
11.0	LibData Licensing

1.0	Introduction

LibData can drive many sorts of library-related web pages and collections of pages dynamically from a rich web-maintainable database.  It is not properly placed into existing categories of applications such as content management systems, course management tools, subject pathfinder builders, or catalogs.  It is probably a little of each, with the ability to change emphasis depending on how the data set is populated and used locally.

The system has two main authoring environments: CourseLib/PageScribe (referred to collectively as CLPS) and Research QuickStart (RQS).  CourseLib is a modest library-centric course authoring tool, whereas PageScribe is the free-form version (without the course-related data fields).  They are essentially the same application, capable of building two sorts of pages.  Research QuickStart is an authoring environment to build subject-centric web pages.  These pages are more uniform than CLPS generated pages (only resources may be added to RQS pages, although they may also cross-reference PageScribe pages), and they are added to a customizable two-tier information type ontology.

There are both public and administrative portions of LibData.  Basic use statistics are collected from the public portion.  An internal authentication and multi-level access system based on roles was also developed to support administrative functions.

It is driven by an underlying collection of about forty database tables tied together relationally.  Most all of these tables are maintained through web-based forms and are fully customizable for content -- allowing for a rich authoring environment with a great deal of possibilities.  The majority of data relationships are optional associations, so LibData's flavor fluctuates in proportion to the work done in populating and associating relationships.

A populated enterprise instance of LibData requires collaboration between staff with complimentary areas of expertise.  Such staff might include a unix/linux administrator, a programmer familiar with web scripting technologies, a seasoned SQL/database person, as well as a web designer.  Of course we often need to wear more than one hat, but LibData will be more reliable and more customizable (as with any technology) given more staff and levels of expertise.

It is hoped that the programming code is simple, even simplistic, and self-documenting whenever possible.  This self-documentation includes comments which accompany the great majority of the functions, as well as copious use of mid-logic commentary.  Writing obfuscated code comes naturally to programmers, so documentation and clarity are unfortunately goals rather than starting points.

2.0	System accounts

The following is a very cursory discussion on role-based security within LibData.  Note that the actual functions are not discussed here (refer to 5.0 Authoring, 6.0 Manager Functions or 7.0 DBA Tools respectively for functions available to Authors, Managers, and LibData DBA’s).  This section is meant to introduce these roles.  There is also capability for Guest and Denied access levels.  Guest accounts are not yet implemented but might, in the future, allow for limited read-only access.  Denied access is useful to lock a user out of the system, but retain his/her account for whatever reason (historical, perhaps they’re on a leave of absence, etc.)

Session and state handling

The login URL will depend on your LibData installation.  It may be something of the form https://www.yourlibrary.edu/libdata/login.phtml.  Note that it’s an https (SSL) port.  Note also that the logout option is currently only on the Author console (explained further below), this section is common to all roles.  Sessions are tied to IP address, stored both in a client-side cookie as well as in a server maintained session database.  Once logged in, a session lasts for as many minutes as specified in the first instantiation of the sessionClass object specified in login.phtml.  The default LibData OS release is 7200, or 2 hours.  Activity or inactivity during this span doesn’t affect the longevity of the session.  So it’s assumed that LibData staff are accessing the administrative portion through office computers in non-public areas.  They may head out to lunch, coffee, or a short meeting and still come back to an authenticated session.  Note that LibData technical staff can adjust the 7200 setting in login.phtml to anything else (higher or lower) as desired (with a minimum of 2 minutes and a maximum of 12 hours as defined in sessionClass.php).

Visible menus

There are several access levels: Denied, Guest, Author, Manager, and DBA.  Currently only Author, Manager, and DBA are implemented.  Anyone below Author access currently has no access, and any account (regardless of access level) is denied if it should have no password assigned to it.  Passwords are assigned and maintained by Managers and DBA’s.  As standard practice with unix systems, password are encrypted and never displayed.  As a result, Managers can never retrieve a forgotten password -- but they may reset it to something else.

Users of Author access see only the authoring console (console.phtml).  Managers will notice an additional link at the bottom of the main authoring console allowing them to reach Manager Functions (console_manager.phtml).  DBA’s see a third link “DBA Tools” (console_dba.phtml).

Authors

Authors may create new resources and edit any resource.  They may delete only resources they’ve created themselves.

They have the capability to create CLPS pages.  They may edit and delete their own pages (page creators are by default the initial coordinator of that page).  Additionally, they may be assigned (by another Author, Manager, or DBA) to co-maintain a page.  Authors may not edit or delete pages they are not the coordinators or co-maintainers of.  They may assign other maintainers, and even remove themselves from coordinator status.  If an Author selects a new page coordinator -- without first assigning him/herself as a co-maintainer -- the Author is locked out of that page and responsibility for maintenance falls on other staff.

Within the RQS authoring environment, Authors may create new subjects from the “New or Delete” link on the main authoring console, console.phtml.  The currently logged in Author is initially assigned to the newly created subject.  S/he may add other staff persons.  Authors may not edit subjects for which they are not assigned.  So, for example, if an author were to remove him/herself as assigned staff, s/he would be unable to get back into that subject.

Managers

Managers may create and edit/delete all resources (regardless of whether they created them.)

They may edit CLPS pages they’ve created, are coordinators of, or co-maintainers of.  Additionally, they may edit pages created by any staff person defined as a member of a Library Unit for which they are listed as Unit Lead.  Staff may (or may not be) assigned to Library Units by Managers on the Manager Functions console.  Not all Managers need be listed as a Unit Lead.  So there is a subtlety with Manager status: one may have varying degrees of managerial rights (being a unit lead or not, and a unit lead over which body of employees).

Whether or not a Manager is a unit lead, s/he may access the Manger Functions console and modify virtually all of the system setup tables, including the assigning and re-assigning of Unit Leads themselves.  Thus, this level of access requires a collegial trust among managers.  If one manager leaves the organization, another may put him/herself in that position without calling upon a DBA.  Managers can make sweeping changes to the system, potentially destroy it, create user accounts and manage passwords, etc.  Their only limitation on the Manager Functions console is that they may not promote any staff member to an access level higher than Manager itself (DBA).

Newly created staff accounts must be assigned a password by a Manager or DBA. The password must be a minimum of 6 characters in length and should contain both alpha and numeric characters.  Interspersing special characters such as !@#$^&() is encouraged for additional security (don’t assign passwords containing the single or double-quote characters, since these are problematic from a database perspective).

Managers play a role (as discussed earlier) in assigning Author staff to subjects.
So an author’s access to maintain, for example, the Anthropology subject is connected to an association made by a Manager or DBA in one of either two system setup tables.  From the Manager Functions console it’s possible to enter the staff maintenance system, select an individual staff person, and add/remove assigned subjects.  There is also a subject-centric setup table in which staff persons may be added/removed to a particular subject.  In addition to entering one of these setup tables, there is an overall management view under RQS Assignments that displays subjects alphabetically in the left-most column, and assigned staff to each subject in the right-most column.  Entries in either column are clickable, tooling into either the staff or subject maintenance page respectively.

Database Administrators (DBA)

DBA’s may create/update/delete all resources and CLPS pages.  In addition to all functions on the Authoring and Management Functions consoles, they may promote/demote staff to all access levels (including the creation of other DBA’s).

Currently there is little extra that DBA’s can do that Managers cannot – although the place for future additional functionality is the DBA Tools screen.  Of particular interest is a CourseLib and PageScribe page debugger, which can analyze pages for possible internal SQL flaws (unlikely, but possible if multiple people do contradictory things to a page at the same time).  We’re currently looking at page locking mechanisms and a page fixing tool.  There are also some portal mappings to external (campus-wide) entities that are probably best limited to a DBA role.

In the underlying table structure, each table row typically has a unique ID (primary key) associated with it.  Staff ID#1 is an empty slot, reserved for N/A (with no access rights).  Staff ID#2 is also a special slot, and should be reserved for the System Administrator account.  Beyond this, there is no restriction on the number of accounts or rights assigned to them.

3.0	Resources

Resources will probably be the most common element on  CLPS and RQS pages.  A “resource” can be a printed work, an URL, or both simultaneously.

Resources are initially created on the Authoring console by entering a title and selecting an initial Master Subject or Master Information Type for it.  (Failing to make an initial selection will result in an explanatory message about what these mean.)  Their purpose is to winnow down the list of Information Types in the drop-down box on the Resource entry form.  This list can become large and cumbersome, so both subjects and information types are classified with a two-tier model (roughly analogous to genus/species).  Resources must also have unique titles.  If an exact match is found, the resource may not (as currently programmed) be entered.  If a near-hit is found, the system will prompt whether you want to proceed.

The only required field is the resource title.  Assigning a Base Information Type is strongly encouraged, since when that resource is added to RQS pages it’ll immediately go to its place in the two-tier information hierarchy.  This may be customized for each instance on Subject pages, but it’s useful to have a likely default location for it.

One the resource is saved, additional forms become available: Assign Locations, Features, and Master Subjects.  Data in each of these pick-lists is vocabulary-controlled by a LibData Manager.  Locations (Libraries) should be straightforward.  Features are any flagging/tagging characteristics that might be attributed to the resource.  In the Manager Functions menu, Features can be defined with a graphical image or icon (and ALT text) that’ll appear on the public RQS subject page interface.

Resources are searchable with a basic or advanced search (available as a link from the Authoring console).  Their use statistics (see 8.0 Statistics) are currently being tracked by an exit method implemented on CLPS pages (RQS resource-level usage is not currently tracked, though it may be in a future release).

4.0	Subjects

LibData Subjects are created by Managers from an option on the Manager Functions table.  They may be associated with a primary and (multiple) secondary locations that appear on that Subject’s corresponding RQS page.  They may also be created by Authors by clicking “New or Delete” on the main console (console.phtml).

They should also be associated with one (or more) Master Subjects.  For example:
Social Sciences (Master Subject) -> Anthropology (Subject).

Authors and Managers may also add/remove Authoring staff to work on various subjects.  Another interface is the RQS Assignments option from the Manager Functions menu (mentioned previously under 2.0 System Accounts).

Once a subject has been created, the subject can now appear in the RQS subject pick-list on the Author console.  Note that it depends on whether the currently logged-in staff account has access rights to the subject in terms of whether or not it appears in the list (see the discussion under 2.0 System Accounts).  DBA’s, for example, will see all subjects in the pick-list, Authors the least.

Note that while a subject appears in the pick-lists for assigned staff it does not yet appear on any public interfaces (it is in an unpublished and empty state).  A subject may now be authored by RQS (refer to 5.1 Authoring Research QuickStart) below.

In summary, for a subject to be editable, it must either (a) be assigned to the currently logged in Author or (b) the currently logged in manager must be unit lead to which the author belongs or (c) all subjects are available if the current user is a DBA.  Alternatively, any manager may simply go in and assign him/herself rights to maintain that subject directly.

5.0	Authoring

LibData has two main public interfaces: RQS and a page-rendering mechanism that handles CLPS pages.  Both types of authoring are begun from the main authoring console, console.phtml.  New subjects and CLPS pages may be created by Authors by clicking “New or Delete” below the appropriate pick-list.

When an author clicks to create a new CLPS page, or if the author follows the “CourseLib/PageScribe Pages” link in the LibData header, the scribe_start.phtml page is reached.  From this page, a new CLPS page may be created.  Or the author may select among a list of pages that s/he currently has authorization rights over.  A final option is the ability to Clone & Load any page as a template for a new page.  This command give the author the ability to copy any other author’s work.  A disclaimer prompt is given, to first encourage some sort of agreement with the coordinator of the cloned page.

Both authoring environments will likely pull heavily from the Resources table.  Navigating from an authoring environment to create new resources is disrupting to work flow.  Entering a resource suggests one task (cataloging oriented), whereas laying resources out in an authoring environment suggests another (page layout and selection).  Therefore it is recommended that “setup” tables be populated to the greatest extent beforehand: resources, subjects and master subjects, information types and master information types, locations/libraries, services, staff, etc.  RQS subject or CLPS page design then becomes a much easier task.

The Author menu, also referred to as the authoring console (console.phtml) contains commands to initiate the maintenance of RQS and CLPS pages (and will be detailed in detailed in sections 5.1 and 5.2 below).

Other options on this menu include linking to the statistics screens (specifically treated in 8.0 Statistics), searching for CLPS pages, information demographic drilldowns, a link to a basic or advanced Resource search interface, and the ability to edit or delete resources by a known system ID number.  This number is displayed on all Resource entry/edit forms, as well as on the (administrative side) search results page.

Searching CLPS pages

Note: Due to database structure, instructors are OR’d in the search.  So it’s not possible to permute a search in which you’d like to combine a library staff person (as instructor), TA with a faculty person to see which course they were associated with (at most one of the three may be picked).  Other fields may be filled in or not to further limit the search.  Most all of the fields are substring-type searches.  For example, entering “.gov” (without the quotes) in the URL field will retrieve a list of all .gov URL’s on all CLPS pages.

Drilldowns

These are available to Authors and above to view demographic relationships of data in LibData.  Note that most of the demographic displays, when fully drilled, have a right-most “Edit” command.  Authors may frequently run into a “not authorized” message when attempting to edit a page or RQS subject over which they have no authority.  Managers may get this message as well, though with less frequency.  So these drilldowns are meant to over an all-encompassing view, not geared toward only the current user’s assignments.

5.1	Research QuickStart Authoring

The editing environment of RQS pages was designed to be as fast as possible at building subject-centric web pages.  We’ve found that work flows best when resources are fully populated into LibData, with as much descriptive material as possible.  Of particular utility is to supply a default description and base information type to all resources.  If this is done, much of the work involved in adding them to RQS pages will be minimized since the data will be used as default settings during its initial placement on RQS pages.

Don’t confuse editing an RQS subject page with editing the subject itself.  Editing the subject will change its description on the public RQS interface, it will also display the subject’s primary location (library) as well as any secondary location(s).  Modifying these aspects to an RQS page is not handled from the RQS authoring environment (described here).  It is handled from editing the subject record directly, available as an option on both the Author and the Manager Functions consoles since Location maintains a system-wide controlled vocabulary for its particular data set.

Once an RQS subject has been selected for authoring from the main console, console.phtml, the initial screen the following functionality is available.

Preview/Publish Commands

Preview

Displays the current RQS subject through the patron interface.  Note that this may involve a switch from SSL to non-SSL, depending on LibData installation.  Browsers may prompt with some sort of notification box.

Preview Core

When resources are added to a page they may be added as a “core” resource.  On the RQS public interface is a link to “show only the core resources.”  This allows RQS subject authors the ability to create highlighted subsets of the page. Any resource on a page can be switched back and forth from core (see Edit Resources below).

Publish (or unpublish)

RQS subject pages are not initially available on the public interface until the RQS page is published.  When published, the “Publish” button is replaced with an “Unpublish” button.

Add Resource Commands

Limit

The resource pick-list can be limited by first letter of the title.  Or it may be limited by a substring search on both the title and description, any “features” assigned to it, or by its master information type – or any permutation of these limits.  Clicking the “Limit” button will limit the pick-list to supplied criteria.

Add					

This will add the resource to the RQS page.  Note that the resource automatically goes to its place in the two-tier information hierarchy based on its assigned base information type (which hopefully is assigned a master information type).  If either were not given, it goes into the (N/A) category and must be manually moved into a new category (see edit resources below).

Note that there is a subtlety programmed into the system: it is possible to have the same resource in a particular slot in the information hierarchy on the same page only once.  For example, it is not possible to have Google appear twice on a subject page entitled Internet Literacy under the heading WWW Resources -> Web Sites.  However, we’ve built an exception case.  Google may be added a second time to the subject page, and this time it will NOT float to its default place on the information hierarchy but, rather, to a (N/A) -> (N/A) position.  It must then be assigned a new information hierarchy position.  Note that assigning it to WWW Resources -> Web Sites when one instance already exists will result in the automatic deletion of the previous instance (enforcing the one time rule of resource per RQS page per information type).

Resources may be selected one at a time (no multiple selects implemented yet).

Add Core

Identical performance to Add above, except that the resource is added to the resource is added as a “core” type resource at the point of addition to the RQS page (and needn’t be toggled as such by editing it later).

Related RQS Pages

Add

Other RQS may be associated with an RQS page.  This allows additional cross-referencing, they appear on the RQS user-interface, set aside from the main body of resources in an HTML table for display clarity to the user.  RQS pages may be selected multiply.

Remove

Removes the selected RQS page(s).  As with Add, multiple selections are possible.

Related PageScribe Pages

Add

PageScribe (but not CourseLib pages) may be associated with an RQS page.  This allows additional cross-referencing, they appear on the RQS user-interface, set aside from the main body of resources in an HTML table for display clarity to the user.  PageScribe pages may be selected multiply.

Remove

Removes the selected PageScribe page(s).  As with Add, multiple selections are possible.

Edit Resources

Edit Base Resource

This option allows for the editing of the resource itself, which will have system-wide ramifications wherever that resource is used.  A common purpose for using this option would be to fix an outdated URL, correct a typographical error, etc.

Edit This Instance

Certain characteristics of the resource’s occurrence on this particular RQS page may be tweaked independently of its base/default values, and its occurrence anywhere else in LibData (including on other RQS pages).

Information Type
The resource may be moved to a different slot in the two-tier information hierarchy.

	Highlighted/Core Resource
If the resource was originally added as “core” or highlighted, it may be unflagged as such – or vice-versa.

	Use Default Description
This radio button MUST be checked to “no” and a unique description supplied in “This Description” (see below).  Simply supplying a unique description without explicitly checking “no” here will result in the changes not going into effect.

Programmer’s Disclaimer: We’re looking at making this not required, but the essential problem is that for LibData to determine whether any changes have been made to the default description (thus automatically indicating a custom description) involves comparing data stored in mySQL server-side with data that has made the round-trip from server to browser client-side, and back again.  Since we’ve allowed for certain characters to be escaped (and potentially more filtering) in the back-end (textInmySQL), and also run through a different parser coming out (textOutHTML), raw character differences will frequently occur.  Thus, in order to make this function reliable, we currently enforce the necessity of manually clicking yes/no to flag this change deliberately, rather than making a potentially misleading comparison in the background of data that make differ not to editing changes but for transparent technical reasons.

	This Description
The default description is the base resource annotation.  It is fully dynamic.  A change to the base resource record will automatically cascade to all occurrences in RQS.  However, if the “use default description” has been checked to “no”, a unique description may be supplied here.  This unique description will then not be affected by changes to the base record’s annotation at a later date.  It can only be modified by tweaking its occurrence on the RQS page where a unique description was supplied.  Note that the title and URL are always dynamically pulled from the base resource record.

Remove

Simply removes this instance of the resource from this RQS page.

5.2	PageScribe Authoring

This section covers both PageScribe and CourseLib, since PageScribe is fully a subset of CourseLib.  However there are additional fields and other things to be concerned about with CourseLib.  So all of the commentary (plus additional issues detailed in 5.3 CourseLib Authoring) apply also to CourseLib.  There is, however, one exception.  PageScribe pages have an additional field, entitled “Page Header” which may be populated with HTML source, descriptive text, etc.  CourseLib pages have their own descriptive fields.

General Notes on Page Structure:
PageScribe and CourseLib pages are built around an outline model with inherent parent-child relationships.  Pages are built with elements.  An element may be of several types (a resource, library/location, a library service, a staffperson, a generic text label,  (up to 64K description with imbedded HTML, and wrapped with an optional URL) -- or a link to an RQS, PageScribe or CourseLib page.  RQS pages may also be “harvested” such that all of their elements are copied to the page (in alphabetical order).  RQS information type hierarchies are not copied with this harvesting procedure, since they don’t apply here.  And, as such, the only meaningful way to harvest them is alphabetically – though they may then be moved around with the up/down arrows.

Many of the commands detailed in this section operate on the parent-child relationship of page elements.  Deleting a parent allows the possibility of promoting all immediate children to the place of parent, or a cascade delete in which all children and descendents (if any) are likewise deleted.  Similar rules apply with copying.  Note that it’s never possible to assign a child to a new parent through adding a new element.  Thus, new page elements may be added only in legal positions: as siblings, new offspring, or before or after entire lineages.

A word of WARNING:
We’ve currently NOT implemented locking or concurrency checking.  So it’s possible to damage a page if two authors simultaneously perform contradictory structural edits to it.  Thus, it is best to distribute page duties such that there is no overlap.  A page may be checked for integrity through an option available on the DBA Tools console (see 7.0 DBA Tools).  If an error is found, one of three fix methodologies is available to the DBA.

A broken page is best handled by avoidance.  If it is broken and it is not repairable using the DBA page fixing tools, probably the best recourse is to print it out, delete it, and ask everyone who might have copied portions of the broken page to purge their copy buffers, and then recreate the page from scratch.  A less damaging option, though perhaps not always successful, is to delete only the damaged portion of a page (deleting, copy buffers, etc. will be explained below).  But note, carefully, that copying a damaged parent-child cluster of page elements will potentially “replicate” the damaged “gene.”  If a SQL guru is available and the page is crucial, damage may be fixed in the mySQL client with some surgically precise analysis on the libdata.elements table.  But be VERY careful with such a procedure...

In a full year (2003/04) of large-scale production usage at the University of Minnesota we’ve encountered only 3-4 page errors, and all have been fixed with the least intrusive methodology (attach foster children to most-likely parent) available on the DBA page fixing toolkit (see section 7.0 DBA Tools).  Note that these fix options are not visible unless an error is found on  the selected page.

Programmer’s Note:
From the Author console, there is a “New or Delete” button under both the PageScribe and CourseLib pick-lists.  Both buttons bring the Author to scribe_start.phtml, but depending on which button is selected, the radio button in scribe_start.phtml indicating whether the page is to be a PageScribe page or a CourseLib page is pre-selected.  It may be toggled to the other selection at this point if desired.  If the user has reached this page directly, for example from a link in the LibData authoring header, then PageScribe is the default selection for the new page (and it may be toggled here).  Once a CLPS page type has been selected, a name chosen, than the authoring environment is entered it may not be switched from PageScribe to CourseLib or vice-versa.  However, portions of the page may be copied and pasted from one page type to the other.

A title must be supplied, and uniqueness is not enforced.  Alternately, it is possible load an existing PageScribe or CourseLib page for editing.  As with the Author console, options in both pick-lists are affected by which pages the currently logged in user has authority to edit.

So whether a page is newly created or loaded for editing (or deleting) purposes, we’ll now briefly detail the available authoring options.

Overall Page Commands

Create Clone

The current page may be copied en masse.  What happens in the background is that all page elements and structure are copied to a new page ID.  The page title is prefixed with “Copy of:” followed by the original source page title.  Note that cloning does not copy over page coordinators and co-maintainers.  These must be re-assigned for the new page (see procedures explained below).  One limitation with our current implementation of cloning is that authors may only clone pages over which they have edit capability (the cloning feature is on the page itself).

Delete Page

Deletes the currently loaded page.  Authors are prompted with a “confirm” box asking whether they really want to do this.  If the page is cross-referenced to any RQS pages, it will be removed from that association as well.  Its statistics will also be purged from the libstats database.  So be careful to archive historical statistics before deleting a page if desired before deleting it.

Publish/Unpublish

The unpublish option becomes available when a page is published and vice-versa.  Note that CourseLib pages have an additional requirement: they may not be published unless a Course subject/designator is selected.  We’ve made this a required field for publishing, not so during authoring.

Publishing currently makes the most sense for CourseLib pages, which have a corresponding pick-list interface.  Unpublished CourseLib pages won’t appear on the CourseLib user interface.  We currently have not implemented a similar pick-list for PageScribe pages, since they are used for a great variety of purposes and share nothing in common with one another (other than the tool they were created with).  However, publishing or unpublishing a PageScribe page, as with CourseLib, has the identical effect of toggling the libdata.published flag to true or false (1 or 0).  So a programmer wishing to create a pick-list of PageScribe pages may key off of this field to display or suppress them from a public user interface as we’ve done with the CourseLib pick-list.

Programmer’s Note: One additional effect of publishing is currently commented out in the scribe_application.php scribePublish() function.  LibData ordinarily displays a dynamic rendition of the page to the user every time the page is loaded.  With the commented out section of code, there is the capability to open a socket to the dynamic page URL itself, suck down all HTML in 4K blocks and build a static snapshot of the page at the instant of publishing.  This snapshot is still stored in a mySQL database field (64K text type field), but the query to render it is trivial (see publish.phtml in the public interface directory of LibData) both technically and in terms of system utilization.  We’ve not yet found a necessity in doing so, so this option has been currently commented out.  Note that we’ve made some changes since we’ve tested this functionality, so minor tweaking might be required to get it going again.  But the possibilities are rather interesting.  It would be possible, for example, to build additional functionality so that several page snapshots might be available.  We’ve had neither the time nor necessity to explore this further, but the functionality is intriguing.  Commented-out code in the scribe.phtml engine allows for the republishing of a page.  That is, the static snapshot may be refreshed.  All of this was fully functional in previous prototypes but it is currently commented out.

Preview

This option previews the currently loaded page in the user interface.  Note that it may involve a switch from an SSL to non-SSL port (as with previewing RQS pages).  An annoying browser message may be involved.  Also, since LibData must constantly refresh the currently loaded page after each command, we must destroy browser cache – otherwise the author might be trying to do something on outdated cached page data (which will likely break the page or cause other errors).  So if there is a message about browser cache lost, the page must be reloaded.  We’ve found that the Mozilla browser seems to give less annoying expired cache messages than Internet Explorer.

Show URL’s in Author Mode / Suppress URL’s

It may be useful for some authors to see URL’s displayed while they are building a page.  This is useful for spot-checking, and gives an idea of what the page may appear like in print-friendly mode (which will display URL’s).  Note that this setting has no effect on the user interface, only on the authoring environment for this particular page.  The suppress option becomes available if URL’s are currently display and vice-versa.

Suppress TOC / Activate TOC

Pages can have an automatically generated table of contents.  This is assembled using root-level page elements by name.  Anchors are built which automatically reference them from the table of contents to their appearance on the page.  The suppress option is available when the ToC is enabled, and vice-versa.

Wrap / Unwrap TOC

Pages with many root level elements may have a long table of contents.  When the TOC is activated (see above), this toggle becomes available.  Wrapping the TOC will cause it to be displayed in a two column table, with the first half of the TOC in the left cell and the second half in the right.

Clear Copy Buffer

This option becomes available when an element, or generational lineage, is copied.  If the buffer is currently empty, this option is nowhere to be found.  There are advantages in leaving it empty.  It offers a slightly less “noisy” authoring mode (the paste buttons all go away), and reduces the chance of a page error.  For example, if the author has copied a damaged parent-child relationship or something interesting happens which might affect the buffer.  

One such interesting case is that an element in the buffer (the buffer, remember, points dynamically back to each source table: resource, staff person, etc.) is deleted. Buffers are affected by this procedure.  Elements in buffers, as well as on pages, reference keys in their host tables.  If the key is lost, then the element is converted – behind the scenes – both on all affected pages as well as in all user copy-buffers to a “text label” type element.  The source element’s title, URL, and description (if any) are inserted into the corresponding text label fields.  When a Manager deletes such a component, there is the capability to add a message why the element was deleted.  This message is automatically concatenated to all occurrences on pages where it once existed – as well as in all instances of user copy buffers.  So this procedure shouldn’t cause any problems, but it’s usually better safe than sorry.  Thus, the recommendation that buffers be cleared after a copy/paste procedure is completed.

This is a particularly complex set of logic, approaching “rocket science” proportions.  But it can be avoided if (a) People avoid deleting things that are currently used on CLPS pages (instead, they first instruct Authors to remove such items beforehand) and (b) they encourage people to leave their copy buffers empty.  For resources particularly, at the point of deletion there is the option to check the Resource Detail page (also available on the Author console as a resource drilldown (the user must supply the resource ID) which will explain system demographics for the affected resource.  Here they may be removed from their occurrences in CLPS prior to their deletion from the base resource table.

Activate Up Anchors / [Up] anchor text / Save [Up] Text

For pages with especially long chains of siblings before additional root uncles & aunts are encountered, it may be useful to automatically generate anchors which refer back to the top of the page.  The text up the “up anchor” may be customized (and the “Save [Up] Text” button must be clicked.

Apply Style

Styles affect page appearance with a header, footer, and cascading stylesheet.  Styles are configured in the Manager Functions menu where they must reference actual files in the supplied directories.  The CSS file must have span classes S1, S2, S3, S4, and S5 which are explained further in this section and more fully in general in the LibData Customization document.  The style should be chosen, and then the “Apply Style” button must be clicked.

Page Font Format

Numbers here refer to the currently selected style, and the special S1, S2, S3, S4, and S5 span classes which must be present in it.  Note that the libdata.css stylesheet (the default) has a basic set of them, but new styles can have their own variants.  The Page Font Format option, in general, allows an author to select a level of elements and apply a particular style en masse, rather than clicking each individually.  This will be explained after reading further below.

	Level
This refers to the generational level of the elements for which the style is to be applied.  Root-level elements are 0.  Their children are 1, grandchildren 2, and so on.

	Style
The previously mentioned special span classes in the selected style sheet (libdata.css is default) can be cycled through here.  Refer to the LibData Customization document for a full discussion of how they may be configured.  Unlike a fully-robust word processing system, we have not implemented individual toggling of font size, italics, bold, underline, face, etc.  Rather, these are bundled in up to 5 variations (in addition to the BODY default style).  So styles 1-5 here should reflect 5 bundles of text characteristics.  Our other interest in doing this was to purposely reduce the font variations possible on a page, since numerous text changes on web pages quickly produce a cluttered rendering.

	Apply Format
Once a particular level of page elements and style type is selected, this button may be clicked to apply it en masse.  This is a quick way of changing the appearance of generational siblings by issuing a single command.
Assign Page Staff

This option causes a new window to appear which handles page authorizations.  The window persists until it is closed, or some other command (outside of the window) is performed.  (This is not an annoying javascript pop-up, but rather an integral part of the authoring mode.) 

	Reassign Coordinator
Page creators are the default coordinators.  It’s possible to for authors to remove themselves from the position of coordinator.  However, if they do not first name themselves as a co-maintainer, they are now locked out of their own page.  Managers can safely name a new coordinator from someone else in their Library Unit (assuming they are Unit Lead).  DBA’s can reassign coordinators willy-nilly and still have access to the page.

	Add/Remove Maintainers
Maintainers can be added and removed as required.  Once added to a page, they have full access over all page functionality, including the ability to usurp a position as coordinator or delete the page entirely.

	Close This Window
This option closes the assign page staff window.  It will close automatically if some command is conducted outside the window.

Inline Element & Icon Explanations

Page Title

The title of the page may be changed here.  Don’t include HTML tags in the title field.  Compare this field with CourseLib titles.  CourseLib pages use the title field to store the name of the course.  But the full title of any CourseLib page is a concatenation of the following (see 5.3 CourseLib Authoring for additional comments):

{course subject – required to publish} {course number} {course title} {course section}

Page Header

(Available only for PageScribe pages).  This field may contain any sort of text or HTML.  In fact, it’s possible to build a page with no page elements at all – and just display the contents of this field.

Green “Plus” Icon

This is the add-an-element symbol.  As discussed in various sections above, there are parent-child relationships at work.  The add icon is available only in legal positions.
The sorts of elements which may be added include the following:  Resource, Location, Staffperson, Service, Free text wrapped with an optional URL, a link to an RQS or CLPS page, or the en masse harvesting (in alphabetical order) of all resources on the selected RQS page.

Options available each of these categories are sometimes defined only by a Manager or DBA (for example, services or library/locations, or staff).  Or they may be the result of the work of Authors (RQS pages, resources).

Note that newly added elements maintain the title, URL, and description of their source or base table.  Library Location has special functionality.  If an URL was supplied to the base table to indicate a map or hours web page,  special bulleted links appear after the Location description (if present).

Free text labels are interesting in that they may contain HTML in both their title and description fields.  It’s even possible to use IMG SRC to reference an image located elsewhere to incorporate images within PageScribe pages.  Note that there is currently no facility to upload multimedia directly into LibData.  Rather, the model here is that a multimedia library should be maintained by someone with an interactive unix account and expertise with permissions, naming conventions, file size maintenance, etc.  So with a little coordination between an Author and a media library and web designer, it’s possible to produce some fairly graphically rich PageScribe/CourseLib pages (sound files can be referenced in similar ways).  We’ve also dumped page source of entire flat HTML page sources into free text description fields (up to 64K limit) to essentially render a page within a single PageScribe element.

Yellow Box Icon

This is the edit icon.  The current element, page title, or CourseLib course-related field may be edited with this command.

If the edit command involves a page element, it may be edited for a unique description.  The initial description, as with RQS, is the description (hopefully a default description was supplied) from its source table.  If the user wants to make changes to it, the text may be edited and the changes Saved.  Failing to click “Save” will result in loss of changes.  So descriptions for elements have one of two statuses: default/dynamic or custom/static.  Changing to a custom description means that changes to the record in the base table will no longer filter down (except element title and URL if any).  It’s possible to revert back from a customized description to the default description by deleting the entire description (including all trailing spaces, carriage returns, etc.) and saving the changes.

If, for whatever reason, a page author wants neither the default description nor a custom description – to have no description at all – we recommend saving a single white-space as a sort of “hidden” custom description to override the displaying of the item’s default description (but this is a rarely used scenario and we’ve never encountered such a need).

Note that text-type elements have additional fields which may be edited: label (title), and an optional URL to wrap around the label.  The description of free text/label fields is of course always static/custom since there is no source table involved.  They are part of the element itself.

Note that deleting a source record in the resource, service, location or staff tables results in behind-the-scenes conversion from all instances on all CLPS pages from dynamic to static/text type fields.  This is a fairly destructive process, so we recommend that dependent CLPS page elements be authored-out before a deletion occurs (as discussed earlier).

The same applies to the procedure of deleting a page itself.  Since LibData 2.10, PageScribe and CourseLib pages may be added as elements to other pages.  So to preserve parent-child relationships, any references to these soon-to-be-deleted pages will also be converted from dynamic lookup-ups for title/URL to non-linkable static/text elements.  As with the deleting of resources, services, locations, or staff persons, the Author is given the opportunity to supply a reason for deletion.  This reason will be appended to any descriptions associated with the page when it occurs as an element.

Red Box Icon

This is the delete element command.  Not to be confused with deleting from the source table, this merely deletes the currently-selected element and makes necessary adjustments (if any) to descendants.  Note that deleting can work one of two ways if descendants are present.  Two options are given in such cases: descendants may be deleted recursively along with the selected parent, or they may be “promoted” as parents.  This has a cascade effect along the lineage, promoting each generation by one level.

Copy (Page/Page) Icon

Elements may be copied individually or, if children are present, the entire lineage as a group may be copied.  Each user has a buffer unique to them, and it remains even after the user has logged out.  In fact, it’ll remain into perpetuity until the user account itself is deleted.  Copying an element(s) causes the “clear copy buffer” button to become available in the overall page commands table, and places a paste icon (see below) next to any legal add position.

Programmer’s Note:
Recall discussions elsewhere in this document about the deleting of source records and how this affects paste buffers (for example 5.2 PageScribe Authoring: Clear Copy Buffers).  So it’s probably good practice at this point to use this function only when it warrants, and not hold buffers into perpetuity.  Although we’re aware of no bugs with the conversion of relational to text type elements on the fly in user copy buffers should a source record become deleted, it might be safer had we implemented automatic deletion all affected user buffers entirely.  That is, no nifty conversion from relational to static on the fly.  But we’ve went the “extra mile” here and hope that we haven’t run out of gas in the process...

Paste (Page/Clipboard) Icon

If one or more elements are currently in the user’s copy buffer, the paste icon becomes available wherever a green add icon is located.  Paste will insert all copied elements at the selected position, and can be done repeatedly.  If there are descendants, they fall into relative place.

Style [X] [1] [2] [3] [4] [5]

This corresponds to the Page Font Format detailed in Overall Page Commands above.  Rather than setting elements of a particular generation en masse, they may also be tweaked individually with this method.

The numbers 1-5 correspond with underlying style classes S1, S2, S3, S4, and S5 that a Manager has developed (according to suggestions in the LibData Customization document) in the currently selected page style.  So there are really two meanings of “styles.”  The page style itself, which encompasses a header, footer, and CSS.  And the particular style class (S1-5) which should be applied to a particular element.  Note that “x” denotes no style.  The currently selected style will be boldened to set it apart from the others.

Up Arrow / Down Arrow

Elements may be moved up or down to swap places with a peer sibling.  This has the effect of moving all descendants (if any) along with the element moved.  These arrows are available only where such moves are legal.

5.3	CourseLib

Relationship to PageScribe
CourseLib relies on the same editing engine used by PageScribe, so all of the functionality in 5.2 PageScribe above apply here.  The subtleties with regard to Publishing CourseLib pages (they then appear on the public side CourseLib interface) and Page Titles of CourseLib pages have been discussed above.  As a reminder with regard to title, CourseLib titles are the title of the course (e.g. Introduction to Biology).  The full title is concatenated in a back-end field to store course department (required for publishing the CourseLib page), course number (if supplied), course title (required), and course section (if supplied).

Additional Fields
CourseLib pages, in authoring mode, have additional fields (those previously mentioned) plus slots for introductory comments, headers, etc.  These are all optional.  HTML tags may be wrapped within text-type fields.

Adding Personnel
Requiring further explanation here is the Add Personnel feature.  This is not to be confused with page staff (those who may have the ability to edit/delete this page), but rather instructor personnel associated with the CourseLib page.

A title (e.g. professor, lecturer, etc.) may be chosen.  Refer to 6.0 Manager Functions Staff Title for further explanation of this field.  Then, it is possible to select either a LibData staff person (to use here as a course instructor), or a faculty person.  Both of these pick-lists are maintained by Managers.

Another possibility is the capability to add faculty and TA’s on the fly (we’ve thought of everything, haven’t we!).  It’s possible for a CourseLib author to create a new faculty person with this method.  Note, however, that Authors may not edit or delete from the faculty table.  So if an Author makes a typo here, it must be cleaned up by a Manager or DBA.  This limitation was programmed deliberately.  Once the firstname/lastname/directory account/email have been filled out, the CourseLib author must select Faculty or TA/Other (default selection is Faculty).  Faculty entries are indexed in the faculty table and may be reused.  TA’s are expendable.  Note that they may still be searched by name substring from the CLPS administrative search screen – but there is no controlled list or vocabulary present for them and they may not be reused by LibData.  So if a lecturer is likely to teach more than one course, they may better be placed in the Faculty table at this point of creation.

6.0	Manager Functions

As briefly discussed under 2.0 System Accounts, Managers have an additional link available at the bottom of the Author console which will allow them to enter the Manager Functions screen.  This is a collection of setup and mapping tables which provide a controlled vocabulary and maintain relationships between various sorts of data.

Keep in mind that this is a fully relational database system.  It would be worthwhile for managers to glance at the LibData E-R diagram, which graphically illustrates the connections between tables.  There are many dependencies between tables, and LibData can maintain the technical side of relationships.  But maintaining a meaningful installation requires careful human attention.

IMPORTANT: Many tables have an initial “(N/A)” row in them.  This is important, and should not be deleted.  This is sort of the catch-all row to handle non-assigned situations.  Its underlying primary key ID is always #1 and the system is sensitive to this.  The staff table, in addition, has a special slot (#2) for the System Administrator.  Occasionally there may also be an “All” category.  Generally these should be left alone and in most cases are not even displayed for editing purposes.  But anyone going into the mySQL tables directly may see these entries.  As a rule of thumb, N/A, All, or System Administrator (in the staff table) should not be deleted.  If they should become deleted, bugs might crop up and someone would probably have to go into mySQL directly to manually INSERT a row in the #1 primary key slot for the affected table again.  Generally the LibData Manager interface will not allow these rows to be deleted, so this information pertains to anyone going into the “back end”.

General comments on the interface – it’s designed to be strictly functional, no work to jazz it up.  Clicking “New” brings the Manager directly to the appropriate form to create a new entry for that type of record.  Most records have an enforced uniqueness rule on the “title” or label of the entity, so this workflow shouldn’t be used if there’s a possibility that the row already exists in the table – it’ll result in a failure message.  The better workflow would be to click the corresponding “Search” button.  Note that an asterisk “*” will display all rows in the table, and the desired row may then be selected with its adjacent radio button.  If the table is quite large, it’s better to search for substrings.  For example, entering “ology” in the subject field would bring up a quick list of Anthropology, Biology, Geology, Zoology, etc. if these were present in the underlying table.  This strategy can be employed against all of the Manager setup tables with a search/limit capability.

Some forms, when saved, then result in additional forms becoming available.  Since this is HTML, remember that forms cannot be imbedded within forms – so a screen with multiple forms might present some confusion for people.  Take the resource form as an example.  When a resource is saved, three additional forms become available: the assigning of a location/library, features, or master subjects.  If a user has written an extensive annotation on the resource form, failed to save it, and then decides to assign a new feature, s/he will lose any unsaved changed in the resource form as the HTML is redrawn from the back-end database.  Some user training is essential here to avoid this.

Assignment-type forms have a “Available” selections box on the left and a “Selected” set on the right, with left and right arrows under both of them.  This is fairly intuitive and standard.  In most cases, multiple selections are possible with the control and shift keys.  The boxes generally contain mutually exclusive sets of data.

A note on nomenclature to clear up confusion: we’ve gone through some iterations with labels, and not everything is cleaned up – Information Type or Subject may also be referred to as “Base Information Type” or “Base Subject” respectively.  General Information Type and General Subject may also be referred to as “Master Information Type” or “Master Subject” respectively.

Information Type

Also referred to as a “base information type” on the Resource form and in other places.  This would be equivalent to the species in a Linnean classification schema of Homo sapiens.  It’s the more specific of the two tiers of classification.  We initially experimented with three (or possibly unlimited) layers but it became a usability and management issue.  How many layers are required to strike various balances?  We found that two were adequate for our purposes.  Information Types are associated with a General (Master) Information Type and a General (Master) Subject.

It’s important to build the associations, since they create the information hierarchy obeyed by RQS pages.  Resources should be assigned (on the resource-entry form) to a base information type so that they become “smart” and float exactly to this default position on the two-tier hierarchy on RQS pages when they are added to them.  Note that the General Information Type of Resources is inferred by the system behind-the-scenes by examining the resource’s base information type and then, in turn, hunting for its general information type.  So properly assigning resources to an information type, and building the associations are essential and reduce work in the long run.

General Information Type

Information types are associated with exactly one General (Master) Information Type.  This is the genus portion of the information hierarchical consideration.

Subject

These correspond to RQS subject pages.  Note that subjects can be assigned a primary location and description – these are both used by RQS to draw public side pages.  Once the subject has been saved, additional forms become available.

Subjects may be assigned to one or more General (Master) Subjects.  Note that where base Information Types have only a single General Information Type, Subjects can be mapped to multiple Master Subjects.

Secondary locations are then also possible to assign. Note also that the locations/libraries for secondary status (also appearing on RQS public side pages) includes the primary location (if any) as well.  So be careful not to redundantly select a location for both primary and secondary.

Staff may be assigned to edit/maintain the RQS page here.  Note that anyone authorized to edit a subject may remove themselves or add other people to it.

Mapping to CIP codes requires some explanation – at the University of Minnesota we’re experimenting with a portal component such that an incoming course subject (for example ANTH) or its equivalent CIP code can be mapped to an RQS subject.  We then have a mechanism to push a simple XML-wrapped set of RQS subjects with URL’s back to the portal.  Thus, a student logging into some other campus/enterprise application might be “pushed” appropriate RQS pages based on courses s/he is registered for.   Since this is unique to our institution it is not part of the LibData open source release.  But the basic concept involves simple “listening” and “sending” PHP functions.  A portal-related page accepts an URL query string parameter for CIP or course subject, and outputs in XML the mapping results.  These might be parsed by the portal the user is logged into for presentation.  This is still in development, but much of the infrastructure has been developed.  So the cross-talk mapping which this functionality relies on may be done here.

General Subject

The very broad research areas which may contain one or more base subjects within.

Location

This may be a library, archival unit, etc.  As mentioned in the CLPS authoring section of this document, note that the location’s map and hours URL (if supplied) will appear as special bulleted links following the location’s description on CLPS pages.

Feature

This is a generic catch-all category for things like Free, Restricted, Full Text, etc.  Note that it includes the ability to reference an icon and create some HTML ALT text.  When an RQS page is rendered on the public side containing resources with assigned features, the appropriate icon(s) are displayed (with underlying ALT text) alongside the resource title.

Service

Library Services, once saved in LibData, have two additional forms.  They may be mapped to location(s) (see discussion above) and they may be associated to a Service Type (see below).  If your Library has a large array of services, they may be categorized (Reference, Borrowing, ILL, etc.).  This allows them to be limited by other applications designed to extract them, outside of LibData.  Also take note that Services added as elements to a page in the CLPS environment may be limited for easier selection by service type.  Again, this feature is probably most useful to large institutions.

Service Type

See discussion of Services above.   This allows specific services to be grouped together into clusters based on business/functional or some other similarity.

Vendor

Resources may be associated with a vendor/provider.  This is useful for both the administrative and public sides of LibData.  The Advanced Search page for resources allows limiting by vendor, which can provide for a useful management tool.

Vendors occasionally experience technical downtimes, and this may be indicated on the vendor form within LibData by clicking the appropriate vendor status: Up, Down, or Alert.  Down and Alert both allow for messages in the Down/Alert box to be displayed alongside all associated resource titles on RQS and CL/PS pages.  The message is accompanied by a small graphic supplied with LibData to bring attention to the user that the link may be experiencing problems.

Note also that resources may be individually flagged as Up, Down, or Alert, with an accompanying resource-specific Down/Alert message.  This allows for circumstances in which some vendor resources are available, and others are not.  If a resource is flagged Down or Alert at both the resource and vendor levels, the vendor message will take precedence.

PageScribe Style

This is discussed at length in the LibData Customization document.  Of special interest here is that LibData currently does no error-checking on the specified files for header/footer/css.  They need to reside in the specified location, and be set with appropriate file permissions.  The creation and design considerations are discussed in the Customization document.  Libdata.css, part of LibData standard, could be used as a template for cloning purposes.  The only requirement for these files is that the CSS must contain special S1, S2, S3, S4, and S5 classes so that element-level style specifications applied in the CLPS authoring environment have corresponding SPAN classes in the supplied CSS.  Beyond this, anything may be customized in the CSS file.

Campus

Used when creating CourseLib pages.

Term

Academic term.  Also used when creating CourseLib pages.

Course Subjects

The list of subjects, typically accompanied with abbreviation by most all academic institutions.  They may  be assigned to a specific campus as well.  CIP code is optional and not currently used by LibData.  However, refer to the discussion under Subjects in this section for how a mapping between Course Subjects and RQS subjects might facilitate some interesting portal functionality.

Faculty

These are used on CourseLib pages and may be assigned/removed from those pages as desired.

Staff Title

A list of titles, used by both faculty and staff.  This is particularly useful when plopping faculty to CourseLib pages.  A title (professor, associate professor, assistant professor, lecturer, etc.) can be associated with the selected faculty person.  Note that staff titles in the staff table are not used in the public interface.  Scenario: a librarian also happens to be a tenured faculty member.  S/he is going to be an instructor on a CourseLib page.  When a LibData staffperson is added as an instructor for a CourseLib page, the title of the staff person as it appears in the Manager Functions staff table is not used.  Rather, it may be selected anew here.  This was allowed since many of us wear multiple hats.  Refer to section 5.3 on CourseLib authoring for this functionality.

Library Units

These are work units with a unit lead, who should have either the Manager or DBA access level in LibData.  Once the Library Unit is saved, an additional form pops up which allows the selection/removal of staff assigned to that unit.  Note that any manager may make changes to any other unit.  (This requires a collegial level of trust, or some additional security-related programming to rectify.)

Staff

	Manage Staff
This option brings up a tabular list of all staff currently part of the LibData system, access, whether they have a password assigned, last date and IP address of login, etc.  Note that once a new staff person has been assigned, several additional forms are available.

The setting and purging of passwords.

The assignment/removal of that staffperson to library units.  Note that this function is the same (but from a staff-centric perspective) to the assignment form under Library Units above.  From that perspective, a given library unit may add/drop staff members.  From this perspective a given staff person may be added/dropped from units.  Staff may also be assigned various subjects here.  Note, also, that the Subject table has the ability to add/drop staff from it, affecting staff as well.

	RQS Assignments
This is a handy Manager-level tool which displays all staff<->subject assignments for managing RQS pages.  Staff appear on the left, subjects on the right.  A “public” flag is either Y or N, depending on whether the subject in question has been published and it publicly available on the patron RQS interfaces.

When a staffperson (left-most column in this table) is “clicked”, the edit-staff form for that person is brought up.  From there it’s possible to add/subtract assigned subjects.  On Or, when a subject (right-most column) is clicked, the subject-edit form is brought up.  From there, staff may be add/dropped from that subject.  So there are numerous ways to perform similar tasks, and they make sense depending on what the manager is doing (working on a particular subject vs. on a particular staffperson).

7.0	DBA Tools

RQS Subject <-> CIP Code Crosswalk

This tool allows DBA’s to conveniently map any RQS subject to academic course subjects.  As was discussed under 6.0 Manager Functions – Subject, there is the capability to map RQS subjects against academic course subjects (or departments).  There is currently no public application with LibData Rel. OS 1.0 that takes advantage of this mapping, but such things would not be difficult to build should the need arise.

One possibility is to simply limit your entry of RQS subjects to mirror 1:1 the academic environment, then no mapping exercise will ever be necessary.  But we’ve found that it’s useful to be able to create new library subjects which either are cross-disciplinary, more timely than the ability of the University to re-organize its academic departments, or subjects which really have no corollary with a particular department.  Thus, this tool is available.  Taking advantage of it rests with each institution’s unique situation.

Resources Lacking Default Information Types

This screen allows for display of all resources which have no assigned default base information type.  These resources will not “float” to their proper place when added to RQS pages, and will always need to be moved manually out of the (N/A) category into something that makes sense.

LibData System Status

A short assembly of queries to report on the current status of the system: number of unique staff who’ve logged in today, number of cataloged resources, CLPS pages, etc.  Any additional status queries developed by a database programmer might be added and displayed to LibData DBA’s here.

CourseLib Debugger

Select the desired CourseLib page and run several integrity tests on it.  If a page begins to behave poorly, it’s most likely an internal error with the parent-child relationships.  This debugger will hopefully aid in making that determination.  Should an error(s) be found, there are intelligent fix options available.

Note that while LibData is tightly normalized, some problems can occur if two users are working on the same page – we have no concurrency checking!  Thus, the best way to avoid this problem is to distribute authoring assignments carefully.  Should a page become damaged, undamaged portions may be copied out and pasted to a new page.  Another possibility is to rebuild the page from scratch.  Sometimes an error may be fixed by cloning the entire page – the new page is rebuilt such that element orders and parent-child references are re-calculated.  (However, errors shouldn’t be very common.  We have gone six months in a large Big-10 university library environment and found only a single error.)

If the debugger locates an error, some information about the nature of the problem will be displayed, and three fix options will become available (these options are not offered if no errors are found).  They range from least to most destructive to the page:

(1)	Attach orphaned elements to most likely parent.  This method will hunt out the element which is most appropriate to be a parent.  For example, an earlier occurring element with an indent/generation level exactly one less.
(2)	Delete orphaned elements and their children.  Simply remove the problematic element and its lineage.
(3)	Purge all parent-child relationships, and move all elements to root-level position.  This method is most destructive, but almost guaranteed to fix a broken page.  It destroys page hierarchy, but preserves the selection of elements.

After whichever method is chosen, the page elements are both adjusted for both order and parent-child cohesion.  The page fix mechanism will suggest that the page debugger be re-run for a final check.  If errors are still found, the same fix method should be attempted again – or perhaps a more severe method (#2 or #3) might be employed.

In general, errors are very rare and we’ve been able to fix them all with method #1.  We’re still working on a page authoring concurrency/locking mechanism.  But since errors are rare and this fix tool is robust, it isn’t a high priority item.

PageScribe Debugger

Same as above, but the pick list produces PageScribe pages only.

8.0	Statistics

Levels of Statistics & Trade-offs
There are two main methods at collecting statistics in LibData.  Every time a CLPS page is loaded, an entry is logged in the libstats table.  Every time an RQS subject page is loaded, an entry is logged for it as well.  With CLPS we’ve gone a step further and implemented an exit counter, to get a feel for resource utilization down to the element level on CLPS pages.

Unfortunately, this has the detrimental side-effect of hiding URLs when the user passes his/her mouse cursor over a link.  Rather than seeing the resource’s own URL, the link.phtml file is referenced – and this takes the element and page ID are as incoming parameters.  These allow the LibData statistics module to collect link usage.  LibData then redirects the patron’s browser to the actual resource URL.  The undesirable side-effect may be easily stripped out by a programmer familiar with PHP – but the trade-off is that element-level statistics are no longer available.

Since HTML is a stateless protocol, there is no way to determine where a user goes once a web page is loaded into his/her browser – unless is “checks back in” with the server.

A word of general caution
The statistics tables were purposely stored into a separate database (libstats) because they grow at unpredictable rates.  And performance may become an issue on the dynamic “roll up” screen display all pages and element utilization per page.  If this happens, a number of options are available:

(1)	The statistics tables should be purged on a regular basis (this requires someone familiar with SQL to enter the libstats database and DELETE FROM the three statistics tables there).

(2)	Some programming modifications might be done to the statistics “roll up” page which displays all element utilization – i.e. display only use statistics for a particular page.  First require users to select a page, then show only its rollup, rather than an entire system-wide rollup.  This will substantially cut down on query load.

(3)	Don’t do anything at all.  Recognize that this is a computational intensive process.  Simply print out statistics in a static format on a scheduled basis.

Relational Comments
Elements in the statistics tables are still tied, relationally, to their source records.  If Google, for example, is a resource on a CLPS page and is deleted by an Author of that page, its statistics are likewise deleted.  So this table currently maintains no historical statistics usage.  This presents a few problems and, like many other things, we’re working on various solutions.

Probably the most desirable solution is to simply not write statistics out to a table at all, but rather a log file – and build an application that’ll analyze the logs.   This requires convincing a unix administrator that it’s not a security risk to grant PHP the ability to interact at this level with the file system...

9.0	Patron Interfaces

The following public interface pages/modes are currently enabled with this release of LibData.  In-house pages may be easily developed with basic SQL queries.  For example, a page to display, in tabular format, all libraries and their telephone numbers is trivial – so the number of patron applications that LibData might drive is enormous, since the data set is rich and (if populated as such) can be highly relational and associative.

RQS Subject Selection Page (subjects.phtml)

Users select from the combo-box which RQS subject page they’d like to view, or limit the box to subjects beginning with a particular letter A through Z.

RQS Subject Page (rqs.phtml)

The RQS page itself.  This is the default page: for screen display, and all resources associated with this particular subject.  Note that there are 4 permutations possible, based on values of incoming URL parameters “core” and “pf”.

screen & all resources		Default rendering.
screen & core only	Display only highlighted or “core” resources (refer to 5.1 RQS Authoring).
print-friendly & all resources	This version omits the table of contents and page header
				(which will likely contain institutional graphics, logo, etc.).
print-friendly & core only	The print-friendly version of only highlighted or “core”
				identified resources.

CourseLib Selection Page (courses.phtml)

Shows a pick-list available CourseLib (not PageScribe) pages in the system.  The combo select box may be limited to course titles beginning with a particular letter, substring search for department or title, or controlled lists of course department and professor name.  The user picks from the combo box, limited by search criteria or not, and loads the specified CourseLib page.

Note that there is no pick list of PageScribe pages.  We’ve felt that, unlike CourseLib, they have nothing inherently in common with one another other than the tool that created them.  Thus, we’ve not yet found the need to create a pick list of them.  Such a list would be easy to make, however.

CourseLib / PageScribe Page (page.phtml)

This PHP file loads CourseLib and PageScribe pages, based on an incoming page_id parameter.

CourseLib / PageScribe Print-Friendly Version (page_print.phtml)

Unlike the print-friendly version of RQS (see above), this is not merely toggled with an incoming URL flag.  Differences were significant enough such that it was decided to maintain two separate URL’s at this point in LibData development.  Print-friendly pages of CourseLib and PageScribe display the URL’s of page elements, and e-mail addresses of staff as elements whenever possible.  This way, they may be printed and are still visible on hard copy.

10.0	Conclusion & Credits

LibData is clearly a work in progress, as it has been since 1997 when the first iteration of Research QuickStart and 2000 when the first version of CourseLib were implemented.  It was our desire here to create something highly functional, much more robust and integrated, with a great degree of customizability, and own it in-house.  This project resulted from many hours of brainstorming sessions by members of the LibData Design Committee, and countless liters of coffee by the programmer on the project. 

We hope that by giving it all away (free of charge, but with no warranty or guarantees stated or implied) that it may be used and improved upon by other institutions, as we continue to do so ourselves.

Core LibData design staff at the University of Minnesota:

Paul Bramscher (LibData programmer) brams006@umn.edu
Shane Nackerud (Web Services Coordinator) snackeru@umn.edu
John Butler (Digital Library Development Laboratory Lead) j-butl@umn.edu
Kate McCready (Reference Librarian) mccre008@umn.edu
Jen Tantzen (Interface Designer) tantz003@umn.edu

Additional members of the LibData Design Committee

Laura Dale Bischof 
Tammy Bobrowsky
Andrea Halverson
Laurie Nelsen

11.0	LibData Licensing

LibData is released under GPL (http://www.gnu.org/licenses/gpl.html) licensing terms, which means that LibData or applications built upon it may not be sold or re-released in some closed format.  We hope that other institutions may take our work, learn from it, build upon it, and share efforts with one another.

We encourage institutions which opt to use LibData to acknowledge our work with something like Built with LibData, Powered by LibData, and offer a link to http://www.lib.umn.edu/digilab/.