Working with lists

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

Overview

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

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

Lists and list values also have logical names, for use such as when filtering. The logical names for user-defined lists and list values are automatically generated if not supplied.

Logical names must be lowercase English letters and numbers. You may also enter one underscore character between letters. The logical names must end with the suffix _In (with a lowercase "l" for "logical name").

You cannot modify a logical name after it is created.

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": 
      [
        {
          "logical_name": "colors_ln",
          "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": "colors_ln"
          }, 
    
          "logical_name": "blue_ln",
          "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/<shared_space_id>/workspaces/<workspace_id>/list_nodes?query="logical_name EQ ^list_node.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/<shared_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

Change a list’s name

You can only change the name of custom lists.

PUT .../api/shared_spaces/<shared_space_id>/workspaces/<workspace_id>/list_nodes?query="logical_name EQ ^list_node.my_custom_list^"
{"data": 
  [
       { "type": "list_node",
         "list_root" : null,
         "name":"NEW LIST_NAME"
       }
  ]
}

Back to top

See also: