Skip to content

Custom fields

Beside its built-in fields, a case can carry fields the project defines for itself — an area, a component, a target release. Suites, runs, plans and steps can have their own too. A field is defined once for the project, in Settings → Fields, and defining one changes no existing case: a case without a value for it simply does not have one.

Settings → Fields shows the fields of one kind of thing at a time: Fields of picks Cases, Suites, Runs, Plans or Steps. A row is the field’s name, its type and its marks — several, required, in the list, in the filter. With no field yet the screen says No fields yet.

Settings → Fields · 3 for Cases: Area (Text · required), Story points (Number) and Component (List · several · in the list · in the filter), each with Edit and Archive; + field at the top right. Settings → Fields · 3 for Cases: Area (Text · required), Story points (Number) and Component (List · several · in the list · in the filter), each with Edit and Archive; + field at the top right.
Three fields of cases, each with its type and marks.

+ field opens New field:

  • Name — up to 100 characters, and no other field of the same kind may have it, an archived one included.

  • Type — one of three:

    TypeA value is
    Texta line of text, up to 1,000 characters
    Numbera number
    Listone of its Options — or, with Several values ticked, any of them
  • Options, on a list: a box per option, + option adds one, × removes one. Up to 100 options of up to 200 characters each; two options with the same label, whatever their case, are refused.

  • Required — a new case cannot be saved without it. See A required field. A step field has no such box.

  • Show in the list and Show in the filter — two switches, each on its own: a field can be offered in the filter without being shown in the list, or the other way round. What each does is in Where the values are and Finding cases by a field.

Save creates the field; Cancel leaves the form.

The New field form: the name Team, the type List with Several values ticked, the options Checkout, Payments and Growth with + option, the boxes Required, Show in the list and Show in the filter left clear, Save and Cancel. The New field form: the name Team, the type List with Several values ticked, the options Checkout, Payments and Growth with + option, the boxes Required, Show in the list and Show in the filter left clear, Save and Cancel.
A list field with three options, before Save.

Edit on a row opens Edit field: the name, the options, Required and the two switches can change. The type cannot, and the form says so — The type cannot change after the field is created. Several values is fixed too. Renaming an option keeps it the same option, so the cases that hold it keep their value under the new label. An option taken off the list stays on the cases that hold it, but it can no longer be picked as a new value.

Archive takes a field out of the forms. It is not a delete — there is none: the field moves under Archived — they keep their values and take no new ones, and Restore brings it back.

A configuration group is a field of a run, but it lives on its own screen, Settings → Configurations, and is not listed here — see Configurations.

A required field is asked for when the thing is made:

  • A case. The form says Area is required. under each empty required field and stops the save with Fill in the required fields: Area. — on a case being edited too, when it has no value yet.
  • A suite or a folder. The dialog that makes one stops the same way.
  • A run. The Manual run dialog (Starting one) says Fill in the required fields before starting: Area. and does not launch.

Through the API a required field is demanded only of a new case, suite, run or plan — 400 · custom field 'Area' is required. On one that already exists, the API only refuses to take the value away: custom field 'Area' is required — its value cannot be cleared. So a field made required later does not stop the cases made before it. A run a reporter starts for automated tests without naming custom is not turned away either: it has no form to fill.

A step field cannot be required: steps are made from a case’s steps when the case is saved, where nothing could ask for a value.

WhatAt most
Live fields of one kind in a project50 — past it, 429: archive one you no longer use first
Options of a list100
Values ticked on a Several values list50
A text value1,000 characters
A field’s name · an option’s label100 · 200 characters
All the values of one case, suite, run, plan or step together16,384 bytes
OfFilled inChanged laterShown
Casesthe form of a new casethe case’s formin the list of cases, for a field with Show in the list
Suitesthe dialog of a new suite or folderFields in the ⋯ of the suite or folder in the treethe same dialog, Fields of its name
Runsthe Manual run dialogthe run’s page, while the run is open or scheduledthe run’s page
Plansthe form of a new planthe plan’s pagethe plan’s page
Steps—Show fields on the step in Settings → Stepsthe same place
  • In the list of cases a field with Show in the list that the case holds a value for is shown beside the case as Area: Checkout — a list by its option labels, several joined by , .
  • On a suite, a run, a plan or a step the values are a Fields block: a name and a value per field, — for none. Edit fields turns it into a control per live field — a box for text and numbers, a select for a list, a tick per option for Several values — with Save and Cancel. A refusal is shown in the server’s own words, such as custom field 'Area' is archived and takes no new value.
  • An archived field still shows the value it holds, and takes no new one.
  • A finished run keeps the values it was started with: the page offers no Edit fields, and the API answers 409 · run '…' is closed. A configuration group shows on the run’s page too, read-only.
  • A step’s values belong to the step of the project’s Steps Database, not to one case.
  • A copy of a case starts with the values of the original’s live fields. A value of an archived field, or an option taken off the list since, stays with the original.
OwnerManagerMemberReader
See the fields and their valuesyesyesyesyes
Define, edit, archive and restore fieldsyesno — 403 · project owner onlyno — 403 · project owner onlyno — 403
Fill in and change valuesyesyesyesno — 403 · read-only member

A manager, a member or a reader sees Settings → Fields as a list, with Only the project owner defines fields. and no buttons. A reader opens a suite’s Fields dialog and the Fields blocks, with no Edit fields.

Filters on the list of cases has, after its own sections, a section for each live case field with Show in the filter, named after the field. A list is a pick of its options; a text or a number field is one box, Value. A value applied is a chip — Area: Checkout.

In the page’s address and in GET /v1/test-cases the parameter is custom, a field’s id and the value with a colon between them (%3A in a link):

GET /v1/test-cases?custom=<fieldId>:<value>
  • The same value, nothing else. A text field matches the whole text as written, a number field the same number, a list field the option — by its id, not its label. There are no ranges and no part of a text: “more than 5” or “starts with Check” cannot be asked.

  • Repeat it for “any of”. custom=<id>:<a>&custom=<id>:<b> is a case holding either value; two different fields, or a field and another parameter, are “all of”.

  • The value is read by the field’s type. The filter does not look up the field: it tries the value as text, as an option’s id and, when it is a number, as a number, and only the reading that fits the field can match. A field id or a value nobody holds is not refused — it matches no case.

  • A pair without its colon is refused, with the form it expects:

    400 · unknown custom "nocolon" — the forms of custom are <fieldId>:<value>

    The field id ends at the first colon, so a value may hold colons of its own.

A field’s id, and the ids of its options, are in GET /v1/custom-fields?entity=case.

The Runs list does the same for run fields with Show in the filter: a select for a list field, a Value box for the others, and GET /v1/runs?custom=<fieldId>:<value> on the API.

Export XLSX writes a column for each case field after the built-in columns, headed Field: and the field’s name — Field: Area. A list’s value is its option labels, several joined by , ; a number and a text are as written. An archived field gets its column only while a case in the sheet still holds a value for it. The fields of suites, runs, plans and steps are not in the sheet.

Imported back, the sheet leaves the Field: columns out: the values do not come back, and a field named Priority is never read as the case’s priority.

  • GET /v1/custom-fields — the project’s fields; ?entity=case (or suite, run, plan, step) narrows to one kind, ?archived=true adds the archived ones. Any member of the project reads it.

  • POST /v1/custom-fields, PATCH /v1/custom-fields/{id}, POST /v1/custom-fields/{id}/archive and /restore, and PUT /v1/custom-fields/order with every live field of a kind in the order wanted — the owner’s alone, 60 a minute each:

    { "entity": "case", "name": "Area", "type": "list", "options": [{ "label": "Checkout" }, { "label": "Search" }], "showInFilter": true }

    type is string (Text), number or list; multiple: true is Several values. A field can also have a defaultValue, which a new case, suite, run, plan or step gets when it does not name the field — the API’s alone, Settings → Fields has no box for it. entity, type and multiple are refused on a PATCH: type cannot be changed after the field is created. A name already taken answers 409.

  • The values travel as custom on the thing itself — POST and PATCH of /v1/test-cases, /v1/suites, /v1/runs and /v1/plans, and PATCH /v1/settings/steps/{id} — an object of field id → value: the text, the number, an option’s id, or a list of option ids for Several values.

    { "custom": { "<field id>": "<option id>", "<another field id>": 3 } }

    In a PATCH a field left out keeps its value and null takes it away. A value that does not fit its field is refused and named: custom field 'Area': 'x' is not one of its options, custom field 'Estimate' takes a number, unknown custom field '…'.

Every route, with its fields and answers: the API reference.