Skip to main content
Version: Early Access

Creating a New Asset Using the API

This article explains how to create a new asset using API.

Prerequisites​

  • Have an HTTP Client.
  • Obtain an API token.
  • Make sure you have a admin level role in the selected Scope.

Understand the Asset Shape​

Before we create a new asset, we need to understand the attributes and relationships for the asset type. Therefore we query meta.v1 to understand the shape of the asset. For example, if we want to create a new Story, we use the following query.

<Server Base URI>/meta.v1/Story?xsl=api.xsl

The result of this query will resemble the following.

Story derives from PrimaryWorkitem 
ID : Relation to Story  
* Scope : Relation to Scope — reciprocal of Workitems
* Name : Text  
Description : LongText  
Order : Rank  
Status : Relation to StoryStatus — reciprocal of PrimaryWorkitems  
Owners : Multi-Relation to Member — reciprocal of OwnedWorkitems  
Super : Relation to Epic — reciprocal of Subs  
Parent : Relation to Theme — reciprocal of Children  
ChangeDate : Date  
CreateDate : Date 
ChangedBy : Relation to Member 
CreatedBy : Relation to Member

In context of creating a new asset, we inspect attributes definitions to understand required attributes. When using xsl=api.xsl parameter, the required attributes are marked with *. Therefore, in the above example, we know a Name and a Scope relationship are required for Story.

Request a New Asset Template​

In order to create a new asset, we need to provide an XML body. To get a template of that XML body, we can use the rest-1.v1/New endpoint. For example, if we want to create a new Story in the root project, we can use the following query.

<Server Base URI>/rest-1.v1/New/Story?ctx=Scope:0

The result of this query will resemble the following:

<Asset href="/VersionOne/rest-1.v1/New/Story">  
<Relation name="Scope" act="set">  
<Asset href="/VersionOne/rest-1.v1/Data/Scope/0" idref="Scope:0"/>  
</Relation>  
</Asset>

The results have been pre-populated based on the ctx parameter; however, the template does not attempt to pre-populate all required attributes. So we need to add the Name attribute as we learned from exploring the asset shape. The new Story should have at least the following.

<Asset href="/VersionOne/rest-1.v1/New/Story">  
<Attribute name="Name" act="set">Create a New Asset</Attribute>  
<Relation name="Scope" act="set">  
<Asset href="/VersionOne/rest-1.v1/Data/Scope/0" idref="Scope:0"/>  
</Relation>  
</Asset>

Post the New Asset​

In order to create a new asset, we need to send an HTTP POST to the rest-1.v1/Data endpoint. For example, we send the following to create a new Story.

<Asset href="/VersionOne/rest-1.v1/Data/Story/14191/21510" id="Story:14191:21510">  
<Attribute name="Name">Create a New Asset</Attribute> 
<Relation name="Scope"> 
<Asset href="/VersionOne/rest-1.v1/Data/Scope/0" idref="Scope:0" />  
</Relation>  
</Asset>

This result confirms the new asset was created. We can now access it as Story:14191. If we want to refer to the values at this starting state, we would use the moment, as in Story:14191:21510. The result also confirms the Name and Scope relationship that we set.

sample-code