Work with user-defined fields

This topic provides instructions for using the POST operation to add a UDF (user-defined field).

Note: The POST, GET and PUT operations are supported on UDFs. DELETE is not supported on UDFs through the REST API.

Create UDFs

The following example creates a UDF for the defect entity at the shared space level. All workspaces under the designated shared space will inherit the UDF.

Copy code 
POST .../api/shared_spaces/<space_id>/workspaces/500/metadata_fields
{
  "data" : [ {
    "entity_type": "defect",
    "label": "Post Release",
    "subtype": "field_metadata_boolean",
    "type": "field_metadata",
    "name": "post_release_udf"
  }
 ]
}

Note: The workspace 500 is an internal workspace that serves the shared space.

The above action creates a field of type boolean. You can create UDFs using any of the following field types:

  • field_metadata_boolean

  • field_metadata_date_time

  • field_metadata_list

  • field_metadata_long

  • field_metadata_long_string

  • field_metadata_memo

  • field_metadata_ref_to_release

  • field_metadata_ref_to_team

  • field_metadata_ref_to_user

  • field_metadata_string

The following example creates a UDF of type list to a specific workspace 1002:

Copy code 
POST .../api/shared_spaces/1001/workspaces/1002/metadata_fields
{
    "data":
    [
        {"subtype":"field_metadata_list",
        "entity_type":"test_manual",
        "name":"mypriority_udf",
        "label":"mypriority",
        "list":
            {
                "type":"list_node",
                "id":"list_node.priority"
            }
        }
    ]
}

Back to top

Read UDF data

The following examples retrieve information on UDFs from the ALM Octane database.

  • List the UDFs belonging to all entities in workspace {workspace_id}:

    .../api/shared_spaces/{sharedspace_id}/workspaces/{workspace_id}/metadata_fields?query="is_user_defined=true"

  • List the shared UDFs belonging to all entities in shared space 1001:

    .../api/shared_spaces/1001/workspaces/500/metadata_fields?query="is_user_defined=true"

    Note: The workspace 500 is an internal workspace that serves the shared space.

  • List the UDFs belonging to all entities in workspace 1002. The request includes the UDF properties that the server should return, including the shared field. The shared field indicates whether the UDF was created at the shared space level or the workspace level.

    .../api/shared_spaces/1001/workspaces/1002/metadata_fields?fields=is_user_defined,subtype,id,label,entity_type,name,shared&query="is_user_defined=true"

  • List the UDFs belonging to the defect entity. Include selected UDF properties:

    .../api/shared_spaces/1001/workspaces/1002/metadata_fields?fields=subtype,id,label,entity_type,name,shared&limit=500&offset=0&order_by=name&query="(entity_type EQ "defect"; is_user_defined EQ true)"

Back to top

Update UDFs

The following example demonstrates updating an existing UDF of type field_metadata_list. It turns the UDF into a multi-select field.

Copy code 
PUT .../api/shared_spaces/1001/workspaces/1002/metadata_fields
{
  "data" : [ {
    "is_multivalue": true,
    "id": "pwmn3q6727x1pu5kjol66gqjo"
  }
 ]
}

To discover a UDF's ID, you can first do a GET operation to retrieve the UDF properties.

Back to top