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.

URI

Workspace level	`http[s]://<server>:<port>/api/shared_spaces/<space_id>/workspaces/<workspace_id>/metadata/fields`
Shared space level	`http[s]://<server>:<port>/api/shared_spaces/<space_id>/metadata/fields`
Site level	`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>

Filtering 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 can not 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.

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 by ALM Octane. 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 ALM Octane 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 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 } Referencing list nodes 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	String
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