Skip to main content

Terminology

Five terms carry most of the weight in the Agility API. Everything else is built from them.

Asset​

A system asset is a core business object in the Agility (formerly VersionOne Lifecycle) model. Assets represent the stories and backlog items, defects, sprints and iterations, and the members who use the system.

Every read and write in the API is ultimately an operation on assets.

See Assets for the conceptual treatment.

Asset Type​

Asset types describe the "classes" of data available. Each asset type carries a collection of attribute definitions, a collection of operations, and metadata such as a default sort order.

Asset types form an inheritance hierarchy: each type inherits attribute definitions, operations and rules from its parent. Types at the leaves of the hierarchy are concrete; types with children are abstract. Every asset is an instance of a concrete type.

For example, Story and Defect are concrete asset types. Workitem is abstract, and both Story and Defect ultimately derive from it. Querying Workitem therefore returns both.

System Names Versus UI Names​

Most asset types share a name with the application UI — a Defect in the UI is a Defect asset type. But several of the most common types do not, because the UI name is configurable per methodology while the system name is fixed:

System nameXPScrumAgileUPDSDM
ScopeProjectProjectProjectProject
ScopeLabelProjectProjectProjectProject
StoryStoryBacklog ItemRequirementRequirement
TimeboxIterationSprintIterationIteration
ThemeThemeFeature GroupUse CaseFeature Group

Always use the system name in API calls. The UI-facing name is a localized display value; resolve it through loc-2.v1 if you need to render it.

Asset State​

Asset states represent the system-known lifecycle stage of an asset. It is a numeric attribute (AssetState), and the UI typically shows only assets that are not "dead". Dead is a range, not a single value: every state of 192 or above is dead, and 192 itself is never stored.

StateNameMeaning
0FutureThe asset exists but has not been activated.
64ActiveThe asset has been assigned to a user-defined workflow status.
128ClosedThe asset has been closed or quick-closed.
200Template (dead)Used only to create new copies via Templates or Quick Add.
208Broken Down (dead)The asset was converted to an Epic for further break-down.
209Collaborator (dead)Members only: a guest collaborator, not a full member.
254Deprecated (dead)Retired by the system, such as subscriptions to a removed feature.
255Deleted (dead)The asset has been deleted.
Deletion is not erasure

Deleted assets are not permanently removed. They are marked with an asset state indicating they have no further value to the system. If an asset is significant or has historical importance, consider closing it when it reaches maturity rather than deleting it.

This is why almost every real-world filter carries a clause like AssetState!='255' — without it you get the tombstones back too.

Filters on AssetState match bands rather than exact values, and AssetState!='128' means "below Closed", so it also excludes dead and deleted assets. See AssetState values before filtering on it.

Attribute Definition​

Attribute definitions describe the properties that make up each asset type. Each one declares the type of data it holds and whether it is required, read-only, multi-value, and more. Attribute definition names are unique within their asset type.

An attribute definition is either a value type (a scalar) or a relation to other assets. Relations are further either single-value or multi-value:

  • Estimate on Workitem is a scalar — specifically a number.
  • Scope on Workitem is a single-value relation to a Scope asset.
  • Workitems on Scope is the reciprocal multi-value relation back to Workitem assets.

Discover the full set for any type through meta.v1. Compose them into paths using the attribute definition syntax.

Oid​

An Oid is a unique system identifier, not normally visible in the Agility user interface. An Oid token is the string form: the asset type name and an integer ID joined by a colon.

Member:20
Story:1220
Scope:0

Scope:0 is the system root project and is a useful anchor in examples.

An Oid token may carry a third segment identifying a specific moment — a historical version of the asset:

Story:1220:4471

An Oid is not the same as the user-visible Number attribute (S-01047, D-00234), which is available on many but not all assets and is meant for humans.