Field metadata reference

The ALM Octane public REST API is fully metadata-driven. All entities described by metadata resources can be accessed via the REST API as resource collection.

The fields metadata API defines the fields available for an entity. For each field there are properties and features, such as the type of the field, whether the field’s values are audited, validations on the field, and so on.

URI

Workspace level

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

Shared space level

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

Site level

http[s]://<server>:<port>/admin/metadata/fields

This API supports filtering only by name and entity_name, such as:

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

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

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

https://{server}:{port}/api/shared_spaces/{uid}/workspaces/{id}/<entity_collection>

Becomes:

.../api/shared_spaces/{uid}/workspaces/{id}/<entity_collection>

Supported HTTP Methods

This API supports only the GET operation.

Back to top

Properties

Below are the various 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
Name

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

  • Field name: name

Label

The label of the field as might appear in UI.

  • Label

  • Field name: label

Entity

The entity the field belongs to.

  • Field name: entity_name

Filterable

Whether the field can be filtered .

  • Field name: filterable

  • Value: Boolean

Sortable

Whether the field can be sorted.

  • Field name: sortable

  • Value: Boolean

Returned by Default

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

  • Field name: returned_by_default

Field Type

The type of the field’s expected value.

  • Field name: field_type

For the available field types, see Field types.

Back to top

Field types

Type Description
Integer
  • Field that contains integer values.

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

“field_type”: “integer”
Boolean
  • Field that contains Boolean values.

  • Values: true / false

“field_type”: “boolean”
DateTime
  • Field that contains date and time information.

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

    • 2015-02-25T16:42:11+00:00

    • 2015-02-25T16:42:11Z

  • 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”
Date
  • Field that contains date information.

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

    • 2015-02-25T16:42:11+00:00

    • 2015-02-25T16:42:11Z

    Although the field is defined as Date, we retain the time portion of the date for multi-zonal filtering capabilities on Date fields. This means that with regards to the data representation, the Date and DateTime types are the same. The Date field type exists in order to sign the consumer, and the application uses only the Date portion of the data. (The user interface shows accordingly the Date picker control and not the DateTime picker control.)

  • The date and time is UTC.

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

“field_type”: “date”
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”
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:

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
}

Back to top

Data validation

Data validation enables you to 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.

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

Not Null

Machine generated alternative text:

Machine generated alternative text:
Machine generated alternative text:
Machine generated alternative text:
Machine generated alternative text:
Machine generated alternative text:

Maximum Length

 

 

 

Mandatory

 

 

Unique

Machine generated alternative text:

 

 

Machine generated alternative text:

 

 

Read Only

Machine generated alternative text:

Machine generated alternative text:

Machine generated alternative text:

Machine generated alternative text:

Machine generated alternative text:

Machine generated alternative text:

Final

Machine generated alternative text:

Machine generated alternative text:

Machine generated alternative text:

Machine generated alternative text:

Machine generated alternative text:

Machine generated alternative text:

Minimum Value Mandatory          
Maximum Value Mandatory          
Input data types
Data type Description Field name  Value Example
Not Null Determines whether a null value is allowed. required Boolean “required”: true
Maximum Length Enforces a maximum length of a string field. max_length Integer, >0 “max_length”: 70
Unique Enforces uniqueness on the level of the whole entity type. unique Boolean “unique”: 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
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
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
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

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

      Machine generated alternative text:
Machine generated alternative text:
 
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
}

Note: runs are a technical preview. Until made public, send an HPECLIENTTYPE header with the value: HPE_REST_API_TECH_PREVIEW in your requests.

Back to top

See also: