Custom Fields

Custom Fields in Valispace - API Documentation

Introduction

In Valispace, Custom Fields provide a powerful way to extend the platform's functionality by allowing users to create additional fields associated with requirements and test runs. These fields can store various types of data, such as dates, text, and selections. This API documentation outlines the process for creating, updating, and managing Custom Fields and their options programmatically.

Definition of Custom Fields

Custom Fields in Valispace can be created using the /data/custom-field/ endpoint with the following syntax:

JSON

CustomField{
  "projects": [uniqueItems: true integer],
  "target_content_type": integer,
  "name": string,
  "type": integer,
  "multi": boolean
}

projects: List of project unique identifiers where the Custom Field should be available.
target_content_type: The target content type for the Custom Field. Use 120 for requirements and 291 for test runs.
name: The name of the Custom Field.
type: Use 0 for Text, 1 for Selection, and 2 for Date.
multi: Set to true for multi-selection when defining a Selection type.

Creating Custom Fields

To create a Custom Field, use the PUT method for the endpoint /data/custom-field/. For example:

JSON

{
  "projects": [136],
  "target_content_type": 120,
  "name": "New Selection Column",
  "type": 1
}

Definition of Custom Field Options

When creating Custom Fields of type Selection, you must also define the available options using the /data/custom-field-options/ endpoint with the following model:

JSON

CustomFieldOption{
  "custom_field": integer,
  "titlename": string,
  "position": number
}

custom_field: The unique identifier of the Custom Field for which the option is being created.
titlename: The name of the option.
position: Optional field to define the position of the option in the options list.

Creating Custom Field Options

To create a Custom Field Option, use the PUT method for the endpoint /data/custom-field-options/. For example:

JSON

{
  "custom_field": 58,
  "name": "New Option"
}

Adding Data to Custom Fields

To add data to a Custom Field, use the /data/custom-field-row/ endpoint with the following model:

JSON

CustomFieldRow{
  "referenced_object_id": integer,
  "custom_field": integer,
  "value": string
}

referenced_object_id: The unique identifier of the object (requirement or test run) to which the data belongs.
custom_field: The unique identifier of the Custom Field to which the data is being added.
value: The data to be added. For Text, use a free text string; for Single Selection, use an option id; for Multiple Selection, use a list of option ids; for Date, use a date in string format.

Adding Data to Custom Fields - First Time Entry

For the first time entry of data to a Custom Field of a given object, use the POST method for the endpoint /data/custom-field-row/bulk-create/. For example:

JSON

{
  "referenced_object_id": 33803,
  "custom_field": 58,
  "value": 29
}

Updating Data in Custom Fields

To update existing data for a Custom Field of a given object, use the POST method for the endpoint /data/custom-field-row/bulk-update/. For example:

JSON

{
  "614": {
    "value": 30
  }
}

Removing Data from Custom Fields

To remove data associated with a given Custom Field and object, use the same bulk-update method with "value": null. For example:

JSON

{
  "614": {
    "value": null
  }
}

Conclusion

Custom Fields in Valispace allow you to enhance the platform's capabilities and tailor it to your specific project needs. By using the provided API endpoints, you can create Custom Fields, define options, and add data programmatically, making Valispace a versatile tool for your project management and analysis requirements.