Trackers

Basics:

  • <trackers> node contains a list of <tracker>, then <triggers> and finally <references>

  • Within a <tracker> there is first the structure of the tracker and then the data themselves within <artifacts> node.

  • The tracker structure is made of metadata (like <name>), fields (<formElements>), semantics (<semantics>), Workflow & field dependencies (<rules>, <workflow>, <simple_workflow>), reports (<reports>) and permissions (<permissions>).

  • An <artifact> is made of <changeset>, each <changeset> corresponds to a modification of the artifact. Order matters! the first <changeset> is the artifact creation.

  • A <changeset> is composed of a <comment> (can be in text, html or commonmark format) and a set of <field_change>. Each <field_change> refers to a field referenced in the <formElements> section of <tracker>.

Example of a simple tracker with a few fields

The example below is a simple tracker made of following fields

  • Id (type: artifact id)

  • Submitted by (type: submitted by)

  • Title (type: string, associated to “title” semantic)

  • Dependency (type: artifact link)

  • Description (type: text)

  • 2 structure fields columns (C1 and C2)

  • Product (type: multiselectbox)

  • Status (type: selectbox, associated to “status” semantic)

Some insights to better understand how this works:

  • L73: definition of status semantic uses reference to field F6680, this will automatically refer to the field defined L51. And same applies for values considered as “Open” (<open_values>, L78) that uses references V7678, V7679 and V7680 defined L56-59.

  • L146: the artifact creation set a value to this status field (<field_change field_name=”status”>) and the value (<value format=”id”>7678</value>) refers to V7678 L56.

  1  <?xml version="1.0" encoding="UTF-8"?>
  2  <project>
  3    <services>
  4      <service shortname="plugin_tracker" enabled="true" />
  5      ...
  6    </services>
  7
  8    ...
  9
 10    <trackers use-natures="true">
 11      <tracker id="T239" parent_id="0" instantiate_for_new_projects="1">
 12        <name><![CDATA[Simple Tracker]]></name>
 13        <item_name>simple</item_name>
 14        <description><![CDATA[simple tracker example]]></description>
 15        <color>inca_silver</color>
 16        <cannedResponses/>
 17        <formElements>
 18          <formElement type="aid" ID="F6683" rank="3">
 19            <name>id</name>
 20            <label><![CDATA[Id]]></label>
 21          </formElement>
 22          <formElement type="subby" ID="F6684" rank="4">
 23            <name>submitted_by</name>
 24            <label><![CDATA[Submitted by]]></label>
 25          </formElement>
 26          <formElement type="string" ID="F6677" rank="5">
 27            <name>title</name>
 28            <label><![CDATA[Title]]></label>
 29            <properties size="30"/>
 30          </formElement>
 31          <formElement type="art_link" ID="F6676" rank="6">
 32            <name>depends</name>
 33            <label><![CDATA[Depends]]></label>
 34          </formElement>
 35          <formElement type="text" ID="F6678" rank="11892">
 36            <name>description</name>
 37            <label><![CDATA[Description]]></label>
 38            <properties rows="10" cols="50"/>
 39          </formElement>
 40          <formElement type="column" ID="F6681" rank="11893">
 41            <name>c1</name>
 42            <label><![CDATA[C1]]></label>
 43            <formElements>
 44              <formElement type="msb" ID="F6679" rank="0">
 45                <name>product</name>
 46                <label><![CDATA[Product]]></label>
 47                <properties size="7"/>
 48                <bind type="static" is_rank_alpha="0">
 49                  <items>
 50                    <item ID="V7675" label="UI" is_hidden="0"/>
 51                    <item ID="V7676" label="Database" is_hidden="0"/>
 52                    <item ID="V7677" label="API" is_hidden="0"/>
 53                  </items>
 54                </bind>
 55              </formElement>
 56            </formElements>
 57          </formElement>
 58          <formElement type="column" ID="F6682" rank="11894">
 59            <name>c2</name>
 60            <label><![CDATA[C2]]></label>
 61            <formElements>
 62              <formElement type="sb" ID="F6680" rank="0">
 63                <name>status</name>
 64                <label><![CDATA[Status]]></label>
 65                <bind type="static" is_rank_alpha="0">
 66                  <items>
 67                    <item ID="V7678" label="New" is_hidden="0"/>
 68                    <item ID="V7679" label="Under analysis" is_hidden="0"/>
 69                    <item ID="V7680" label="Under verification" is_hidden="0"/>
 70                    <item ID="V7681" label="Done" is_hidden="0"/>
 71                  </items>
 72                </bind>
 73              </formElement>
 74            </formElements>
 75          </formElement>
 76        </formElements>
 77        <semantics>
 78          <semantic type="title">
 79            <shortname>title</shortname>
 80            <label>Title</label>
 81            <description>Define the title of an artifact</description>
 82            <field REF="F6677"/>
 83          </semantic>
 84          <semantic type="status">
 85            <shortname>status</shortname>
 86            <label>Status</label>
 87            <description>Define the status of an artifact</description>
 88            <field REF="F6680"/>
 89            <open_values>
 90              <open_value REF="V7678"/>
 91              <open_value REF="V7679"/>
 92              <open_value REF="V7680"/>
 93            </open_values>
 94          </semantic>
 95          <semantic type="tooltip"/>
 96          <semantic type="plugin_cardwall_card_fields"/>
 97        </semantics>
 98        <rules>
 99          <date_rules/>
100          <list_rules/>
101        </rules>
102        <reports>
103          <report is_default="0">
104            <name>Default</name>
105            <description>The system default artifact report</description>
106            <criterias>
107              <criteria rank="0">
108                <field REF="F6680"/>
109              </criteria>
110            </criterias>
111            <renderers>
112              <renderer type="table" rank="0" chunksz="15">
113                <name>Results</name>
114                <columns>
115                  <field REF="F6683"/>
116                  <field REF="F6677"/>
117                  <field REF="F6680"/>
118                  <field REF="F6679"/>
119                </columns>
120              </renderer>
121            </renderers>
122          </report>
123        </reports>
124        <workflow/>
125        <permissions>
126          <permission scope="tracker" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_ACCESS_FULL"/>
127          <permission scope="field" REF="F6683" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
128          <permission scope="field" REF="F6684" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
129          <permission scope="field" REF="F6676" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
130          <permission scope="field" REF="F6676" ugroup="UGROUP_REGISTERED" type="PLUGIN_TRACKER_FIELD_SUBMIT"/>
131          <permission scope="field" REF="F6676" ugroup="UGROUP_PROJECT_MEMBERS" type="PLUGIN_TRACKER_FIELD_UPDATE"/>
132          <permission scope="field" REF="F6677" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
133          <permission scope="field" REF="F6677" ugroup="UGROUP_REGISTERED" type="PLUGIN_TRACKER_FIELD_SUBMIT"/>
134          <permission scope="field" REF="F6677" ugroup="UGROUP_PROJECT_MEMBERS" type="PLUGIN_TRACKER_FIELD_UPDATE"/>
135          <permission scope="field" REF="F6678" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
136          <permission scope="field" REF="F6678" ugroup="UGROUP_REGISTERED" type="PLUGIN_TRACKER_FIELD_SUBMIT"/>
137          <permission scope="field" REF="F6678" ugroup="UGROUP_PROJECT_MEMBERS" type="PLUGIN_TRACKER_FIELD_UPDATE"/>
138          <permission scope="field" REF="F6679" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
139          <permission scope="field" REF="F6679" ugroup="UGROUP_REGISTERED" type="PLUGIN_TRACKER_FIELD_SUBMIT"/>
140          <permission scope="field" REF="F6679" ugroup="UGROUP_PROJECT_MEMBERS" type="PLUGIN_TRACKER_FIELD_UPDATE"/>
141          <permission scope="field" REF="F6680" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
142          <permission scope="field" REF="F6680" ugroup="UGROUP_REGISTERED" type="PLUGIN_TRACKER_FIELD_SUBMIT"/>
143          <permission scope="field" REF="F6680" ugroup="UGROUP_PROJECT_MEMBERS" type="PLUGIN_TRACKER_FIELD_UPDATE"/>
144        </permissions>
145        <artifacts>
146          <artifact id="445">
147            <changeset>
148              <submitted_by format="username">vaceletm</submitted_by>
149              <submitted_on format="ISO8601">2015-11-10T09:05:19+01:00</submitted_on>
150              <comments/>
151              <field_change field_name="title" type="string">
152                <value><![CDATA[A demo bug]]></value>
153              </field_change>
154              <field_change field_name="description" type="text">
155                <value format="text"><![CDATA[With some content]]></value>
156              </field_change>
157              <field_change field_name="product" type="list" bind="static">
158                <value format="id">7675</value>
159              </field_change>
160              <field_change field_name="status" type="list" bind="static">
161                <value format="id">7678</value>
162              </field_change>
163            </changeset>
164            <changeset>
165              <submitted_by format="username">vaceletm</submitted_by>
166              <submitted_on format="ISO8601">2015-11-10T09:05:46+01:00</submitted_on>
167              <comments>
168                <comment>
169                  <submitted_by format="username">vaceletm</submitted_by>
170                  <submitted_on format="ISO8601">2015-11-10T09:05:46+01:00</submitted_on>
171                  <body format="text"><![CDATA[Some work done]]></body>
172                </comment>
173              </comments>
174              <field_change field_name="status" type="list" bind="static">
175                <value format="id">7680</value>
176              </field_change>
177            </changeset>
178          </artifact>
179          <artifact id="446">
180            <changeset>
181              <submitted_by format="username">vaceletm</submitted_by>
182              <submitted_on format="ISO8601">2015-11-10T09:05:19+01:00</submitted_on>
183              <comments/>
184              <field_change field_name="title" type="string">
185                <value><![CDATA[A demo bug (2)]]></value>
186              </field_change>
187              <field_change field_name="description" type="text">
188                <value format="text"><![CDATA[With some content]]></value>
189              </field_change>
190              <field_change field_name="product" type="list" bind="static">
191                <value format="id">7675</value>
192              </field_change>
193              <field_change field_name="status" type="list" bind="static">
194                <value format="id">7678</value>
195              </field_change>
196            </changeset>
197            <changeset>
198              <submitted_by format="username">vaceletm</submitted_by>
199              <submitted_on format="ISO8601">2015-11-10T09:05:46+01:00</submitted_on>
200              <comments>
201                <comment>
202                  <submitted_by format="username">vaceletm</submitted_by>
203                  <submitted_on format="ISO8601">2015-11-10T09:05:46+01:00</submitted_on>
204                  <body format="text"><![CDATA[Some work done]]></body>
205                </comment>
206              </comments>
207              <field_change field_name="Artifact Links" type="art_link">
208                <value nature="reported_in">1234</value>
209                <value nature="_is_child">12</value>
210                <value>42</value>
211              </field_change>
212              <field_change field_name="status" type="list" bind="static">
213                <value format="id">7680</value>
214              </field_change>
215            </changeset>
216          </artifact>
217        </artifacts>
218      </tracker>
219    </trackers>
220  </project>

External Fields

Since 11.14, it’s possible to add external fields on import XML. This external fields are form elements from plugins.

Test Management step fields

Step definitions and step executions are external fields.

Step execution structure

  • Type must be ttmstepexec

  • TTM must be activated in your project

Here is an example of a step execution field for tracker structure XML :

1  <externalField type="ttmstepexec" ID="F431" rank="2">
2    <name><![CDATA[steps]]></name>
3    <label><![CDATA[Steps Execution]]></label>
4    <description><![CDATA[Execution of the test's steps]]></description>
5  </externalField>

Step definition structure

  • Type must be ttmstepdef

  • TTM must be activated in your project

Here is an example of a step definition field for tracker structure XML :

1  <externalField type="ttmstepdef" ID="F431" rank="2">
2    <name><![CDATA[steps]]></name>
3    <label><![CDATA[Steps definition]]></label>
4    <description><![CDATA[Definition of the test's steps]]></description>
5  </externalField>

Step Definition data changeset

To import step defintion’s data changeset, you can use the following format.

  • Type must be ttmstepdef

  • Steps inside are required

 1  <external_field_change field_name="steps" type="ttmstepdef">
 2    <step>
 3      <description format="text"><![CDATA[here is the first step]]></description>
 4      <expected_results format="text"><![CDATA[here is the first expected result]]></expected_results>
 5    </step>
 6    <step>
 7      <description format="html"><![CDATA[here is the second step]]></description>
 8      <expected_results format="html"><![CDATA[here is the second expected result]]></expected_results>
 9    </step>
10  </external_field_change>

Workflow modes

Both workflow types (simple and advanced) are importable through the XML import. Each types define their own tags and hierarchy.

Here is an exemple of the advanced mode:

 1<workflow>
 2  <field_id REF="F688"/>
 3  <is_used>1</is_used>
 4  <transitions>
 5    <transition>
 6      <from_id REF="null"/>
 7      <to_id REF="V427"/>
 8      <postactions>
 9        <postaction_field_date valuetype="2">
10          <field_id REF="F689"/>
11        </postaction_field_date>
12      </postactions>
13      <conditions>
14        <condition type="perms">
15          <permissions>
16            <permission ugroup="UGROUP_PROJECT_MEMBERS"/>
17          </permissions>
18        </condition>
19        <condition type="notempty">
20          <field REF="F692"/>
21        </condition>
22      </conditions>
23    </transition>
24    <transition>
25      <from_id REF="V428"/>
26      <to_id REF="V427"/>
27      <postactions>
28        <postaction_field_date valuetype="2">
29          <field_id REF="F689"/>
30        </postaction_field_date>
31      </postactions>
32      <conditions>
33        <condition type="perms">
34          <permissions>
35            <permission ugroup="UGROUP_PROJECT_MEMBERS"/>
36          </permissions>
37        </condition>
38        <condition type="notempty">
39          <field REF="F692"/>
40        </condition>
41      </conditions>
42    </transition>
43  </transitions>
44</workflow>

Here is an exemple of the simple mode:

 1<simple_workflow>
 2  <field_id REF="F42704"/>
 3  <is_used>1</is_used>
 4  <states>
 5    <state>
 6      <to_id REF="V36863"/>
 7      <transitions>
 8          <transition>
 9              <from_id REF="null"/>
10          </transition>
11          <transition>
12              <from_id REF="V36864"/>
13          </transition>
14      </transitions>
15      <postactions>
16          <postaction_field_date valuetype="2">
17              <field_id REF="F42705"/>
18          </postaction_field_date>
19          <postaction_frozen_fields>
20              <field_id REF="F42708"/>
21          </postaction_frozen_fields>
22      </postactions>
23      <conditions>
24        <condition type="perms">
25          <permissions>
26            <permission ugroup="UGROUP_PROJECT_MEMBERS"/>
27          </permissions>
28        </condition>
29        <condition type="notempty">
30          <field REF="F42708"/>
31        </condition>
32      </conditions>
33    </state>
34  </states>
35</simple_workflow>

Folders

If you have existing folders you want to keep at import, you have to define the tracker which will be flagged as folder with the attribute “is_folder”.

To import your artifacts with link “In folder”, the system nature _in_folder will be used.

<?xml version="1.0" encoding="UTF-8"?>
<project>
      <services>
        <service shortname="plugin_tracker" enabled="true" />
        ...
      </services>
      ...
      <trackers use-natures="true">
        <tracker id="T239" parent_id="0" instantiate_for_new_projects="1" is_folder="true">
          <name><![CDATA[Simple Tracker]]></name>
          <item_name>simple</item_name>
          <description><![CDATA[simple tracker example]]></description>
          <color>inca_silver</color>
          <cannedResponses/>
          <formElements>
            <formElement type="computed" ID="F123" rank="97">
              <name>computed_field_name</name>
              <label><![CDATA[Computed_Field_Label]]></label>
            </formElement>
          </formElements>
          ...
          <artifacts>
            <artifact id="445">
              <changeset>
                <submitted_by format="username">vaceletm</submitted_by>
                <submitted_on format="ISO8601">2015-11-10T09:05:19+01:00</submitted_on>
                <comments/>
                <field_change field_name="Artifact Links" type="art_link">
                  <value nature="_in_folder">12</value>
                </field_change>
              </changeset>
              ...
            </artifact>
          </artifacts>
        </tracker>
      </trackers>
</project>

Computed field import

The new computed field can have have manual or autocomputed values. The <manual_value> node enable to keep the manual value for the field, the <is_autocompute> node keeps the field in autocompute mode.

 1  <?xml version="1.0" encoding="UTF-8"?>
 2  <project>
 3    <services>
 4      <service shortname="plugin_tracker" enabled="true" />
 5      ...
 6    </services>
 7    ...
 8    <trackers use-natures="true">
 9      <tracker id="T239" parent_id="0" instantiate_for_new_projects="1">
10        <name><![CDATA[Simple Tracker]]></name>
11        <item_name>simple</item_name>
12        <description><![CDATA[simple tracker example]]></description>
13        <color>inca_silver</color>
14        <cannedResponses/>
15        <formElements>
16          <formElement type="computed" ID="F123" rank="97">
17            <name>computed_field_name</name>
18            <label><![CDATA[Computed_Field_Label]]></label>
19          </formElement>
20        </formElements>
21        ...
22        <artifacts>
23          <artifact id="445">
24            <changeset>
25              <submitted_by format="username">vaceletm</submitted_by>
26              <submitted_on format="ISO8601">2015-11-10T09:05:19+01:00</submitted_on>
27              <comments/>
28              <field_change field_name="computed_field_name" type="computed">
29                <manual_value><![CDATA[11]]></manual_value>
30              </field_change>
31              <field_change field_name="computed_field_name" type="computed">
32                <is_autocomputed>1</is_autocomputed>
33              </field_change>
34            </changeset>
35            ...
36          </artifact>
37        </artifacts>
38      </tracker>
39    </trackers>
40  </project>

Permissions

In the previous example, you can see a block for permissions management at the end

<permissions>
  <permission scope="tracker" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_ACCESS_FULL"/>
  <permission scope="field" REF="F6683" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
  <permission scope="field" REF="F6684" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
  <permission scope="field" REF="F6677" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
  <permission scope="field" REF="F6677" ugroup="UGROUP_REGISTERED" type="PLUGIN_TRACKER_FIELD_SUBMIT"/>
  <permission scope="field" REF="F6677" ugroup="UGROUP_PROJECT_MEMBERS" type="PLUGIN_TRACKER_FIELD_UPDATE"/>
  <permission scope="field" REF="F6678" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
  <permission scope="field" REF="F6678" ugroup="UGROUP_REGISTERED" type="PLUGIN_TRACKER_FIELD_SUBMIT"/>
  <permission scope="field" REF="F6678" ugroup="UGROUP_PROJECT_MEMBERS" type="PLUGIN_TRACKER_FIELD_UPDATE"/>
  <permission scope="field" REF="F6679" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
  <permission scope="field" REF="F6679" ugroup="UGROUP_REGISTERED" type="PLUGIN_TRACKER_FIELD_SUBMIT"/>
  <permission scope="field" REF="F6679" ugroup="UGROUP_PROJECT_MEMBERS" type="PLUGIN_TRACKER_FIELD_UPDATE"/>
  <permission scope="field" REF="F6680" ugroup="UGROUP_ANONYMOUS" type="PLUGIN_TRACKER_FIELD_READ"/>
  <permission scope="field" REF="F6680" ugroup="UGROUP_REGISTERED" type="PLUGIN_TRACKER_FIELD_SUBMIT"/>
  <permission scope="field" REF="F6680" ugroup="UGROUP_PROJECT_MEMBERS" type="PLUGIN_TRACKER_FIELD_UPDATE"/>
</permissions>

There are 2 scopes for permissions:

  • tracker

  • field

Fore each we have the same type of attributes:

  • REF reference a field defined in tracker structure

  • ugroup is one group that have the given type of permission

  • type is the access right granted (depend of the scope)

Supported ugroup values:

  • UGROUP_ANONYMOUS

  • UGROUP_REGISTERED

  • UGROUP_PROJECT_MEMBERS

  • UGROUP_PROJECT_ADMIN

  • Any custom ugroup name

If several ugroups should have the same permission, there should be several lines

Supported type value for tracker scope:

  • PLUGIN_TRACKER_ADMIN grant tracker administration capabilities to group

  • PLUGIN_TRACKER_ACCESS_FULL grant access to tracker to group

  • PLUGIN_TRACKER_ACCESS_ASSIGNEE grant access to all artifacts assigned to people of the group (eg. Alice and Bob belong to “project_members”, Astrid belong to “project admin”. Alice will see all artifacts assigned to herself or assigned to bob but not those assigned to Astrid)

  • PLUGIN_TRACKER_ACCESS_SUBMITTER grant access to all artifacts submitted by people from the group (see previous example but with “submitted by” instead of “assigned to”)

  • PLUGIN_TRACKER_ACCESS_SUBMITTER_ONLY, for this group people see only the artifacts they submitted (eg. HelpDesk).

Supported type for field scope:

  • PLUGIN_TRACKER_FIELD_READ ugroup can see the field content

  • PLUGIN_TRACKER_FIELD_SUBMIT ugroup can set value for the field at artifact creation

  • PLUGIN_TRACKER_FIELD_UPDATE ugroup can upgrade the field value after creation

Timetracking

If you have times tracked on artifacts and you want to keep at import, you have to:

  • Enable timetracking in tracker

  • Add times for artifacts in this tracker

Here is an example of how to enable timetracking to the tracker and import times:

 1  <?xml version="1.0" encoding="UTF-8"?>
 2  <project>
 3        <services>
 4          <service shortname="plugin_tracker" enabled="true" />
 5          ...
 6        </services>
 7        ...
 8        <trackers use-natures="true">
 9          <tracker id="T239" parent_id="0" instantiate_for_new_projects="1">
10            <name><![CDATA[Simple Tracker]]></name>
11            <item_name>simple</item_name>
12            <description><![CDATA[simple tracker example]]></description>
13            <color>inca_silver</color>
14            <cannedResponses/>
15            <formElements>
16              <formElement type="computed" ID="F123" rank="97">
17                <name>computed_field_name</name>
18                <label><![CDATA[Computed_Field_Label]]></label>
19              </formElement>
20            </formElements>
21            ...
22            <artifacts>
23              <artifact id="445">
24                <changeset>
25                  <submitted_by format="username">vaceletm</submitted_by>
26                  <submitted_on format="ISO8601">2015-11-10T09:05:19+01:00</submitted_on>
27                  <comments/>
28                  <field_change field_name="Artifact Links" type="art_link">
29                    <value nature="_in_folder">12</value>
30                  </field_change>
31                </changeset>
32                ...
33              </artifact>
34            </artifacts>
35            <timetracking is_enabled="1">
36              <permissions>
37                <read>
38                  <ugroup><![CDATA[project_admins]]></ugroup>
39                </read>
40                <write>
41                  <ugroup><![CDATA[project_members]]></ugroup>
42                </write>
43              </permissions>
44              <time artifact_id="445">
45                <user format="ldap">102</user>
46                <minutes>240</minutes>
47                <step>Dev v2</step>
48                <day format="ISO8601"><![CDATA[2020-07-25T00:00:00+02:00]]></day>
49              </time>
50              <time artifact_id="445">
51                <user format="ldap">102</user>
52                <minutes>60</minutes>
53                <step>Dev</step>
54                <day format="ISO8601"><![CDATA[2021-02-06T00:00:00+01:00]]></day>
55              </time>
56            </timetracking>
57          </tracker>
58        </trackers>
59  </project>