Configuring and Using Third-Party ITS Keys

If you use AccuRev with a third-party issue tracking system (whether through an integration, or just in parallel), you might find it convenient to use the third-party issue numbers (“keys”) along with or instead of AccuWork issue numbers.

To do this, you need to:

•	Customize your AccuRev schema to define a new third-party issue field (or make use of an existing one).

•	Specify a -3 switch with CLI commands that make use of third-party tracking numbers (for example, promote -3 -I <3rd_party_ITS_key> <element_name>).

Modifying the schema

To make use of third-party ITS keys, you must first modify the AccuRev schema. You can do this by either manually editing the schema.xml file, or by using the Schema Editor in the AccuRev GUI (see the “Schema Editor” section of the AccuRev On-Line Help Guide).

Using the Schema Editor

If you do not wish to edit schema.xml directly, you can use the Schema Editor in the AccuRev GUI. Identify an existing key field that can be used, or define a new one using the Add button. Then assign this key field using the 3pty ITS Key dropdown menu.

Note that some AccuRev schemas (like the schemas delivered with AccuSync) already have a third-party key defined, such as “jirakey”. If this is the third-party ITS key that you need to use, you just need to ensure that it is assigned to the 3pty ITS Key dropdown menu as described above, and that it is positioned on the Issue form as described below.

Next go to the Layout tab and position this field in the Issue form (or confirm that it is already there). To position it, select the entry in the Fields column, and then click where you want it to appear in the left side of the tab (for example, in the Header section).

Save your changes and exit the Schema Editor. Now when you display the AccuWork Issue form, the third-party ITS key field will be displayed.

Editing schema.xml

You can also directly edit the schema XML files (schema.xml and layout.xml). In a text editor, open the schema.xml file for your depot:

<ac_install>/storage/depots/<depot_name>/dispatch/config/schema.xml

First, determine if you need to define a new field to handle the third-party ITS key. Note that all AccuRev schemas have an entry for AccuWork issue numbers. For example:

<field
name="issueNum"
type="internal"
label="Issue"
reportWidth="10"
fid="1">

Do not use this for third-party ITS keys. Define a new one (or determine if you already have one available in your schema) and make sure that it is specified in the lookupField as described below.

Some AccuRev schemas (such as the schemas delivered with AccuSync) already have a third-party key defined, such as:

<field
name="jiraKey"
type="Text"
label="JIRA Key"
reportWidth="10"
width="10"
fid="3">
</field>

If you need to define a new key, do so using the above key as an example, making sure to assign it an unused fid (field ID) number.

After identifying a key field, or defining a new one, modify the fid value of the lookupField entry to reflect the new key field (the lookupField entry is typically found near the top of schema.xml:

<lookupField fid="1"/>

For example, if you were modifying this entry to use the jiraKey field shown above, you would change the fid value to “3”.

If you will be using this convention in new depots that you create in the future, you should also make this change to the master copy of schema.xml in:

<ac_install>/storage/site_slice/dispatch/config

To position this field on the Issue form (or to confirm that its position is already defined), open layout.xml in a text editor. Use the existing entries in the file as a model for defining the third-party ITS key field.

Using Third-Party ITS Keys in the CLI

Once the schema has been configured as described in the previous section, you use third-party ITS keys with a variety of AccuRev CLI input commands by specifying the new “-3” switch in addition to the traditional “-I” switch (for example “-3 -I US23407”). Note that you can also still use AccuWork issue numbers by using the traditional “-I” switch by itself, but you cannot specify both on the same command line.

Here are the AccuRev commands that accept the -3 switch:

•

cpkadd

•

cpkdepend

•	cpkdescribe

•

cpkremove

•

issuelist

•

merge

•

patch

•

promote

•

purge

•

revert

Here are some examples of using the promote command with the -3 switch:

Promote a file and associate it with an issue using the third-party issue key:

accurev promote -I <3rd_pty_key> -3 <element_name>

Promote a file and associate it with several issues using third-party issue keys:

accurev promote -I "<3rd_pty_key_1> <3rd_pty_key_2> <3rd_pty_key_3>"
-3 <element_name>

You can also use the third-party keys with the -Fx switch for XML. For example, to promote a file using the -Fx switch and associate it with several issues using third-party issue keys:

accurev promote -Fx -l <xml_filename>

where the XML file has the following format:

<issues third_party=”true”>
<id>[3rd_pty_key_1]</id>
<id>[3rd_pty_key_2]</id>
<id>[3rd_pty_key_3]</id>
</issues>

Commands That Return Third Party Issue Numbers

These commands return third-party key information in XML output (specified with the -fx switch):

•

hist

•

cpkdepend

•

xml -l

cpkdepend also returns third-party key information in non-XML format. If you specify -3 to query the dependency, then the values in non-fx will be displayed using third-party values. If specify standard issue numbers, they will be displayed in standard format. If you specify -3 without -fx and an issue does not have a third-party value, an asterick ('*') appears before the issue number.

In the examples below, the third-party values are displayed in bold. "thirdPartyName" is the field name (not the label name) defined in the Schema Editor.

hist example output

<version

path="\.\file.cpp"

eid="3"

virtual="4/2"

real="5/2"

virtualNamedVersion="s25263_proj1_dev/2"

realNamedVersion="ws25263_testuser1/2"

elem_type="text"

dir="no">

<issueNum

thirdPartyName="jiraKey"

thirdPartyValue="J1002">2</issueNum>

</version>

cpkdepend example output

<acResponse>

<issueDependencies>

<issueDependency>

<issues>

<issue

number="2"

thirdPartyName="jiraKey"

thirdPartyValue="J1002"

incomplete="false"/>

</issues>

<dependencies>

<issue

number="1"

thirdPartyName="jiraKey"

thirdPartyValue="J1001"/>

</dependencies>

</issueDependency>

</issueDependencies>

</acResponse>

Using Third-Party Keys in the AccuRev GUI

Once you have enabled the use of third-party issue tracking system (ITS) keys in the AccuWork schema, the Select Issue (Change Package) dialog and the Look Up Issue dialog display additional controls that let you indicate whether you want to use AccuWork issue numbers or third-party ITS keys when specifying issues.

For example, when you bring up the Look Up Issue dialog, if third-party ITS keys are enabled AccuRev displays radio buttons that let you indicate that you want AccuRev to use the third-party key rather than the AccuWork issue number when looking up the issue.

The radio button for the ITS is labeled with whatever text is specified in the Schema Editor for the "Label" field (see Using the Schema Editor).