Appendix E dbconfig recipes

The dbconfig file (The dbconfig file) is the heart of any gnats installation. It contains some very powerful machinery, something which this appendix tries to illustrate.

We provide a range of examples that are both intended to be useful in their own right and to serve as starting points or building blocks for your own modifications.

Provide Gnatsweb URL in initial response

Sites that have Gnatsweb installed may wish to modify the response e-mail which is sent to the submitter of a PR so that it includes a URL where the status of the PR can be monitored. In order to allow this, you should first create an entry in gnatsd.user_access which allows viewing of PRs in your database (See The gnatsd.user_access file.)

Next, locate the entry mail-format "initial-response-to-submitter" in the dbconfig file of your database and add the following before the line reading “The individual assigned...” in the body section:

\nYou can follow the status of this report on\n\
http://hostname/cgi-bin/scriptname?\n\
cmd=view&database=dbname&user=username&\n\
password=passwd&pr=%s\n\n\

Substitute hostname, cgi-bin and scriptname as appropriate for the setup of your web server. The part before the ? would typically look something like http://www.example.com/cgi-bin/gnatsweb.pl. Substitute the name of your database for dbname, and the username and password of the user with view rights for username and passwd.

Next, add a Number to the fields list statement inside the body so it reads as follows:

fields { "Category" "Number" "Number" "Responsible"
         "Category" "Responsible" "Synopsis"
         "Arrival-Date" }

State full name of responsible in initial response

The initial e-mail response to the submitter of a PR identifies the responsible person assigned to the PR as follows: “The individual assigned to look at your report is: GNATS username”. Some sites may wish to modify this so that the full name of the responsible person is used instead of the gnats user name.

The full name is contained in the fullname subfield of the user's entry in the responsible file and can be accessed as Responsible[fullname] (see Enumerated field administrative files.)

The change is achieved by editing the dbconfig item mail-format "initial-response-to-submitter" and changing the fields part of the Body from

fields { "Category" "Number" "Responsible"
         "Category" "Responsible" "Synopsis"
         "Arrival-Date" }

to

fields { "Category" "Number" "Responsible[fullname]"
         "Category" "Responsible" "Synopsis"
         "Arrival-Date" }

Append-only Audit-Trail

The Audit-Trail of a PR is by default editable. For some applications, one might want to make the Audit-Trail append-only, so it provides a full and unchangeable case history. Also by default, only certain changes, such as change of state and change of responsible gets recorded in the Audit-Trail. In some cases, it might also be convenient to have a way of inserting comments directly into the Audit-Trail.

The following procedure creates such an append-only Audit-Trail and adds a PR field which makes it possible to register comments in the Audit-Trail.

First, add the keyword read-only to the Audit-Trail field definition in dbconfig.

Then, add the following field definition to dbconfig:

field "Add-To-Audit-Trail" {
   description "Add a log entry to the Audit Trail"
   multitext { default "\n" }
   on-change  {
        add-audit-trail
        audit-trail-format {
        format "**** Comment added by %s on %s ****\n %s\n\n"
        fields { "$EditUserEmailAddr" "$CurrentDate" "$NewValue"
        }
        }
    }
    on-change {
        set-field "Add-To-Audit-Trail" { "\n" }
    }
}

Supporting gnats “release-based” fields

When installing gnats version 3.x, it was possible to choose whether to enable three optional fields: Quarter, Keywords and Date-Required. Default installations had these fields switched off, and installations which had them were called “release-based”.

The default dbconfig shipped with gnats version 4 or newer does not have these fields, so if you are upgrading from an old release-based system, you need to add the following field definitions to your dbconfig file:

field "Quarter" {
    description "What quarter does the PR fall into?"
    text
    query-default inexact-regexp
    textsearch
}

field "Keywords" {
    description "Keywords used to index this PR"
    text
    query-default inexact-regexp
    textsearch
}

field "Date-Required" {
    description "Date that the PR must be fixed by"
    date
}

A side note: Pre-release versions of gnats 4 also had a field named Cases. For those who may need it, here is the field definition of Cases:

field "Cases" {
    text
    query-default inexact-regexp
    textsearch
}