Entity features

This topic lists the array of features supported by an entity's metadata. Entity metadata describes the features that the entity supports. This topic shows how the features are represented in the REST API.

Each item is a JSON object, features. Features and relations are represented as a reference field for both entities involved in the relation.

REST

The following are the supported REST API-related definitions.

Field	Description
name	The name of the feature is a constant value: rest.
url	The resource URL relative to the context root.
methods	An array of strings that the HTTP protocol methods support. Values: GET POST PUT DELETE

Field

Description

name

The name of the feature is a constant value: rest.

url

The resource URL relative to the context root.

methods

An array of strings that the HTTP protocol methods support.

Values:

GET
POST
PUT
DELETE

Copy code

Example for the workspaces entity (at the shared space level):

{
    "name": "rest",
    "url": "workspaces",
    "methods": [ "GET", "POST", "PUT" ]
}

Mailing

The mailing feature indicates whether the entity supports mailing.

Fields	Description
name	The name of the feature is a constant value: mailing.

Copy code

Mailing example:

{
    “name”: “mailing”
    “url”: “mails”
}

Non- auditable

The non-auditable feature indicates whether the entity should appear in an audit.

For details, see Audit entities (technical preview).

Fields	Description
name	The name of the feature is a constant value: non-auditable. If this feature is listed for an entity, the entity does not appear during an audit.

Copy code

Non-auditable example:

{
    “name”: “non-auditable”
}

History

The history feature indicates whether the entity should be listed when using the REST API for viewing history.

For details, see View history (technical preview).

Fields	Description
name	The name of the feature is a constant value: history. If this feature is listed for an entity, the entity does appear when viewing history.

Copy code

History example:

{
    “name”: “history”
}

Drafts

The drafts feature indicates whether drafts of work items (epics, features, user stories, and defects) can be created.

Use drafts to bypass validation rules when POSTing work items using the API. This allows integrations using the API to quickly create work items without, for example, validating required fields.

For details, see Draft entities.

Fields	Description
name	The name of the feature is a constant value: draft_mode.

Copy code

Drafts example:

{
    “name”: “draft_mode”
}

Attachments

The attachments feature indicates whether the entity supports attachments by accessing the <context>/attachments API.

Fields	Description
name	The name of the feature is a constant value: attachments. To add an attachment to entities that support this feature, reference the entity in the *<context>/attachments* request using the field on the attachment entity: owner_<entity name> Where entity name can be the entity name or the parent entity name, if the entity has the subtype of attribute. The actual field name can be queried via the field metadata API for the attachment entity. For details, see Field metadata reference. Example: owner_defect The attachment entity must have a reference to only one owner entity.

Fields

Description

name

The name of the feature is a constant value: attachments.

To add an attachment to entities that support this feature, reference the entity in the <context>/attachments request using the field on the attachment entity:

owner_<entity name>

Where entity name can be the entity name or the parent entity name, if the entity has the subtype of attribute.

The actual field name can be queried via the field metadata API for the attachment entity. For details, see Field metadata reference.

Example: owner_defect

The attachment entity must have a reference to only one owner entity.

Copy code

Attachments example:

{
    “name”: “attachments”
}

Comments

The comments feature indicates whether the entity supports comments through the <context>/comments API.

Field	Description
name	The name of the feature is a constant value: comments. The actual field name can be queried via the field metadata API for the comment entity. For details, see Field metadata reference. Example: owner_defect The comment entity must have a reference to only one owner entity.

Copy code

Comments example:

{
    “name”: “comments”
    “relation_name”: “comments_to_epic”
}

Rules

The rules feature indicates whether the entity supports rules.

Fields	Description
name	The name of the feature is a constant value: business_rules.

Copy code

Rules example:

{
    “name”: “business_rules”
}

Subtypes

The subtypes feature indicates that the entity has subtypes.

Aggregated entities have a field called subtype which stores the subtype of the entity instance. Similarly, the subtype instances have a field called Subtype of , the aggregated entity to which they are related.

Fields	Description
name	The name of the feature is a constant value: subtypes.
types	A string array of the names of the entities, which are the subtypes of this entity.

Copy code

Subtypes example:

{
    “name”: “subtypes”,
    “types”: [
        “defect”,
        “feature”,
        “epic”,
        “work_item_root”,
        “story”
    ]
}

Subtype of

The subtype of feature indicates that an entity is a subtype of another entity.

Entities that are a "subtype of" have a field called subtype of, the aggregated entity to which they are related. Similarly, aggregated entities have a field called subtype, which stores the subtype of the entity instance.

Fields	Description
name	The name of the feature is a constant value: subtype_of.
type	The name of the entity, which has this entity in the subtypes feature definition.

Copy code

Subtype of example:

{
    “name”: “subtype_of”,
    “type”: “work_item”
}

Phases

The phases feature provides the ability to advance the status of the entity from phase-to-phase using the defined workflow.

Fields	Description
name	The name of the feature is a constant value: phases.

Copy code

Phases example:

{
    “name”: “phases”
}

Hierarchy

The hierarchy feature indicates whether the entity is hierarchical.

Fields	Description
name	The name of the feature is a constant value: hierarchy.
root	The root entity in the hierarchy, with the following fields: type. The type of the root entity—often, work_item_root. id. The ID of the root entity. For non-empty arrays, multi-reference field by name children exists on the entity (this field will be defined in the fields metadata API). For non-empty arrays, reference field by name parents exists on the entity (this field will be defined in the fields metadata API). child_types. An array of strings, the allowed types for child entities. parent_types. An array of string, the allowed types for parent entities. max_depth. The maximum number of levels allowed in the hierarchy.

Fields

Description

name

The name of the feature is a constant value: hierarchy.

root

The root entity in the hierarchy, with the following fields:

type. The type of the root entity—often, work_item_root.
id. The ID of the root entity.

For non-empty arrays, multi-reference field by name children exists on the entity (this field will be defined in the fields metadata API).

For non-empty arrays, reference field by name parents exists on the entity (this field will be defined in the fields metadata API).
child_types. An array of strings, the allowed types for child entities.
parent_types. An array of string, the allowed types for parent entities.
max_depth. The maximum number of levels allowed in the hierarchy.

Example of the hierarchy feature for application modules (product areas)

Copy code

Example of hierarchy feature for the product area entity:

    {

      "features": [
        {
          "methods": [
            "DELETE",
            "POST",
            "GET",
            "PUT"
          ],
          "name": "rest",
          "url": "product_areas"
        },
        {
          "parent_types": [
            "product_area"
          ],
          "max_depth": 4,
          "root": {
            "type": "product_area",
            "id": "1001"
          },
          "name": "hierarchy",
          "child_types": [
            "product_area"
          ]
        }
      ],
      "name": "product_area",
      "description": "Also known as an application module, a product area is a functional area of the application you are developing. Use product areas to test overall product quality (such as regression testing, end-to-end cross-feature testing).",
      "label": "Product Area",
      "type": "entity_metadata"
    },

Example of the hierarchy feature for feature entity with a subtype

Copy code

Example of hierarchy feature for the feature entity with subytpe work_item:

   {

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