This section describes two similar, but separate facilities that integrate AccuRev’s configuration management functionality with its issue management (AccuWork) functionality. Both integrations record information about the
Promote transaction in a user-specified AccuWork issue record. One of them uses an issue record’s change package as the point of integration; the other uses a particular field in the issue record as the point of integration.
When a promote command is executed in a user’s workspace (but not in a higher-level dynamic stream), the change-package-level integration records all the promoted versions on the Changes subtab of a user-specified AccuWork issue record.
The change-package-level integration is enabled on a depot-by-depot basis. Open the AccuWork Schema Editor for a particular depot’s issue database, and go to the Change Packages subtab.
Filling in the lower section, “Change Package Triggers”, enables the integration for that particular depot. This section is structured as a set of condition/query pairs. One of the queries will be selected for execution at
promote-time. If the first condition in the left column is satisfied, the first query in the right column will be executed; otherwise the second condition will be evaluated, and if it’s satisfied, the second query will be executed; and so on.
Each clause of a condition performs a test on the Promote destination stream. For example, this condition is satisfied if the user is promoting to either of the streams
possum_mnt or
possum_tst:
The query corresponding to each condition can be any AccuWork query, which selects a set of issue records.
The Change Package Triggers section also specifies the format of each query’s results table — the fields to appear as columns, the column widths, the order of the columns (fields), and the sort order of the rows (records).
If the Promote command is invoked through the AccuRev GUI:
1.
|
One of the AccuWork queries specified in the Change Package Triggers section is executed, selecting a certain set of issue records.
|
Note: If you have implemented support for a third-party issue tracking system (ITS), the Select Issue (Change Package) dialog displays controls that let you choose whether to submit changes against the AccuWork issue number or the third-party ITS key. See “Using Third-Party ITS Keys” in the
AccuRev Technical Notes for more information.
If the promote command is invoked through the AccuRev CLI:
> accurev promote -I 4761 chap01.doc
Validating elements.
Promoting elements.
Promoted element \.\doc\chap01.doc
> accurev promote -I 4761 -g chap01.doc
Validating elements.
Promoting elements.
Promoted element \.\doc\chap01.doc
There is no way to have the promote command automatically handle a “change package merge required” situation. You must either perform a merge on the element to be promoted, or remove the existing change package entry for that element.
Note: the query can select issue record #0, even though it doesn’t exist — for example with this clause:
The integration between configuration management and issue management at the transaction level records the number of each
promote transaction in a particular field of a user-specified issue record.
Note that “client_dispatch_promote” is simply a keyword, not the name of a script file. The integration is implemented by two cooperating routines, one built into the AccuRev client software, one built into the AccuRev server software.
3.
|
The promote command completes its work, propagating the versions to the backing stream.
|
4.
|
The promote transaction number is recorded in the affectedFiles field of the selected issue record. (This change to the issue record is, itself, recorded as a transaction, of kind dispatch.)
|
If the user enters “0” or makes a blank entry, the promote command completes but no change is made to any issue record. This provides a way for the user to bypass the integration.
Over time, the affectedFiles field of a given issue record can accumulate a
SPACE-separated list of
Promote transaction numbers.
•
|
The client-side processing — querying the AccuWork issue database and prompting the user to specify an issue record — is structured as a pre-promote-trig trigger routine built into the AccuRev client software.
|
You enable the integration by setting the pre-promote-trig trigger with the “client_dispatch_promote” keyword, as described above. You don’t need to explicitly set a
server-post-promote-trig trigger script.
In most cases, you’ll want to avoid setting a server-post-promote-trig trigger script, just letting the built-in routines do their work. But suppose that after a
Promote, you want the server machine to perform operations in addition to those defined in the transaction-level integration — for example, updating reference trees and sending email messages. In such cases:
3.
|
Use a mktrig command to make the script the depot’s server-post-promote-trig trigger script.
|
Further customizations of the transaction-level integration are possible. For example, you might want the user to be able to specify several issue records, not just one. Or you might want to link
promote commands in one depot with the AccuWork issue database in another depot. Or you might want to update an issue record field other than
affectedFiles. In such cases, you’ll want to dispense with the built-in “client_dispatch_promote” routines altogether:
1.
|
Start with the sample script client_dispatch_promote_custom.pl (in the examples/dispatch subdirectory), and create your own script for use as a pre-promote-trig script to execute on the client.
|
Both the change-package-level and transaction-level integrations can be enabled for a given depot at the same time. In this case, a user performing a
Promote command in a workspace is prompted to specify an issue record just once, not twice. The prompting for an issue record by the change-package-level integration takes place as usual. That issue record is then updated by both integrations.
Even if both integrations are enabled, a Promote command performed in a dynamic stream (not a workspace) activates the transaction-level integration, not the change-package-level integration.