Skip to main content
Version: 24.3

Changing List Type Value Colors Using the API

This article explains how to change the list type value colors using the API.

Digital.ai Agility contains many list types that display as drop-down lists in asset details, such as a portfolio item, story, or defect. For example, portfolio items have an EpicCategory list type that, by default, contains values such as Initiative, Feature, Sub-Feature, and Non-Functional, and displays in the Digital.ai Agility user interface with the label "Type". In addition to names, list type values also have an associated color, and using the Digital.ai Agility API, you can create new or edit existing list types values and their associated colors.

List Type Value Colors

When setting the list type value color, you can use one of the following named values:

watermelonfuchsiawisteriadenimmarineseafoam
tumbleweedpaperstrawberryplumeggplantindigo
ceruleanjunglebeaverobsidianlimespring
dandelionmangotangerinemahoganydoveshadow
fernshamrocksunglowcoppersunsetmulberry
pewteriron 

Finding the Name of a List Type

Before you can work with a list type you'll need to know its internal system name. For example, if you want to work with a list type that is used by an Epic, you can use the following Meta API query to get the list of attributes that it uses:

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

The result of this query will resemble the following:

Epic derives from Workitem
* Name : Text
* Scope : Relation to Scope — reciprocal of Workitems
BlockingIssues : Multi-Relation to Issue — reciprocal of BlockedEpics
Category : Relation to EpicCategory — reciprocal of Epics
Description : LongText

In this case, the Category attribute is what appears as a "Type" in the user interface, and the list type that it is associated with it is named EpicCategory.

Querying for List Type Values

Once you know the name of the list type that you want to work with, you can find out the values that it contains using a Data API query like the following:

<Server Base URI>/rest-1.v1/Data/EpicCategory

The result of this query will resemble the following:

    <Assetstotal="4"pageSize="2147483647"pageStart="0">
\<Asset href="/15.1.0.7144/rest-1.v1/Data/EpicCategory/207" id="EpicCategory:207"\>  
\<Attributename="AssetType"\>EpicCategory\</Attribute\>
\<Attributename="ColorName"\>seafoam\</Attribute\>
\<Attributename="AssetState"\>64\</Attribute\>
\<Attributename="Order"\>99\</Attribute\>
\<Attributename="Description"/\>
\<Attributename="Name"\>Initiative\</Attribute\>
\</Asset\>

\<Asset href="/15.1.0.7144/rest-1.v1/Data/EpicCategory/208" id="EpicCategory:208"\>
\<Attributename="AssetType"\>EpicCategory\</Attribute\>
\<Attributename="ColorName"\>sunglow\</Attribute\>
\<Attributename="AssetState"\>64\</Attribute\>
\<Attributename="Order"\>100\</Attribute\>
\<Attributename="Description"/\>
\<Attributename="Name"\>Feature\</Attribute\>
\</Asset\>

Each value in the list type contains an id value which is the OID Token. You'll need that value when working with a specific list type value.

Creating a List Type Value

To create a new list type value in an existing list type, you can execute an HTTP POST request against the same REST URL that you used to query all the values in the list type:

\<Server Base URI\>/rest-1.v1/Data/EpicCategory

The XML payload of the HTTP POST will be the attributes that you want to set for the new list type. In the example below, we're setting the Name and the ColorName:

\<Asset\>  
\<Attribute name="Name" act="set"\>New List Type Value\</Attribute\>
\<Attribute name="ColorName" act="set"\>tumbleweed\</Attribute\>
\</Asset\>

The result of this query will resemble the following:

\<Assethref="/15.1.0.7152/rest-1.v1/Data/EpicCategory/2039/3045"id="EpicCategory:2039:3045"\>  
\<Attributename="Name"\>New List Type Value\</Attribute\>
\<Attributename="ColorName"\>tumbleweed\</Attribute\>
\</Asset\>

Note that the HTTP response will contain the OID Token of the newly created list type value in the id attribute, you will need that OID Token value to perform operations on that list type value.

Updating a List Type Value

To update an existing list type value, append the numerical portion of the OID Token to the REST URL, then pass the attribute value that you want to update in the XML payload of the HTTP POST request:

\<Server Base URI\>/rest-1.v1/Data/EpicCategory/2039

The XML payload of the HTTP POST will be the attributes that you want to set for the new list type. In the example below, we're only updating the ColorName:

\<Asset\>  
\<Attribute name="ColorName" act="set"\>shamrock\</Attribute\>
\</Asset\>

The result of this query will resemble the following:

\<Assethref="/15.1.0.7152/rest-1.v1/Data/EpicCategory/2039/3046"id="EpicCategory:2039:3046"\>  
\<Attributename="ColorName"\>shamrock\</Attribute\>
\</Asset\>

Deleting a List Type Value

To delete an existing list type value, append the Delete operation using the op keyword and execute the call as an HTTP POST request:

\<Server Base URI\>/rest-1.v1/Data/EpicCategory/2039?op=Delete

The result of this query will resemble the following:

\<Assethref="/15.1.0.7152/rest-1.v1/Data/EpicCategory/2039/3049"id="EpicCategory:2039:3049"/\>