ST - Internals - Configuration

This describes the current configuration in the package, providing future direction for its improvement.

The /software/rt-math-1 package configuration is currently spread across several places. Someday they will be merged.

Much configuration resides in database tables, and in the code (in configuration specific packages). The general direction for configuration that isn't in a database table is towards using

/software/rt-math-1/data/config/

A disadvantage of that, as with database tables, is that it's not possible to have configuration specific to the various versions (currently "debug", "beta" and "production"). In practice, that only matters when configuration handling changes.

The conventional /software/rt-math-1/config/* barely exist, containing only

/software/rt-math-1/config/share/templates/

The direction has been away from xhier style configuration towards the above. Should the need for the xhier style emerge, the intent is to use Perl as the configuration language, with a program to check the results before applying them to /software/rt-math-1/data/config/.

Table of Contents

Where to Make Changes

The ST package source resides on capo.private in /software/rt-math-1. All configuration changes are made there. Changes are subject to revision control. For configuration that resides in the versioned part of ST (in lib/{debug,beta,production}), changes are made to the debug version, relying upon version updates to handle the other versions.

Access Control

There is a WWW page for easy updates to the ST access control. While the access control model is quite detailed (see the queue_acl table), in practice there are only three possibilities of interest:

Staff Names

Staff names typically appear in

Additions to database tables are handled by a separate program that adds or deletes staff members.

Holidays

See ongoing updates for details about updating the holidays list.

Time Intervals

See ongoing updates for details about updating the list of time intervals in the RunOn Sentence.

Presentation and Planning Categories

Each of the categories has a file in

/software/rt-math-1/data/config/ppcat/

As the .Readme advises, one a change can been made, run

/software/rt-math-1/maintenance/st-install-ppcat

to install the changes.

Email Templates

The templates used when sending email reside in

/software/rt-math-1/config/*/templates/.

although there is currently only a shared version.

They are merged (via `st-install-config`) into /software/rt-math-1/data/config/templates/. A template file can be replaced by a directory containing files named either by an organization (e.g. "CFCF" or "MFCF") or as ".default". Possible names remain to be documented.

They admit to variable substitution for variables of the form %<NAME>% for various <NAMES>. Until they're documented, see /software/rt-math-1/lib/debug/st/support/mail.pm

The Welcome

The "Welcome" pages

https://cs.uwaterloo.ca/cscf/internal/request/Welcome
https://www.math.uwaterloo.ca/mfcf/help/request/Welcome

contain organization specific text, that resides in

/software/rt-math-1/data/config/welcome/{CSCF,MFCF}

See &st::ui::web::display_welcome() and @st::config:args::welcome_msg for implementation details.

Database Access

The names and access control information for the databases that are used are found in

/software/rt-math-1/lib/debug/st/config/databases.pm

access to which is restricted. Currently that's for ST, inventory, and subscription systems. Access to all but ST data is intended to be read-only.

Miscellaneous General Configuration

Perl variable definitions (in the st::config package) are various forms of configuration, almost all of which are very unlikely to change. They currently reside in

/software/rt-math-1/lib/debug/st/config.pm

They will possibly end up in /software/rt-math-1/data/config/ some day. However that would lose the ability to have version specific configuration.

In practice, only the debug version of such configuration (/software/rt-math-1/lib/debug/st/config.pm) is directly updated, with the version updates taking care of the other versions.

There is no clear boundary between "unlikely to change", and not.

Miscellaneous Organization-Specific Configuration

Perl variable definitions (in the st::config::orgs package) are various forms of configuration, almost all of which are very unlikely to change. They currently reside in

/software/rt-math-1/lib/debug/st/config/orgs.pm

They will possibly end up in /software/rt-math-1/data/config/ some day.

They are organization specific to handle, e.g., differences between CSCF and MFCF. Should this ever be used by other organizations (highly unlikely), this would grow.

The only reason that organization specific configuration isn't handled on a per WWW-server basis is that a single WWW server can support multiple hosts. Whether it should be a separate Perl package is debatable.

Database Tables

There are multiple tables that also contain configuration, primarily the "queues", "queue_acl", "owner", and "ownerOrganization" tables. See the schema documentation for details.

Files

/software/rt-math-1/.admin/Maintainer
mail address(es) of the \fIrt-math-1\fP package maintainer.
/software/rt-math-1/config/share/templates/
email templates.
/software/rt-math-1/data/config/templates
the working copy of the above.
/software/rt-math-1/data/config/ppcat/
defines the presentation and planning categories.
/software/rt-math-1/data/config/welcome/{CSCF,MFCF}
the organization specific introduction to the welcome page.
/software/rt-math-1/lib/debug/st/config/orgs.pm
organization specific configuration
/software/rt-math-1/lib/debug/st/config.pm
general configuration
www.cs:/.software/regional/odyssey-3_apache/data/vhosts/cs.uwaterloo.ca/cscf/internal/htaccess/staff-all
access control for attachments

See Also

xhier(7)
description of the xhier software organization.
xhier-package-config(7)
package configuration conventions.
st-install-config(8)
how we apply xhier style configuration