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.

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)

- Set up lists

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ALM Octane Help Center ALM Octane Help 15.1.90 All View Local Help Center View Online Help Center back Go back in browser history forward Go forward in browser history Remove search highlights next topic Go to next topic previous topic Go to previous topic Print the current topic Version: