Skip to main content
Version: 24.3

Exercise 6: Update your Story

This topic explains how to use update your story option in Agility.

Overview​

This tutorial will help you query the Story created in Exercise 4 using the Rest API.

Prerequisites​

  • Access to a Digital.ai 7.0 instance or newer. We are using https://www16.v1host.com/api-examplesfrom our previous exercises.

  • We assume that you understand all material found in the following previous exercises:

    • VersionOne REST API Tutorial

    • Exercise 1: Basic Use of the API Console

    • Exercise 2: Find a Scope (Project) OID Token in the U

    • Exercise 3: Query a Scope (Project) for Specific Attribute

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

    • Exercise 5: Query your Story

  • Knowledge of the Agility API Console

  • Basic Knowledge of XML

What you'll learn​

This exercise walks you through the process of changing data in the Reference attribute, deleting an Owner, and adding a new Owner.

Step 1: Recall the OID of the newly created story​

Recall the saved OID Story:1045returned in the response from the output in Exercise 4: Create your own Story (Backlog Item) within a Scope and Exercise 5: Query your Story.

Step 2: Select attributes to update, build a payload, and execute POST​

Recall from Exercise 3: Query a Scope (Project) for Specific Attribute, the metadata query. For this exercise, we will update the Owners and Reference attributes. To find the OIDs for the Owners relation, recall Exercise 3: Query a Scope (Project) for Specific Attribute, Step 3, Methods 1 and 2.

Select the scope that will be the destination for your new story. For our example, we are going to add to the Scope called " Digital.ai Agility 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 Lifecyle UI or you can query the project from the API. Both methods are described here.

Method #1 - Query for a Member using the Agility UI​

Under ADMIN/Members/Members, you will see a list of the members in Agility. If you hover over the member's name, you will see the OID for that member in the status at the bottom, left side of the page. In the case of Billy Agile, his OID is Member:1043

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

Run this query: rest-1.v1/Data/Member?sel=ID&where=Name='Billy Agile'.

Here is the response. Confirm that the OID from this response matches the OID discovered in the UI.

alt text

Now that we have established what the Member OIDS were, we can build the payload.

<Asset>  
<Attribute name="Reference" act="set">`**`MyNewReference-123`**`</Attribute> 
<Relation name="Owners" > 
<Asset idref="`**`Member:20`**`" act="`**`remove`**`" />  
<Asset idref="`**`Member:1043`**`" act="`**`add`**`"/>  
</Relation> 
</Asset>

  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:

    Enter this into the URL boxrest-1.v1/Data/Story/1045and click Send.

Step 3: Examine response​

Observe a similar results to the output below.

alt text

Notice here we have Story:1045:1160. Consistent with my previous mention of moments, a new moment is generated from this update to our story. If you examine the output below you will see that it shows the Referenceand Owners attributes with new content.

Step 4: Examine the newly modified attributes​

  • Change your POST button back to GET.

  • Modify the URL to berest-1.v1/Data/Story/1045?sel=Reference,Owners and click Send.

This confirms that our simultaneous changes to an asset was successful.

alt text

Review​

  • Queried the contents of a project using an OID.

  • Perform simultaneous changes to attributes on a single story.

Quiz

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