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 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: