Trackers ******** Basics: - ```` node contains a list of ````, then ```` and finally ```` - Within a ```` there is first the structure of the tracker and then the data themselves within ```` node. - The tracker structure is made of metadata (like ````), fields (````), semantics (````), Workflow & field dependencies (````, ````, ````), reports (````) and permissions (````). - An ```` is made of ````, each ```` corresponds to a modification of the artifact. Order matters! the first is the artifact creation. - A ```` is composed of a ```` (can be in ``text``, ``html`` or ``commonmark`` format) and a set of ````. Each ```` refers to a field referenced in the ```` section of ````. 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" (, L78) that uses references V7678, V7679 and V7680 defined L56-59. - L146: the artifact creation set a value to this status field () and the value (7678) refers to V7678 L56. .. sourcecode:: xml :linenos: :emphasize-lines: 51,56,57,58,59,78,146 ... ... simple inca_silver id submitted_by title depends description c1 product c2 status title Define the title of an artifact status Define the status of an artifact Default The system default artifact report Results vaceletm 2015-11-10T09:05:19+01:00 7675 7678 vaceletm 2015-11-10T09:05:46+01:00 vaceletm 2015-11-10T09:05:46+01:00 7680 vaceletm 2015-11-10T09:05:19+01:00 7675 7678 vaceletm 2015-11-10T09:05:46+01:00 vaceletm 2015-11-10T09:05:46+01:00 1234 12 42 7680 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 : .. sourcecode:: xml :linenos: 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 : .. sourcecode:: xml :linenos: 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 .. sourcecode:: xml :linenos: 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: .. sourcecode:: xml :linenos: 1 Here is an exemple of the ``simple`` mode: .. sourcecode:: xml :linenos: 1 Artifact link types ------------------- When importing a project that uses custom artifact link types (aka. natures), you should check that the target Tuleap platform has the same artifact link types by adding a ```` node. The XML importer will check that all artifact link types defined in this node exist on the target platform. If one or more types don't exist, it will stop the import safely before anything is imported. In addition, the children ```` tags will allow the user to define if this type is used or not in the target project: * if ``is_used="0"``, the type will be disabled in project * if ``is_used="1"`` or is_used is missing, the type will be used in the project. .. sourcecode:: xml ... my_custom_nature_shortname my_custom_nature_shortname2 .. attention:: You must set the ``use-natures`` attribute to ``false`` on trackers to not use the typed artifact links. Since Tuleap 9.14, trackers now use by default the typed artifact links. 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. .. sourcecode:: xml ... ... simple inca_silver computed_field_name ... vaceletm 2015-11-10T09:05:19+01:00 12 ... Computed field import --------------------- The new computed field can have have manual or autocomputed values. The node enable to keep the manual value for the field, the node keeps the field in autocompute mode. .. sourcecode:: xml :linenos: :emphasize-lines: 15,16,17,18,19,20,29,32 ... ... simple inca_silver computed_field_name ... vaceletm 2015-11-10T09:05:19+01:00 1 ... Permissions ----------- In the previous example, you can see a block for permissions management at the end .. sourcecode:: xml 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: .. sourcecode:: xml :linenos: :emphasize-lines: 35-56 ... ... simple inca_silver computed_field_name ... vaceletm 2015-11-10T09:05:19+01:00 12 ...