Attributes
Attributes are the fundamental properties that define and describe assets in Digital.ai Agility. This guide covers attribute concepts, definitions, types, and syntax for working with the API.
Overview
On every asset are a number of attributes, which attach specific values to the attribute definitions defined in the asset type. If the attribute's definition is a relation, then the value(s) of the attribute are references to an asset(s).
Attribute Definitions
Attribute definitions describe the properties that "make up" each asset type. Each attribute definition describes the type of data it can contain as well as whether it is required, read only, multi-value, and many other qualities. Attribute definitions are identified by a name that is unique within its asset type. Attribute definitions are defined as either value types or relations to other assets. Further, relation attribute definitions can be either single-value or multi-value.
For example, the Estimate attribute definition on the Workitem asset type is a scalar (specifically, a Number). On the other hand, the Workitem asset type's Scope attribute definition is a single-value relation (to a Scope asset). The reverse relation, Workitems on the Scope asset type, is a multi-value relation (to Workitem assets).
Attribute Types
Digital.ai Agility supports various attribute types for different kinds of data. Attribute types fall into two main categories: value types and relations.
Value Types
A value type is an attribute type with a simple type of value like Boolean or Numeric. Value types are also known as scalars. These represent primitive data that can be directly stored and manipulated.
Relationships
A relationship is an attribute type that references another Digital.ai Agility asset. Relation attribute definitions can be either single-value or multi-value. References are made with OID Tokens. For example, the Scope attribute on a Workitem is a single-value relationship, while the Workitems attribute on a Scope is a multi-value relationship.
Attribute Type Reference
| Attribute Type | Data Type | Value Type? | Description |
|---|---|---|---|
| Boolean | boolean | Yes | true or false |
| Numeric | double | Yes | floating point number |
| Date | datetime | Yes | date and possibly time |
| Duration | string | Yes | a string with syntax N UnitType where N is an integer and UnitType is Days, Weeks, or Months |
| Text | string | Yes | string limited to 4000 characters |
| LongText | string | Yes | String limited by database. Often contains html or rich text. |
| Password | string | Yes | A string that represents the password for a login. A password attribute type is write-only. It can never be retrieved. |
| Relation | Oid | No | a relationship to another asset |
| Rank | Rank | No | An arbitrary object that represents one rank object relative to another |
| AssetType | AssetType | No | the name or token of an asset type |
| Opaque | Opaque | No | An internal value that has no external meaning. |
| State | integer | No | A number that corresponds to an internal asset state of an asset. |
| Blob | Blob | No | A stream of binary data such as the content of an Attachment asset. |
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- UseSumto aggregate numeric attributes. UseCountto count multi-relation attributes. UseMinDateto return minimum date value. UseMaxDateto 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']
Operations
Each operation on an asset type contains a reference to an attribute definition that can be used to determine whether the specific operation can be executed on a given asset or not. Operations allow you to perform actions like creating, updating, or deleting assets, as well as executing specific workflows such as closing or reopening work items.
For more information on executing operations, see: