The DLXS Collection Manager CGI: collmgr
Overview and Contents
This document describes the Collection Manager CGI program (collmgr) delivered with the DLXS middleware. It is used to maintain the metadata databases that allow the DLXS middleware to access information about specific collections and groups of collections implemented through the middleware.
The collection information and groups information databases serve to identify and locate the various modules, objects, and search restrictions that are used by the class middleware to serve each collection available in the various classes. For more information about the databases themselves, click here.
collmgr is a CGI program whose main function is to manage collection and group information. This information is that which was kept in the groups and colldb tab-delimited text files prior to the CDROM #8 release of DLXS. This CGI program allows you to maintain this information in either a CSV database or a MySQL database.
For information on the individual fields, please see the help file used by the Collection Manager (collmgr)
IMPORTANT: To learn about the databases and their structure and for an explanation of how different user IDs affect which rows of data are retrieved from the databases see Interaction between database rows, users, DLXS Middleware and collmgr.
In the following explanations, certain terms are used that need some explanation.
- user ID
- The user ID is the key in the database (either collection or groups database) that determines which row of metadata information in the database will be used for a particular collection or group of collections.
- The term release refers to the database rows that have been released by individual developers for testing by a larger audience. When testing is complete, these are the rows that will be moved into production. These rows in the databases are keyed by the user ID dlxsadm. At DLPS, these are rows that are seen by the middleware when running in the "release" directory, as opposed to a particular developer's work directory, and when the DLPS_DEV environment variable is set to 1.
- Rows in the databases keyed by this user ID are seen by the middleware in the production environment; that is, when the DLPS_DEV envrionment variable is set to 0 or not defined.
- This environment variable is set by an authorization system when running the collmgr. It determines what permissions a user has when managing the databases. For example, if the authorization system allows each user to log in as a unique individual with his or her own user ID (see DLPS development environment), that user may check out rows into their own working environment, or make changes to rows and check them back in. If the user logs in as "dlxsadm", the user may "release" the rows keyed by "dlxsadm" (that is, the "release rows") to production and may also add or delete fields from tables.
Workflow for someone managing a collection with a user ID other than dlxsadm
When you login to manage a collection, you are asked whether you wish to manage collections or groups. Then you are asked to select the class with which you wish to work. A list of working collections will be displayed. These are the collections you have checked out under your user ID.
The first time you run collmgr, this list will be empty. In order to build up the list you can choose to checkout collection. This will display a page where you will be permitted to select one or more collections to checkout. Checking out actually creates a copy of the collection database row keyed as release. The new row is keyed by the user ID of the user requesting the checkout.
Returning to the page that lists your working collections, you will see the collection(s) you have just checked out. You can then view them or edit them as you wish, one at a time.
If at any time you wish to get a more up-to-date version of a collection (see point below regarding aging) from the release pool or to undo some changes you have saved to your copy, just check it out, and the values in your row (i.e., the row for that collection which is keyed by your user ID) will be overwritten with those in the release row.
You can also create a new collection, and then check it in. Checkin places the collection in the release pool (by actually copying the row into a new row with all the same values except for the user ID, now dlxsadm (note: any row with user ID dlxsadm is known as a release row or release collection). If you find that you no longer need a collection in your working list, select remove working collection, and it will be removed from your working list (i.e., the row for that collection which is keyed by your user ID, will be deleted). Note: The release pool is not affected by this function because the release row (keyed by user ID dlxsadm) is not deleted.
Here are some important points to keep in mind when developing collections using collmgr:
- When you create a collection, and give it an id, collmgr will check to make sure this collection id is not used by any collections in any of the classes. If it is, it will post a warning and not allow you create that collection.
- If you checkout a collection and someone else also checks it out, makes changes to it, and then checks it in during the time you have it checked out, you will see - AGED attached to the collection name in the list. This notifies you that the release collection has changed since your checkout. You will not be allowed to check this collection in. You will have to check it out, thereby accepting the changes the other user has made to the release row. Only then can you make the changes you need, and check in those changes.
Managing groups works in much the same way as managing collections. You will be able to create a group, check out groups, delete groups from your working list, and then check in your changes.
However, there is one additional layer of complexity that comes with working with groups: the relationship that exists between groups and collections. Note the following:
- When a user creates a group, s/he also selects the collections that are included in the group. When a user is creating a group, the collections presented include all the collections in release, all the collections the user has checked out, and all the collections that are new (i.e., collections s/he may be developing and that have never been checked in).
- As the user selects collections to associate with the group, collmgr will check out each collection, unless it has already been checked out by the user.
- Also when a group is checked out, all collections associated with that group are automatically checked out (i.e., placed in the user's list of working collections), assuming the collection has not already been checked out.
- This behavior of collmgr guarantees that the working list of collections and the working list of groups that reference these collections are compatible.
- One important scenario that collmgr guards against is the case where a collection has been created, has never been checked in, but has been associated with a group. If the user tries to check in the group, collmgr will display a warning to the user to indicate the situation and will not allow the user to check in the group with this collection selected.
- In order to maintain a consistent relationship between a group and collection, if a collection is removed from the working list it will be removed from all groups that include it.
Workflow for someone managing a collection with user ID dlxsadm
The principal difference when managing collections and groups
when logged in as dlxsadm is that you are editing the
release rows in the database directly. That is, you do not
check out and check in rows. The edits you submit affect the
release rows immediately.
If your DLXS site does not
involve interactions among many collection developers, each
needing their own work space, you may decide that the easiest
approach is just to use the single user ID: dlxsadm to
accomplish all your collection development.
If you delete a
working collection, only the 'release' version is deleted. All
user collection rows are kept and also the production collection
rows. A release to production at this point will overwrite the
production collection row. This differs from the case where, when
logged in as an individual user, if you remove a collection, it is
only removed from that user's set of working rows, not from
release or production. Deleting a group behaves the same as
deleting a collection. The collections in the group are not
A quick glance at the initial
collmgr page will show that when logged in as
dlxsadm you are allowed to manipulate the databases in ways
that individual users cannot. Following is a list of these
Make a Release to Production enables the
administrator to copy the release rows onto the production
rows making the release row changes visible to the
middleware when it is running in an environment without the
DLPS_DEV environment variable set, i.e., when the middleware
is running in a production mode. The release rows are those
that contain all the changes checked in by individual users
or changed directly by dlxsadm. Note that a
"release to production operation" also moves all
groups to production.
Add Fields to Collection Tables enables the
administrator to create new collection fields for one or
more of the middleware classes by entering a field name and
selecting which classes use the field. If all the classes
use the field, it is placed global table (the "Collection"
table). If only a few classes need the field, the field is
placed in tha class specific table(s) for the selected
classes. When entering the field name, the collmgr code
checks if the field already exists for the class selected.
If it does, it will not add the field to the database. The
administrator may optionally supply a default value for the
field and specify whether the field should contain a single
value or a list of values. If the field can contain multiple
values, the user may enter the multiple values in the area
indicated and separate each value with the pipe symbol (|).
Fields are added typically when there is a need for
additional new functionality coded in the middleware.
Delete Fields from Colleciton Tables enables the administrator to remove existing fields for one or more of the middleware classes by selecting a field name. The user will be prompted for the class(es) for which the field is to be deleted, since the same field name may be used by multiple classes. At DLPS this function is primarily to remove obsolete fields.
Add Fields to Group Tables enables the administrator to create new group fields for one or more of the middleware classes by entering a group field name and selecting which classes use the field. The steps for performing this task are the same as those for adding a field to the collection tables.
Delete Fields from Group Tables enables the administrator to remove existing fields for one or more of the middleware classes by selecting a group field name. At DLPS this function is primarily to remove obsolete fields. The steps for performing this task are the same as those for deleting a field from the collection tables.