Working with the Collection Manager

From DLXS Documentation

Current revision

Main Page > Working with DLXS Components > Working with the Collection Manager

[edit] Collection Manager CGI Overview

This section 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 LINK.

collmgr is a CGI program whose main function is to manage collection and group information. This CGI program allows you to maintain this information in a MySQL database.

For information on the individual fields, please see the help file the Collection Manager uses.

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.

[edit] Definitions

To work with the Collection Manager you should be familiar with the following terms:

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.

release

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.

production

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.

REMOTE_USER

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.

[edit] Workflow for someone managing a collection with a user ID other than dlxsadm

[edit] Managing collections

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.

[edit] Managing Groups

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.

[edit] 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 affected, however.

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 additional priviledges.

• 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.

Top