Examples of retrieving metadata

This section provides examples of how to access the metadata for entities and fields to work with the ALM Octane REST API.

Get metadata for the user story entity

Request

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/entities?query="name EQ 'story'"

Response

{
  "data": [
    {
      "features": [
        {
          "methods": [
            "DELETE",
            "POST",
            "GET",
            "PUT"
          ],
          "name": "rest",
          "url": "stories"
        },
        {
          "name": "mailing",
          "url": "mails"
        },
        {
          "name": "phases"
        },
        {
          "name": "subtype_of",
          "type": "work_item"
        },
        {
          "parent_types": [
            "feature",
            "work_item_root"
          ],
          "max_depth": 4,
          "root": {
            "type": "work_item_root",
            "id": "1001"
          },
          "name": "hierarchy",
          "child_types": []
        },
        {
          "name": "user_defined_fields"
        },
        {
          "name": "business_rules"
        },
        {
          "name": "comments",
        },
        {
          "name": "attachments",
        }
      ],
      "name": "story",
      "description": null,
      "label": "Story",
      "type": "entity_metadata"
    }
  ],
  "total_count": 1
}

Explanation of the response

Let's look at this example on the workspace level. You can see from this example that:

Description	Metadata excerpt
You can perform DELETE, POST, GET, and PUT operations on user stories.	{ "features": [ { "methods": [ "DELETE", "POST", "GET", "PUT" ], "name": "rest", "url": "stories" },
User stories are hierarchical. Their "parents" are work items. The root item for user stories has an ID of 1001. They do not have "children."	{ "parent_types": [ "feature", "work_item_root" ], "max_depth": 4, "root": { "type": "work_item_root", "id": "1001" }, "name": "hierarchy", "child_types": [] },
The ability to advance the status of the entity from phase-to-phase using the defined workflow is supported. Changing phases of an entity is performed on the entity itself. For example, to change the phase (or status) of an entity, perform a PUT on the entity.	{ "name": "phases" },
User stories are subtypes of work items.	{ "name": "subtype_of", "type": "work_item" },
The user story entity supports: The creation of user-defined fields. Grouping, and the ability to set a default order. Emailing of the entity. User-defined tagging. Attachments. Customization of workflow using rules. Comments. The ability to rank the user story using the ordering attribute. Limitation: Ranking work items is supported using PUT requests. Retrieving the rank of a work item in a GET request is not supported, and null is returned.	{ "name": "phases" }, { "name": "subtype_of", "type": "work_item" }, { "name": "user_defined_fields" }, { "name": "default_order_by", "field_name": "name", "direction": "ASC" }, { "name": "ordering", "aspects": [{ "aspect_name": "rank", "order_field_name": "rank", "context_field_name": null } ] }, { "name": "mailing", "url": "mails" }, { "name": "has_user_tags" }, { "name": "attachments"," }, { "name": "business_rules" }, { "name": "comments", }

Get field metadata for pipelines

Here is an example on the workspace level for pipelines.

Request

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="entity_name EQ 'pipeline'"

Explanation of results

Description	Metadata
Pipeline fields include ID, pipeline name, creation time, the root job for the pipeline, version stamp, author, and current release.	"name": "id", "name": "name", "name": "creation_time", "name": "version_stamp", "name": "author", "name": "last_modified", "name": "current_release",
You can see information about each pipeline field, including (but not limited to): The name of the field. The name of the entity. The description of the field. The label of the field, usually used for display in the ALM Octane UI. The type of the field's values (string, date_time).	{ "entity_name": "pipeline", "description": "", "label": "Creation time", "name": "creation_time", "field_type": "date_time", },
Indication that the field references an entity collection. See also: Reference.	"field_type_data": { "multiple": false, "targets": [ { "type": ""workspace_user" } ] },
Sanitization If a field supports sanitization. REST API output sanitization removes or encodes data returned by requests. This reduces security risks. See also: Sanitization. Valid sanitization types are: NONE. Return the value "as is." Most fields are not sanitized. HTML. Return the value according to the predefined HTML sanitization allowlist. Memo-type fields can be sanitized using this allowlist.	{ "sanitization": "NONE" },
If the field supports additional functionality / features, such as tracking for history purposes. In this case, the functionality is called auditable.	"field_features": [ { "name": "auditable" } ],
If a field is final. A value can be supplied to a field only upon creation of an entity. Then the field becomes read-only. The Author field is a good candidate for setting final to true. See also: Final	{ "final": true },
You can determine if a pipeline field: Can be used for grouping, filtering, and sorting. Can be edited. Is user-defined. Is required. Is used in a rule. Must be unique. Is visible in the ALM Octane UI.	{ "filterable": true, "editable": false, "label": "Creation time", "sortable": true, "is_user_defined": false, "required": false, "accessible_via_business_rules": true, "unique": false, "name": "creation_time", "groupable": false, "visible_in_ui": true },

Know which fields are required for an entity

When creating a new entity using the REST API, it is helpful to know in advance which fields are mandatory. Use the required attribute.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="entity_name EQ 'defect'; required EQ 'true'"

See which fields are not returned by default on GET operations

To see a list of fields that are not returned by default, query the field metadata to check the returned_by_default attribute:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="returned_by_default EQ false"

Get the allowed values for entity fields

Some entities are associated with lists. For example, runs are associated with statuses. Other entities, such as stories, defects, and requirements, are associated with phases.

Skipped might be a valid status for an automated test run, but not for a manual test run.

In Design might be a valid phase for a requirement, but not for a defect.

When creating a new entity, you must provide the correct status or phase, as these are mandatory fields.

This topic explains how to get the values that are relevant for your entity using field metadata and the list_node resource collection. The list_node resource collection contains all list values and maps them to their relevant entities.

Get valid values for a manual test run's statuses

Using the field metadata, we can see all fields and their properties for manual runs:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="entity_name EQ ^run_manual^"

We see two status fields for manual test runs:

list_node.native_status, whose description is "The run's status, such as Planned, Passed, Failed, Not completed or Blocked."
list_node.run_status, whose description is "The aggregated status of the run, such as Passed, Failed, or Requires attention." This status is used to summarize native statuses for analysis purposes, such as in the Dashboard.

The values for both of these statuses are stored as target references to list nodes, using the logical_name attribute.

list_node.native_status

      "field_type_data": {
        "multiple": false,
        "targets": [
          {
            "logical_name": "list_node.run_native_status",
            "type": "list_node"
          }
        ]
      },

list_node.run_status

      "field_type_data": {
        "multiple": false,
        "targets": [
          {
            "logical_name": "list_node.run_status",
            "type": "list_node"
          }
        ]
      },

To see the allowed values for the manual run native status, let's look in the list_nodes resource collection for the statuses based on the logical name prefix list_node.run_native_status. We use the wildcard * to list all statuses with this prefix.

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

We now see the allowed statuses for manual runs, which we can assign, for example, when POSTing a new manual test run using the REST API. The statuses are passed, failed, blocked, skipped, completed, and planned (plus one root list_node).

{
  "total_count": 7,
  "data": [
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.passed",
      "version_stamp": 1,
      "name": "Passed",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1092",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.failed",
      "version_stamp": 1,
      "name": "Failed",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1091",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.blocked",
      "version_stamp": 1,
      "name": "Blocked",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1094",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.skipped",
      "version_stamp": 1,
      "name": "Skipped",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1090",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.not_completed",
      "version_stamp": 1,
      "name": "Not Completed",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1093",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status.planned",
      "version_stamp": 1,
      "name": "Planned",
      "list_root": {
        "type": "list_node",
        "id": "1089"
      },
      "id": "1095",
      "last_modified": "2017-05-09T19:05:51Z"
    },
    {
      "type": "list_node",
      "creation_time": "2017-05-09T19:05:51Z",
      "activity_level": null,
      "logical_name": "list_node.run_native_status",
      "version_stamp": 1,
      "name": "Run_Native_Status",
      "list_root": null,
      "id": "1089",
      "last_modified": "2017-05-09T19:05:51Z"
    }
  ],
  "exceeds_total_count": false
}

See comments for an entity

For performance optimization, when GETting entities, comments are not included in the response. To see comments, you have to explicitly request them using the fields clause.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects&fields=comments

Get deprecated API resources for a specific version

After upgrading to a new version of ALM Octane, you might want to see a list of resources that have been deprecated. In preparation for when deprecated these resources are no longer supported, you might want to update your code to refer to the corresponding alias instead.

To see deprecated resources, query on the deprecated field and specify the version number to which you just upgraded.

Example for deprecated resources:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="deprecated EQ ^12.55.8^"

Tip: To see the alias for a deprecated resource, use the interactive API client. For details, see Interactive API client.