Skip to main content

Query Examples

There are 4 ways to retrieve information from the Meta API. You can retrieve all of Meta in one large response, you can retrieve a specific asset type's information, or you can retrieve information for an attribute definition or an operation.

How to Retrieve All of Meta​

The following example will retrieve the entire Meta description in a single large XML response.

~/meta.v1/

<Meta href="/VersionOne/meta.v1/">
	<AssetType name="State" token="State" displayname="AssetType'State" abstract="False">
		<DefaultOrderBy href="/VersionOne/meta.v1/State/ID" tokenref="State.ID"/>
		<DefaultDisplayBy href="/VersionOne/meta.v1/State/Code" tokenref="State.Code"/>
		<AttributeDefinition name="ID" token="State.ID" displayname="AttributeDefinition'ID'State" attributetype="Relation" isreadonly="True" isrequired="False" ismultivalue="False">
			<ReciprocalRelation href="/VersionOne/meta.v1/State/ID" tokenref="State.ID"/>
			<OrderByAttribute href="/VersionOne/meta.v1/State/ID" tokenref="State.ID"/>
			<DisplayByAttribute href="/VersionOne/meta.v1/State/Code" tokenref="State.Code"/>
			<RelatedAsset nameref="State" href="/VersionOne/meta.v1/State"/>
		</AttributeDefinition>
		<!-- Additional Attribute Definition Nodes -->
		<!-- Additional Operation Nodes -->
	</AssetType>
	<!-- Addition Asset Type Nodes -->
</Meta>
Remarks

The root element is called "Meta" and contains an href attribute which indicates what URL was used to retrieve the information. The "Meta" element will contain a number of sub elements called "AssetType" which correspond to each of asset types supported by the Agility API. In each "AssetType" element are multiple "AttributeDefinition" elements and multiple "Operation" elements as well as a few other nodes that are attribute definition references which provide suggestions on how to sort or display certain asset types. Inside each "AttributeDefinition" node there are a number of relevant nodes that describe the specific attribute definition. Finally inside each "Operation" node is a "Validator" node which is a reference to an attribute definition that indicates whether the operation is valid for a given asset.

How to Retrieve Meta for a Story Asset Type​

The following example will retrieve the Meta description for the Story asset type.

~/meta.v1/Story

<AssetType href="/VersionOne/meta.v1/Story" name="Story" token="Story" displayname="AssetType'Story" abstract="False">
	<Base nameref="PrimaryWorkitem" href="/VersionOne/meta.v1/PrimaryWorkitem"/>
	<DefaultOrderBy href="/VersionOne/meta.v1/Story/Order" tokenref="Story.Order"/>
	<DefaultDisplayBy href="/VersionOne/meta.v1/Story/Name" tokenref="Story.Name"/>
	<AttributeDefinition name="ChangeDate" token="Story.ChangeDate" displayname="AttributeDefinition'ChangeDate'Story" attributetype="Date" isreadonly="True" isrequired="False" ismultivalue="False">
		<Base href="/VersionOne/meta.v1/BaseAsset/ChangeDate" tokenref="BaseAsset.ChangeDate"/>
		<OrderByAttribute href="/VersionOne/meta.v1/Story/ChangeDate" tokenref="Story.ChangeDate"/>
</AttributeDefinition>
Remarks

When asking for a specific asset type, such as the one above, the response will be very similar to what is displayed when asking for all of Meta. Note how the asset type contains a "name" attribute as well as an attribute called "abstract". The "abstract" attribute indicates that the Story asset type is a concrete type. A Workitem asset type on the other hand is an abstract type because other asset types derive from it.

You'll also notice that one of the sub-nodes under the "AssetType" element is called "Base". This is an asset type reference node that indicates which asset type Story derives from. In the above example the Story asset type derives from a type called PrimaryWorkitem.

How to Retrieve Meta for the Name Attribute on the Story Asset Type​

The following example will retrieve the Meta description for the Name attribute.

~/meta.v1/Story/Name

<AttributeDefinition href="/VersionOne/meta.v1/Story/Name" of="/VersionOne/meta.v1/Story" name="Name" token="Story.Name" displayname="AttributeDefinition'Name'Story" attributetype="Text" isreadonly="False" isrequired="True" ismultivalue="False">
	<Base href="/VersionOne/meta.v1/BaseAsset/Name" tokenref="BaseAsset.Name"/>
	<OrderByAttribute href="/VersionOne/meta.v1/Story/Name" tokenref="Story.Name"/>
</AttributeDefinition>
Remarks

The root element is called "AttributeDefinition". It contains an "of" attribute which indicates the URL of the asset type that the attribute belongs to. It also contains a "name" attribute and a "token" attribute. When an attribute definition reference is used, it will contain either an attribute called "tokenref" or "nameref" which corresponds directly to an attribute definitions "token" and "name" attributes respectfully.

The "displayname" attribute is an unlocalized string that can be passed to the Localization API to retrieve a meaningful name for the attribute definition.

The "attributetype" attribute indicates what type of data this attribute definition represents. See the List of Attribute Types for more information.

Finally the node contains an "isreadonly" attribute which indicates that the attribute is read only and cannot be updated or set, an "isrequired" attribute which indicates that the attribute is required to save or update an asset of the specific asset type, and finally an "ismultivalue" attribute which indicates that there may be multiple values for the attribute definition.

Currently only attribute definitions of type "Relation" may be multi-value attribute definitions.

How to Retrieve Meta for the Delete Operation on the Story Asset Type​

The following example will retrieve the Meta description for the Delete operation.

~/meta.v1/Story/Delete

<Operation href="/VersionOne/meta.v1/Story/Delete" of="/VersionOne/meta.v1/Story" version="6.1.9999.30960" name="Delete">
	<Validator href="/VersionOne/meta.v1/BaseAsset/IsDeletable" tokenref="BaseAsset.IsDeletable" />
</Operation>
Remarks

The root element is called "Operation". It contains an "of" attribute which indicates the URL of the asset type that the attribute belongs to.

The operation may contain a sub element called "Validator" which is a reference to an attribute definition. A validator is the name of an attribute that can be asked for on an asset to determine whether the operation is valid for the asset.

So for example, you can query a Story asset with ID 1000 for the IsDeletable attribute to determine whether you can call the Delete operation on the asset.