API/Tags

This topic explains how to create, use, and update tags in Agility.

Overview

This endpoint provides read, write, and update access to tags. This endpoint queries for tags, creates tags, and updates tags.

URL Form	<Server Base URI>/api/tags/Command/<command> <Server Base URI>/api/tags/all <Server Base URI>/api/tags/<tag>
Authentication	Application
HTTP Request Verb	HTTP GET, HTTP POST
Response Content Type	application/json

API

It is VERY important to note that you MUST use JSON REST API to add tags. You cannot add tags with XML using the REST API. Only JSON works.

HTTP Verbs

HTTP GET

GET requests are used to query information, and receive a JSON response.

HTTP POST

POST requests are used to update information.

What are Tags?

First and foremost Tags are values that exist on most BaseAssets. Tags exist only in the context of the Assets they are added to. This means adding (and removing)tags for an Asset should be done via rest-1.v1/Data.

As of now Tags have been exposed on the following Assets via the AttributeDefinition``TaggedWith

• Story
• Defect
• Test Set
• Task
• Test
• Portfolio Item
• Regression Test

Adding And Removing Tags from Assets

Below is an example of adding the RMA tag and removing the UX tag from an existing Story.

    <Server Base URI>/rest-1.v1/Data/Story/1224

Post Data:

    {
                    "Attributes": {
                    "TaggedWith": {
                    "value": [
                    {
                    "value": "RMA",
                    "act": "add"
                    },
                    {
                    "value": "UX",
                    "act": "remove"
                    }
                    ]
                    }
                    }
                    }

Note that if you just need to perform a single add or remove, then you can simplify the request as shown below.

    <Server Base URI>/rest-1.v1/Data/Story/1224

Post Data:

    {
                    "Attributes": {
                    "TaggedWith": {
                    "value": "RMA",
                    "act": "add"
                    }
                    }
                }

Examples of the Tag API : GET

A Single Tag

The following example returns usage information for the specified tag. It will let you know based on your scope visibility the total # of usages of the tag count vs the usage that are visible to your member visibleCount.

    <Server Base URI>/api/tags?tag=UX

Response:

    {
                    "tag": "UX",
                    "count": 1,
                    "visibleCount": 1
            }

All Tags

The following example returns every tag in use in the system with usage information broken down the same as the Single Tag above.

    <Server Base URI>/api/tags/all

Response:

    {
                    "acceptanceTestDetails": {
                    "tag": "AcceptanceTestDetails",
                    "count": 1,
                    "visibleCount": 1
                    },
                    "acceptanceTestDetails 2": {
                    "tag": "AcceptanceTestDetails 2",
                    "count": 1,
                    "visibleCount": 1
                    },
                    "acceptanceTestDetails 3": {
                    "tag": "AcceptanceTestDetails 3",
                    "count": 1,
                    "visibleCount": 1
                    }
                }

Searching for Tags

The following example returns an array of tags that match the search term.

    <Server Base URI>/api/tags/command/search?term=Test

Response:

[ "Automated SQL UnitTests", "ProductPlanning Regression Tests", "RegressionTestDetails", "RegressionTests", "Testboard", "TestSetDetails", ]

Examples of the Tag API : POST

The below commands are restricted to users that have Project Admin access and will only work for projects they have scope visibility to. A user cannot remove tags on assets they cannot see or edit in the system.

Merging Tags

The following example will merge multiple tags into a single tag. It is possible to merge into an existing tag, or into a new tag. This will remove all of the tags listed in the MergeFrom array in the Post Data and will add the MergeTo tag to the assets the other tags were removed from.

    <Server Base URI>/api/tags/command/merge

Post Data:

                {
                "MergeTo" : "Regression Tests",
                "MergeFrom" : ["RegressionTestDetails", "RegressionTests"]
                }
           

Removing Tags

The following example will allow you to remove tags from every asset they exist on.

    <Server Base URI>/api/tags/command/remove

Post Data:

            {
            "removeFrom" : ["RegressionTestDetails", "RegressionTests"]
            }