Custom Fields

This chapter focuses on custom fields. Custom fields are extra fields that can be attached to certain entities. The set of such extra fields is defined by per-project configuration, which means for instance that two test cases in two distinct projects may have different custom fields.

Please be careful not to be confused with Custom Field Values : whereas a Custom Field is the abstract definition of a field, a Custom Field Value represents an actual value for that field.

TODO : les différents sous-types etc.

Get all custom fields

A GET to /custom-fields returns all the custom fields.

HTTP request

GET /api/rest/latest/custom-fields?page=1&size=20 HTTP/1.1
Accept: application/json
Host: localhost:8080

Request parameters

Parameter Description

page

number of the page to retrieve (optional)

size

size of the page to retrieve (optional)

sort

which attributes of the returned entities should be sorted on (optional)

fields

which fields of the elements should be returned (optional)

type

which type of the element should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1344

{
  "_embedded" : {
    "custom-fields" : [ {
      "_type" : "custom-field",
      "id" : 1,
      "name" : "checkbox1",
      "code" : "ck1",
      "label" : "ck1",
      "optional" : false,
      "options" : [ ],
      "input_type" : "CHECKBOX",
      "default_value" : "true",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/custom-fields/1"
        }
      }
    }, {
      "_type" : "custom-field",
      "id" : 2,
      "name" : "checkbox2",
      "code" : "ck2",
      "label" : "ck2",
      "optional" : false,
      "options" : [ ],
      "input_type" : "CHECKBOX",
      "default_value" : "true",
      "_links" : {
        "self" : {
          "href" : "http://localhost:8080/api/rest/latest/custom-fields/2"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "http://localhost:8080/api/rest/latest/custom-fields?page=0&size=20"
    },
    "prev" : {
      "href" : "http://localhost:8080/api/rest/latest/custom-fields?page=0&size=20"
    },
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/custom-fields?page=1&size=20"
    },
    "last" : {
      "href" : "http://localhost:8080/api/rest/latest/custom-fields?page=1&size=20"
    }
  },
  "page" : {
    "size" : 20,
    "totalElements" : 22,
    "totalPages" : 2,
    "number" : 1
  }
}

Response fields

Path Type Description

_embedded.custom-fields

Array

the list of elements for that page

page.size

Number

the page size for that query

page.totalElements

Number

total number of elements

page.totalPages

Number

how many pages can be browsed

page.number

Number

the page number

_links

Object

related links

Relation Description

first

link to the first page (optional)

prev

link to the previous page (optional)

self

link to this page

next

link to the next page (optional)

last

link to the last page (optional)

Get custom field

A GET to /custom-fields/{id} returns the custom field with the given ID.

Path parameters

Table 1. /api/rest/latest/custom-fields/{id}
Parameter Description

id

the id of the custom-field

HTTP request

GET /api/rest/latest/custom-fields/3 HTTP/1.1
Accept: application/json
Host: localhost:8080

Request parameters

Parameter Description

fields

which fields of the elements should be returned (optional)

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 313

{
  "_type" : "custom-field",
  "id" : 3,
  "name" : "checkbox3",
  "code" : "ck3",
  "label" : "ck3",
  "optional" : false,
  "options" : [ ],
  "input_type" : "CHECKBOX",
  "default_value" : "true",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/custom-fields/3"
    }
  }
}

Response fields

Path Type Description

id

Number

the id of the entity

_type

String

the type of the entity

name

String

name of the custom-field

code

String

code of the custom-field

label

String

label of the custom-field

input_type

String

the type of custom-field

default_value

String

default value of the custom-field

optional

Boolean

if the custom-field is optionnal or not

options

Array

all the options of the custom-field

_links

Object

related links

Relation Description

self

link to this custom-field

Create custom field

A POST to /custom-fields creates a new custom field.

HTTP request

POST /api/rest/latest/custom-fields HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 210
Host: localhost:8080

{
  "_type" : "custom-fields",
  "name" : "cuf date",
  "label" : "label date",
  "code" : "code date",
  "input_type" : "DATE_PICKER",
  "optional" : true,
  "default_value" : "2020-04-22",
  "options" : [ ]
}

Request fields

Path Type Description

_type

String

the type of the entity

input_type

String

the type of the custom field :DROPDOWN_LIST,PLAIN_TEXT

label

String

the label of the custom field

code

String

the code of the custom field

name

String

the name of the custom field

default_value

String

the default value of the custom field

optional

Boolean

if the custom field is optional or not

options

Array

an array of custom fields

HTTP response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 333

{
  "_type" : "custom-field",
  "id" : 4,
  "name" : "cuf date",
  "code" : "code date",
  "label" : "label date",
  "optional" : true,
  "options" : [ ],
  "input_type" : "DATE_PICKER",
  "default_value" : "2020-04-22",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/custom-fields/4"
    }
  }
}

Response fields

Path Type Description

_type

String

the type of the entity

id

Number

id of the entity

input_type

String

the type of the custom field :DROPDOWN_LIST,PLAIN_TEXT

label

String

the label of the custom field

code

String

the code of the custom field

name

String

the name of the custom field

default_value

String

the default value of the custom field

optional

Boolean

if the custom field is optional or not

options

Array

an array of custom fields

_links

Object

related links

Relation Description

self

link to this custom-fields

Modify custom field

A PATCH to /custom-fields/{id} modifies the custom field with the given id.

HTTP request

PATCH /api/rest/latest/custom-fields/5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 215
Host: localhost:8080

{
  "_type" : "custom-fields",
  "name" : "cuf text",
  "label" : "label text",
  "code" : "code text",
  "input_type" : "PLAIN_TEXT",
  "optional" : true,
  "default_value" : "ceci est un test",
  "options" : [ ]
}

Path parameters

Table 1. /api/rest/latest/custom-fields/{id}
Parameter Description

id

the id of the custom field

Request fields

Path Type Description

_type

String

the type of the entity

input_type

String

the type of the custom field :DROPDOWN_LIST,PLAIN_TEXT

label

String

the label of the custom field

code

String

the code of the custom field

name

String

the name of the custom field

default_value

String

the default value of the custom field

optional

Boolean

if the custom field is optional or not

options

Array

an array of custom fields

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 338

{
  "_type" : "custom-field",
  "id" : 5,
  "name" : "cuf text",
  "code" : "code text",
  "label" : "label text",
  "optional" : true,
  "options" : [ ],
  "input_type" : "PLAIN_TEXT",
  "default_value" : "ceci est un test",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/custom-fields/5"
    }
  }
}

Response fields

Path Type Description

_type

String

the type of the entity

id

Number

id of the entity

input_type

String

the type of the custom field :DROPDOWN_LIST,PLAIN_TEXT

label

String

the label of the custom field

code

String

the code of the custom field

name

String

the name of the custom field

default_value

String

the default value of the custom field

optional

Boolean

if the custom field is optional or not

options

Array

an array of custom fields

_links

Object

related links

Relation Description

self

link to this custom-fields

Delete custom field

A DELETE to /custom-fields/{ids} deletes the custom field(s) with the given id(s).

HTTP request

DELETE /api/rest/latest/custom-fields/2,3 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Path parameters

Table 1. /api/rest/latest/custom-fields/{ids}
Parameter Description

ids

a list id of the custom-fields to delete

HTTP response

HTTP/1.1 204 No Content
Warning
Features about custom field options must be modified.

Add custom field option

A POST to /custom-fields/{id}/options adds option to the custom field with the given id .

HTTP request

POST /api/rest/latest/custom-fields/7/options HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 71
Host: localhost:8080

{
  "label" : "opt1",
  "code" : "code opt 1",
  "colour" : "#ff8000"
}

Path parameters

Table 1. /api/rest/latest/custom-fields/{id}/options
Parameter Description

id

the id of the custom-field

Request fields

Path Type Description

label

String

the label of the custom field option

code

String

the code of the custom field option

colour

String

the colour of the custom field option

HTTP response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 465

{
  "_type" : "custom-field",
  "id" : 7,
  "name" : "cuf ddl",
  "code" : "code ddl",
  "label" : "label ddl",
  "optional" : true,
  "options" : [ {
    "label" : "opt1",
    "code" : "1",
    "colour" : "#ffffff"
  }, {
    "label" : "opt2",
    "code" : "2",
    "colour" : "#ff8000"
  } ],
  "input_type" : "DROPDOWN_LIST",
  "default_value" : "",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/custom-fields/7"
    }
  }
}

Response fields

Path Type Description

_type

String

the type of the entity

id

Number

the id of the custom-field

input_type

String

the input type of the custom-field

name

String

the name of the custom-field

code

String

the code of the custom-field

label

String

the label of the custom-field

default_value

String

the code of the custom-field

optional

Boolean

whe custom-field

options

Array

the custom-field’s options

_links

Object

related links

Relation Description

self

link to this custom-field

Update custom field option label

A PATCH to /custom-fields/{id}/options/{optionLabel}/label/{newValue} modifies the label of the option with given original label .

HTTP request

PATCH /api/rest/latest/custom-fields/6/options/opt/label/opt1 HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

Path parameters

Table 1. /api/rest/latest/custom-fields/{id}/options/{optionLabel}/label/{newValue}
Parameter Description

id

the id of the custom-fields

optionLabel

the label of the option to update

newValue

the new label of the custom-fields

HTTP response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 412

{
  "_type" : "custom-field",
  "id" : 6,
  "name" : "cuf text",
  "code" : "code text",
  "label" : "label text",
  "optional" : true,
  "options" : [ {
    "label" : "opt1",
    "code" : "1",
    "colour" : "#ffffff"
  } ],
  "input_type" : "DROPDOWN_LIST",
  "default_value" : "ceci est un test",
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/api/rest/latest/custom-fields/6"
    }
  }
}

Response fields

Path Type Description

_type

String

the type of the entity

id

Number

id of the entity

input_type

String

the type of the custom field :DROPDOWN_LIST,PLAIN_TEXT

label

String

the label of the custom field

code

String

the code of the custom field

name

String

the name of the custom field

default_value

String

the default value of the custom field

optional

Boolean

if the custom field is optional or not

options

Array

an array of custom fields

_links

Object

related links

Relation Description

self

link to this custom-fields