Interface to the Change Package Facility

AccuWork issue records are used to implement the change package facility. The set of changes in a change package is indicated by a set of “Versions”, listed on the Changes subtab of an issue record, each with a corresponding “Basis Version”:

Each Version / Basis Version pair defines a set of changes to the element: the changes made since the Basis Version was created, up to and including the Version. The change package consists of such Version / Basis Version “patches” for any number of elements.

Various user commands and triggers maintain the contents of a change package: adding new versions and removing existing versions. There are also commands for comparing the contents of a change package to the contents of a stream, enabling you to easily answer the question, “Have all the changes made for Task A been propagated to Stream B?”

The following sections describe the CLI to the change package facility.

Adding Entries to a Change Package

The following XML document requests the adding of two entries to the change package of issue record #433: for the element with element-ID 3, record the series of versions between Basis Version 4/3 and Version 4/6; for the element with element-ID 7, record the series of versions between Basis Version 4/2 and Version 4/9.

<acRequest>
    <cpkadd>
        <user>john</user>
        <depot>etna</depot>
        <stream1>etna_dvt</stream1>
        <issues>
            <issue>
            <issueNum>433</issueNum>
        <elements>
            <element
              id="3"
              real_version="4/6" basis_version="4/3">
             <element
              id="7"
              real_version="4/9" basis_version="4/2">
            </element>
        </elements>
            </issue>
        </issues>
    </cpkadd>
</acRequest>

Removing Entries from a Change Package

The following XML document requests the removal of the change-package entry for the element with element-ID 3 from issue record #433.

<acRequest>
    <cpkremove>
        <user>john</user>
        <depot>etna</depot>
        <stream1>etna_dvt</stream1>
        <issues>
            <issue>
            <issueNum>433</issueNum>
        <elements>
            <element
              id="3"
              real_version="4/6">
            </element>
        </elements>
            </issue>
        </issues>
    </cpkremove>
</acRequest>

Listing the Contents of a Change Package

The following XML document requests the listing of the change packages of issue records #433 and #512.

<acRequest>
    <cpkdescribe>
        <user>john</user>
        <depot>etna</depot>
        <stream1>etna_dvt</stream1>
        <issues>
            <issueNum>433</issueNum>
            <issueNum>512</issueNum>
        </issues>
    </cpkdescribe>
</acRequest>

Note that a <cpkdescribe> query is the only way to retrieve an issue record’s change package data. A <queryIssue> query retrieves all the other fields, but not the change package data.

Listing Transactions that Affected Change Packages

The following XML document requests the listing of certain transactions in the range 488–569, including the numbers of the change packages (issue records) modified by those transactions.

<acRequest>
    <cpkhist>
        <user>john</user>
        <depot>etna</depot>
        <transaction1>569</transaction1>
        <transaction2>488</transaction2>
    </cpkhist>
</acRequest>

The transactions listed include explicit change-package requests (kind=dispatch, operation=cpkadd or cpkremove). Also included are promote transactions that triggered cpkadd operations.

Creating a Relationship between Two Issue Records

The following XML document creates a Duplicate (type=1) relationship between issue records #337 (the parent) and #198 (the child):

<relateIssue issueDB="UserReportedBugs">
    <relationship
        type="1"
        issueNum1="337"
        issueNum2="198">
    </relationship>
</relateIssue>

Removing a Relationship between Two Issue Records

The following XML document removes a Duplicate (type=1) relationship between issue records #337 (the parent) and #198 (the child):

<unrelateIssue issueDB="UserReportedBugs">
    <relationship
        type="1"
        issueNum1="337"
        issueNum2="198">
    </relationship>
</unrelateIssue>

Listing Issue Record Relationships

Following is an XML template for reporting ...

•	the relationships in which a specified issue record is the parent, or

•	the relationships in which a specified issue record is the child, or

•	both of the above

<listRelatedIssues issueDB="depot-name">
    <relationship
        type="type-number"
        issueNum="issue-number"
        relationship="kind">
    </relationship>
</listRelatedIssues>

The placeholders in this template are:

depot-name

The name of the depot in which the issue resides.

type-number

1 (Duplicate)

3 (Sub Task)

4 (Dependency)

5 (Tracking)

issue-number

The integer number of the issue record whose relationships are to be listed.

kind

child, to list the issue records that have issue-number as a child.

parent, to list the issue records that have issue-number as a parent.

all, to combine both the above listings.

Determining Which Change Packages Are Included in a Stream

The following XML document requests a Show Issues command on stream etna_dvt: list the change packages (issue records) whose entire set of changes have been propagated to stream etna_dvt.

<acRequest>
    <issuelist show_active = "false">
        <user>jjp</user>
        <depot>etna</depot>
        <stream1>etna_dvt</stream1>
        <issues>
        </issues>
    </issuelist>
</acRequest>

Changing the attribute to show_active = "true" would restrict the listing to change packages that have at least one version that is currently active in stream etna_dvt. (Removing the attribute would have the same effect, since the “show_active” attribute defaults to “true”.)

The following variant (note the boldface code) restricts the listing to a particular set of active change packages (issue records): in effect, this allows you to pose the question, “Have all the changes in #167 and #332 already been propagated to stream etna_dvt?”.

<acRequest>
    <issuelist>
        <user>jjp</user>
        <depot>etna</depot>
        <stream1>etna_dvt</stream1>
        <issues>
            <issueNum>167</issueNum>
            <issueNum>332</issueNum>
        </issues>
    </issuelist>
</acRequest>

Other attributes for the <issuelist> element include:

•	show="[complete | incomplete]" -- show only complete or incomplete issues from the specified stream.

•	show_unaffiliatedchanges="[true | false]" -- show changes that are not associated with any issue in the specified stream.

Comparing Two Streams in Terms of Change Packages

The following XML document requests a Show Issues Difference command, showing which change packages (issue records) in stream brass_dvt have not had their changes propagated to stream brass_tst.

<acRequest>
    <issuediff>
        <user>john</user>
        <depot>brass</depot>
        <stream1>brass_dvt</stream1>
        <stream2>brass_tst</stream2>
    </issuediff>
</acRequest>

The following variant (note the boldface code) restricts the listing to a particular set of change packages (issue records): in effect, this allows you to pose the question, “Are #167 and #332 among the change packages that have not yet been propagated from stream brass_dvt to stream brass_tst?”.

<acRequest>
    <issuediff>
        <user>john</user>
        <depot>brass</depot>
        <stream1>brass_dvt</stream1>
        <stream2>brass_tst</stream2>
        <issues>
            <issueNum>167</issueNum>
            <issueNum>332</issueNum>
        </issues>
    </issuediff>
</acRequest>

Other attributes for the <issuediff> element include:

•	show="[complete | incomplete]" -- include only complete or incomplete issues from the diffed streams.

•	show_unaffiliatedchanges="[true | false]" -- show changes that are not associated with any issue in either stream.