Attribute Definition Syntax

An attribute is a single or multi-value property on an asset. For example a Story has an attribute called Reference which contains text, while the Owners attribute is a multi-value relationship which allows multiple people to own a single Workitem asset. Attributes can be very simple such as the previously mentioned Reference attribute or they may be complex including downcasting, filters, and aggregates.

Projection

Often it is useful to follow a relationship from one asset through another to get another piece of information. For example if you wanted to know the name of a Category attribute on a Story asset you could ask for the attribute Category.Name on a Story and it would return the Name attribute of the StoryCategory which the Story asset relates to.

            <Server Base URI>/rest-1.v1/Data/Story/1000/Category.Name

Downcast

A Scope asset has a relation called Workitems which points to all the Workitem assets that belong to the given Scope. This includes Story, Defect, Task, and Test asset types. If you wish to only get Story assets you can use downcasting to filter to Workitem assets to a specific type. The following example would return only those Story assets that are in Scope with ID 0.

            <Server Base URI>/rest-1.v1/Data/Scope/0/Workitems:Story

Filter

In another example you may wish to know all the Workitem assets in a given Scope that are owned by a specific Member. A filtered attribute would help solve this problem. You can use **Workitems[Owners=Member:20] **to return only those Workitem assets that are owned by Member with ID 20. An example URL would look like the following.

            <Server Base URI>/rest-1.v1/Data/Scope/0/Workitems[Owners='Member:20']

Aggregation

Lets say you wanted to get the total number of Workitem assets in a particular Scope. You can use the aggregate portion of an attribute to count the number of Workitem assets. The following example would return the total number of Workitem assets that belong to Scope with ID 0.

            <Server Base URI>/rest-1.v1/Data/Scope/0/Workitems.@Count

Combination

To combine all of this into a more complex example, you may also wish to get the total Estimate for all Story assets that have an owner and are in a given Scope. Rather than getting all Workitem assets and programmatically sorting them into buckets, the API can help you. You can follow a relationship, filter the relationship, and then finally use an aggregate to return the final count all using a single attribute on a Scope asset.

The corresponding attribute would be something like this: Workitems:Story[Owners.@Count!='0'].Estimate.@Sum In this example the Scope.Workitems attribute will be downcast to only include Story assets, then filtered where the number of Owners is not zero. Once the filtered list is determined, then Estimate for those Story assets will be pulled and finally a single sum will be returned. This attribute will have a URL like the following.

            <Server Base URI>/rest-1.v1/Data/Scope/0/Workitems:Story[Owners.@Count!='0'].Estimate.@Sum

Formal Syntax

            <Attribute> ::= <AttributeExpression> [ . @<Aggregate> ]
            <AttributeExpression> ::= <AttributeTerm> [ { . <AttributeTerm> } ... ]
            <AttributeTerm> ::= Name [ <DownCast> ] [ <Filter> ]
            <DownCast> ::= : <AssetType>
        <Filter> ::= [ <Filters> ]

Arguments

• Name - The name of an attribute such as the Reference or Owners attributes.
• AssetType - An asset type used to limit or down cast muli-relation attributes such as a Story's Children attribute or a Scope's Workitems attribute.
• Filters - A filter token used to filter the results of a multi-relation attribute such as a Member's Scopes attribute.
• Aggregate - Use Sum to aggregate numeric attributes. Use Count to count multi-relation attributes. Use MinDate to return minimum date value. Use MaxDate to return maximum date value.

Remarks

Downcast. A relation may refer to a higher level asset type, for example Scope.Workitems refers to Workitem assets. Downcasting allows the relation to be filtered to a more specific asset type and also the relation to be filtered by attributes of the more specific asset type. For example downcasting Scope.Workitems to Story assets allows you to use Story specific attributes in the filter such as the Category attribute. The URL will return a 404 Error:

            <Server Base URI>/rest-1.v1/Data/Scope/0/Workitems[Category='StoryCategory:108']

While the following will work correctly.

            <Server Base URI>/rest-1.v1/Data/Scope/0/Workitems:Story[Category='StoryCategory:108']

Related concepts

Platform concepts