AccuRev Triggers : Integrations Between AccuRev and AccuWork

Integrations Between AccuRev and AccuWork
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.
Change-Package-Level 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.
Enabling the Integration
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).
Triggering the Integration
Once the integration is enabled for a depot, it is triggered whenever a user performs a promote command in a workspace associated with that depot.
If the Promote command is invoked through the AccuRev GUI:
1.
2.
3.
The user selects one or more of the issue records. There is also a New Issue button, which enables the user to create a new issue record “on the fly”.
4.
5.
If the promote command is invoked through the AccuRev CLI:
1.
Just as with the GUI, one of the AccuWork queries specified in the Change Package Triggers section is executed, selecting a certain set of issue records.
2.
Please enter issue number ?
Users can bypass this prompt by specifying an issue number with the –I option:
> accurev promote -I 4761 chap01.doc
Validating elements.
Promoting elements.
Promoted element \.\doc\chap01.doc
You can specify multiple issue records with the –I option like this:
... -I "4761 4795 5006" ...
Note: attempting to update an existing change package entry might cause a “change package gap” or “change package merge required” situation, either of which cancel the promote command. For example:
Promoting elements.
Change package gap: /doc/chap01.doc
You can handle a change package gap by adding the –g option to the promote command. This combines the new and existing change package entries by “spanning the gap”:
> 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.
For more on “change package gap” and “change package merge required” situations, see Updating Change Package Entries of the AccuRev Concepts Manual.
3.
Assuming the user-specified issue record is one of those selected by the query, the command completes its work, and the promoted versions are recorded in the change package section of the selected issue record.
What happens if the user specifies no issue record or a non-existent issue record, such as 99999 or 0? In both the GUI and CLI cases:
If the user enters “0” (or equivalently, makes a blank or non-numeric entry), AccuRev checks whether issue record #0 is among the issues selected by the query executed in Step 1.
Note: the query can select issue record #0, even though it doesn’t exist — for example with this clause:
issueNum equal to 0
If the query does select issue record #0, the user’s command completes but no information is sent to the issue database. This provides a way for the user to bypass the integration when performing the promote command.
Transaction-Level Integration
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.
Enabling the Integration
The transaction-level integration is enabled on a depot-by-depot basis, by setting the depot’s pre-promote-trig trigger. For example:
accurev mktrig -p kestrel pre-promote-trig client_dispatch_promote
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.
Triggering the Integration
Once the integration is enabled for a depot, it is activated whenever a user executes the Promote command in any workspace or dynamic stream.
1.
The depot’s default query, as defined on the Queries tab (Issues > Queries), is executed and the results are displayed to the user.
2.
The user selects one of the issue records. Note that if no default query is defined for the depot, the user is prompted to type an issue record number.
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.
Implementation and Customization of the Transaction-Level Integration
When the transaction-level integration is activated, processing takes place on both the AccuRev client machine and the AccuRev server machine:
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.
The server-side processing — updating of the AccuWork issue record — is structured as a server-post-promote-trig trigger routine built into the AccuRev server 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:
1.
Create a script that performs the server-side part of the transaction-level integration, along with the desired additional processing. Start with the sample script server_dispatch_promote_custom.pl, which is located in the examples/dispatch subdirectory of the AccuRev installation directory.
2.
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.
2.
As described above, start with the sample script server_dispatch_promote_custom.pl (in the examples/dispatch subdirectory), and create your own script for use as a server-post-promote-trig script to execute on the server.
If Both Integrations are Enabled
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.

AccuRev, Inc.
Phone: 781-861-8700
Fax: 781-861-8704
support@accurev.com