Skip to main content
System StatusContact Support Agility Community

Exercise 4: Create your own Story (Backlog Item) within a Scope


This tutorial guides you through the process of creating a story inside of the VersionOne UI using the Rest API.


What you'll learn

This exercise is will walk you through the process of creating a Story in a specific project in your VersionOne instance.

Step 1: Select a destination project that will hold your new story

Creating stories is fairly straight forward and it is also easy to create in the API. Note that stories, also considered Primary Work items just like defects and issues, must be created within a scope (also called a project).

Here is a simple methodology that ensures clean and easy creation of a story.

  1. Examine the metadata to see what attributes must be populated prior to creating the story.

    Open up a browser tab and enter  This is what the output of the query looks like. This page is a way to examine the composition or the schema of the Story asset.

    You will spend a good amount of examining the output from a metadata query to discover what attributes inside of VersionOne assets are important to your project's requirements. This is available in every instance of VersionOne. In the screenshot above, you will see two attributes with * next to them. These are the required attributes that need to be populated before you can create your new asset.  For our example, we're going to populate Name, Scope and Description.

  2. Understand what types and what data can be legally entered in these attributes.

    Name, Scope and Description have their types in the metadata listing above and they are Text, (Scalar), Single-Relation and Text respectively. Recall from exercise 3 on how a Single-Relation works.

  3. Select the scope that will be the destination for your new story. For our example, we are going to add to the Scope called VersionOne Rest APIs 101.

    There are two ways to find the OID of the project that you are interested in using to hold your new story. You can find the project OID from the VersionOne UI or you can query the project from the API.  Both methods are described here.

    Method 1 - Query for a destination project using the VersionOne UI

    1. Go to your projects view and locate the project that you are wan to add your story to.

    2. Hover your mouse over the project and examine the status bar bottom of the screen. You will see the OID appended at the end of the URL.  In this case, it is Scope:1005. Keep this since we are going to use this value to update the scope attribute on the new story.

          (this is the blown up view)

  4. We now have a project OID to use hold our story.

Method #2 Query for a destination project using the VersionOne Rest API 

This method allows you to query the VersionOne database and find the OID that is associated with the human readable text. Modify your URL in the APIConsole to look like the URL below, and click Send.

rest-1.v1/Data/Scope?sel=ID&where=Name='VersionOne REST APIs 101'

       I have taken the liberty to click Send so if you look at the body which is the response, you will see id="Scope:1005".  Scope:1005 is your OID. 

Step 2: Construct your payload.

	<Attribute name="Name" act="set">My New Story</Attribute>
	<Attribute name="Description" act="set">My New story rocks!</Attribute>
	<Relation name="Scope" act="set">
		<Asset idref="Scope:1005" />
  1. Select the GET drop and change it to POST then observe the editor at the bottom.

  2. Construct your payload.

  3. Enter the above payload into the editor and change the URL so it looks like this rest-1.v1/Data/Story and press Send.

  4. Examine the response.

Step 3: A Closer Look at the Payload

  • Lines 1 & 7:
    <Asset> basically states to the Rest API, "Hey, I am sending you an Asset type to create for me".

  • Line 2:  
    name="Name" is where we declaring that we are going to modify the name attribute with the contents inside of the <Attribute> tag. Setting act="set"  indicates that we are going to write a single value to the Name attribute.

  • Line 3:
    This has the same behavior and pattern as line 3.

  • Lines  4-6:  
    Recall that the <Asset> tag is a way to tell the Rest API that you are sending it an asset type.  The <Relation> tag tells the API "Hey, this is not an ordinary scalar value but a complex value. It has a name, action, and the reference (idref) to specific scope.

The set of values that the act keyword can be assigned is {add,set,remove}.

In summary, a payload used for creating a story via the Rest API is a combination of Attributes and Relations wrapped in a <Asset> tag.  Within the context of each Attribute and Relation are their names along with instructions on what kind of "action" should be performed on the individual Attribute or Relation.


  • Learned two ways to search for a project (Scope) OID.

  • Created a new story.

  • Examined the details of a <Relation>.


What two ways to find the Scope's OID did we explore?

Query in VersionOne UI
Query via Query.v1 endpoint
Query via Rest-1.v1