Field metadata reference

Field metadata describes the fields available for an entity. Each field has properties and features, such as the type of the field, whether the field’s values are audited, and validations on the field.

In this topic:

URI

The table below lists the URIs for the different levels.

Level URI
Workspace http[s]://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields
Shared space

http[s]://<server>:<port>/api/shared_spaces/<space_id>/metadata/fields

For the syntax for specifying parameters in URIs, see Variables and values.

Throughout this document, the example URIs are abbreviated, without the server and port context.

http://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/<entities>

Becomes:

.../api/shared_spaces/<space_id>/workspaces/<workspace_id>/<entities>

Filter field metadata using the URI

You can filter on all attributes when filtering field metadata.

When filtering metadata, unlike regular filtering on entities:

  • Only the query clause is supported. You cannot use the limit, offset, total_count, or order_by clauses.
  • The Or operator (||) is not supported between query phases in the query statement. Only the And operator (;) is supported.
  • The entity_name sets the context for any other query phrases in the query statement.

Examples

  • To list fields only related to defects: 

    http[s]://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="entity_name EQ 'defect'"

  • To list the required fields for manual tests: 

    http://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="entity_name EQ 'test_manual' ; required EQ true"

  • To list defect fields that have a creation_time property: 

    http[s]://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="entity_name EQ 'defect'; "name EQ 'creation_time'"

  • To list only user-defined fields, query the field metadata with the is_user_defined attribute: 

    http[s]://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields?query="is_user_defined EQ true"

Supported HTTP Methods

This API supports only the GET operation.

Back to top

Properties

Below are the properties that describe each field in the REST API.

Note: Each relation is represented as a reference field for both of the entities that are involved in the relation.

Field Properties
Access level

If the field can be accessed (such as PUBLIC, or PUBLIC_TECH_PREVIEW).

  • Field name: access_level
Accessible by rules

Whether rules can access this field.

  • Field name: accessible_via_business_rules

  • Value: Boolean
Auto-generated

Whether the field is generated automatically.

  • Field name: auto_generated

  • Value: Boolean
Description

The description for the field.

  • Field name: description
Entity name

The entity the field belongs to.

  • Field name: entity_name
Features

Set of the features supported for this field, such as:

  • non-auditable. By default, auditing of fields is supported. If this feature is listed, the field is not tracked for audits. The feature is listed as: "name": "non-auditable".

  • graphable. This field is available for graphs. The feature is listed as: "name": "graphable".
Field type

The type of the field’s expected value.

  • Field name: field_type

For the available field types, see Field types.
Filterable

Whether the field can be filtered .

  • Field name: filterable

  • Value: Boolean
Groupable

Whether you can group by this field.

  • Field name: groupable

  • Value: Boolean
Label

The label of the field as might appear in UI.

  • Label

  • Field name: label
Name

The name of the field as it appears in API representation.

  • Field name: name
Returned by default

Whether the field is returned by default when there is no field selection.

  • Field name: returned_by_default

Note: Default fields are not returned for TECH-PREVIEW resources.
Selectable

Whether the field can be used in a query.

Some fields are intentionally not selectable, if they would return too many results.

For example, you can query a defect by its severity. But querying a severity and all associated defects would potentially return too many results.

  • Field name: selectable

  • Value: Boolean
Sortable

Whether we can sort entities according to this field.

  • Field name: sortable

  • Value: Boolean
Supports permissions

Whether the field is controlled by permissions.

  • Field name: supports_permissions

  • Value: Boolean
User-defined

Whether the field is system-defined or user-defined.

  • Field name: is_user_defined

  • Value: Boolean
Visible

Whether the field is visible in the user interface.

  • Field name: visible_in_ui

  • Value: Boolean

Back to top

Field types

The following table describes the field types available for an entity.

Type Description
Boolean

  • Field that contains Boolean values.

  • Values: true / false

"field_type": "boolean"
Date

  • Field that contains date information.

  • Expected date format is: ISO-8601, such as: 2022-02-25.
DateTime

  • Field that contains complete date and time information, meaning "date only" is not supported.

  • Expected date format is: ISO-8601, such as:

    • 2018-06-10T10:13:15Z

    • 2018-03-12T16:42:11%2B01:00 (encoded 2018-03-12T16:42:11+01:00

    • 2018-03-12T16:42:11-01:00

  • The date and time is UTC.

  • For create, update and filtering purposes, the API consumer must use the UTC and ISO-8601 formats.

"field_type": "date_time"
Integer

  • Field that contains integer values.

  • Value of this type can be in the range of -9007199254740991 to +9007199254740991.

"field_type": "integer"

Note: All ID fields are strings, not integers.
Memo

  • A field that contains a text value.

  • Usually represented in HTML

"field_type": “memo”
Object

  • A field that has an arbitrary structure.

  • Represented as a JSON object, as defined in the JSON documentation.

"field_type": "object"
Reference

  • A field that references an entity collection.

  • The value is set as a link. The link is an object that contains: 

    • Entity type

    • Entity ID

      For example:

      {
           "id": 1001,
           "type": "defect"
      }

  • The field field_type contains they type of field. For reference fields: “field_type”: “reference”

  • The field field_type_data contains information on the referenced types.

  • Multiple references can be represented if the multiple field is set to true. When the multiple field is set to true, values are expected in the following form:

    {
        "total_count": 2,
        "data": [
            {
                "id": 1001,
                "type": "release"
            },
            {
                "id": 1002,
                "type": "release"
            }
        ]
    }

    Note: For POST and PUT requests, the total_count property can be omitted.

  • The List Node (list_node entity) entity is a special one, and the reference field to a list node is different than the other entities.

  • The Reference field can reference more than one entity type.

    Representation of a reference to single entity type, except list_node entity 

    "field_type": "reference",
    "field_type_data": {
        "targets": [
            {
                "type": "release"
            }
        ],
        "multiple": false

    Representation of a reference a list_node entity

    "field_type": "reference",   
    "field_type_data": {
        "targets": [
            {
                "type": "list_node",
                "logical_name": "list_node.severity"
            }
        ],
        "multiple": false
    }

    Representation of a reference to multiple entity types, except the list_node entity

    "field_type": "reference",
    "field_type_data": {
        "targets": [
            {
                "type": "defect"
            },
            {
                "type": "story"
            }
        ],
        "multiple": false
    } 

Example: Reference to a list_node entity.

"field_type": "reference",   
"field_type_data": {
    "targets": [
        {
            "type": "list_node",
            "logical_name": "list_node.severity"
        }
    ],
    "multiple": false
}
String

  • A field that contains a string value.

  • The length of the value is determined by the max_length input validation property.

“field_type”: “string”

Note: All ID fields are strings, not integers.

Back to top

Data validation

Data validation lets you validate inputs and outputs.

This provides a way for the consumer to validate inputs before inputs are sent to the server, and to expect certain outputs to be returned from the server.

You can validate both inputs and outputs.

Note: Some validations depend on the context. In these cases, a status code and an error message are returned.

Input

Values sent to the server can be validated.

Some validations are optional.

Some validations are allowed for specific data types only.

Input validation by data type

Input validation

Integer

Boolean

Date / DateTime

String

Memo

Reference

Final

Check mark.

Check mark. Check mark. Check mark. Check mark. Check mark.

Maximum Length

X mark

X mark

X mark

Mandatory

X mark

X mark

Maximum Value Mandatory X mark X mark X mark X mark X mark
Minimum Value Mandatory X mark X mark X mark X mark X mark

Not Null

 Check mark. Check mark. Check mark. Check mark. Check mark. Check mark.

Read Only

 Check mark. Check mark. Check mark. Check mark. Check mark. Check mark.

Unique

Check mark.

X mark

X mark

Check mark.

X mark

X mark

Input data types
Data type Description Field name  Value Example
Editable Determines whether a field is read-only. editable Boolean "editable": true
Final A value can be supplied to a field only upon creation of an entity. Then the field becomes read-only. This means that subsequent attempts to PUT a value in the field results in a 400 (Bad Request) error. final Boolean “final”: true
Maximum Length Enforces a maximum length of a string field. max_length Integer, >0 “max_length”: 70
Maximum Value Enforces a maximum value for integer fields. max_value Integer. Must be greater than or equal to the minimum value validation. "max_value": 10000
Minimum Value Enforces a minimum value for integer fields. min_value Integer. Must be less than or equal to the maximum value validation. "min_value": 1
Not Null Determines whether a null value is allowed. required Boolean “required”: true
Read Only Determines whether the field is read only. . This means that attempts to PUT a value in the field results in a 400 (Bad Request) error. editable Boolean “editable”: true
Unique Enforces uniqueness on the level of the whole entity type. unique Boolean “unique”: true

Output

Values that are being returned from the server can be validated.

Validations are optional.

Some validations are allowed from specific data types only.

Output validation by data type

Output validation

Integer / Long

Boolean

Date / DateTime

String

Memo

Reference

Sanitization

 X mark X mark X mark Check mark. Check mark. X mark
Output data types
Data type Description Field name  Value Example

Sanitization

    Enforces sanitization for the field’s output and provides options for types of sanitization.

    See also: Sanitization.

sanitization

A string value that represents an enum: {text, html}

“sanitization”: “html

Back to top

Example: Metadata for a run field object

{
    "name": "description",
    "entity_name": "run",
    "filterable": false,
    "editable": true,
    "returned_by_default": true,
    "label": "Description",
    "sortable": false,
    "required": false,
    "sanitization": "HTML",
    "unique": false,
    "field_type": "memo",
    "max_length": null
}

Back to top

See also: