Share this page

# Working with lists

You can add custom lists, or customize items in existing system lists, using the REST API.

In this topic:

## Overview

To work with lists, you must be authenticated in ALM Octane with either space admin permissions or as an admin for a workspace.

Limitations: UDFs can only be defined in English even if ALM Octane has been localized for a specific language.

Lists and list values can be filtered by name or logical name. The logical names for user-defined lists and list values are automatically generated.

Back to top

## Create a new custom list

1. Create the root of the list:

       POST .../api/shared_spaces/<shared space ID>/workspaces/<workspace ID>/list_nodes

       {"data":

         [

           {

             "name":"colors"

           }

         ]

       }

   The logical_name of the newly‐created list is the root ID. For example, this POST might return the ID abcd1234.

2. Create list items for the list whose ID is abcd1234:

       POST .../api/shared_spaces/<shared space ID>/workspaces/<workspace ID>/list_nodes

       {"data":

         [

           {

             "list_root": {
               "type": "list_node",
               "id": "abcd1234"
             },

             "name": "blue"

           }

         ]

       }

Back to top

## Add an item to an existing list

1. Find the ID of the list. In this example, the list that is updated is the list with the possible values for a run status.

       GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="logical_name EQ ^list_node.run_status^"

       Or:

       GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="name EQ ^run_status^"

2. The ID of the root node of the list is returned in the response. Use this value in the body of the request for the list_root id property (in step 3).

3. Add the new item to the list:

       POST .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes

       {"data":

         [

             {  "type": "list_node",

                "list_root" : {

                    "type": "list_node",

                    "id":<list root ID>},

                    "name":"new item value"

              }

         ]

       }

Back to top

## Remove an item from an existing list

To remove an item from a list, you can:

- Temporarily deactivate the list item.

- Deprecate the list item.

You deactivate, deprecate, or activate a list item by updating the list item's activity level.

Activity level | Description
--- | ---
0 | Active
1 | Deprecated
2 | <For internal use. Do not use.>
3 | Inactive Note: You cannot assign inactive values to fields that use the list.

Example: Deactivating an item

    PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes/<list_item_logical_name>?fields=id,name,activity_level

    {

    "activity_level": 3

    }

Example: Activating an item

    PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes/<list_item_logical_name>?fields=id,name,activity_level

    {

    "activity_level": 0

    }

Back to top

## Change a list’s name

You can only change the name of custom lists.

    PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="logical_name EQ ^abcd1234^"

Or:

    PUT .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="name EQ ^colors^"

    {"data":

      [

           {

             "name":"NEW LIST_NAME"

           }

      ]

    }

Back to top

See also:

- Accessing user-defined fields (UDFs)

- Lists

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ALM Octane Help Center ALM Octane Help 23.4-24.3 All View Local Help Center View Online Help Center Version: