Share this page

# 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`
Site | `http[s]://<server>:<port>/admin/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[s]://<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"`

## Retrieve hidden fields by role

You can retrieve hidden user-defined fields (UDFs) that are visible to specific roles by combining role information with field metadata queries.

For details about configuring field hiding, see Field hiding.

To retrieve hidden fields per role:

1. Retrieve the list of roles and their IDs:

   Use the following API call to get role information:

   Copy code

       GET /api/shared_spaces/<space_id>/roles?fields=name,logical_name

   This returns a list of roles with their IDs, names, and logical names.

2. Find the ID of the role you want to filter by:

   From the response, identify the role ID. For example, the DevOps Admin role might have an ID of 1004.

3. Query hidden fields visible to that role:

   Use the role ID to filter the metadata fields:

   Copy code

       GET /api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata_fields?fields=name,id&query="(entity_type='defect';(show_for_roles={id=1004}))"

   This example retrieves hidden UDFs for the 'defect' entity that are visible to the DevOps Admin role (ID 1004).

4. Query hidden custom fields for a specific role:

   Copy code

       GET api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata_fields?fields=name,id,entity_type&query="(is_user_defined=true;hide_field=true;!(show_for_roles={id=1006}))"

   This example retrieves all UDFs hidden from the View role (ID 1006).

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

## 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.

## 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 |  |  |  |  |  |
Maximum Length |  |  |  | Mandatory |  |
Maximum Value | Mandatory |  |  |  |  |
Minimum Value | Mandatory |  |  |  |  |
Not Null |  |  |  |  |  |
Read Only |  |  |  |  |  |
Unique |  |  |  |  |  |

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

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`

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

    }

## See also

- Entity metadata reference
- Retrieve metadata
- Examples of retrieving metadata

https://admhelp.microfocus.com Software Delivery Management 8942
Tips to improve your search results... OpenText™ Software Delivery Management Help Center OpenText™ Software Delivery Management Help 26.3 All View Local Help Center View Online Help Center Version: