Manage custom fields
Custom fields let you add your own metadata to capture information that matters to your organization. Custom fields apply to jobs.
The metadata your organization needs to track on a job (an owner, a ticket number, a cost center) has nowhere to live, so it ends up crammed into job names or simply isn't captured.
Field types
| Type | Use for |
|---|---|
| Text / Textarea | Short or long free text |
| Number | Numeric values |
| Boolean | Yes/no |
| Select | A fixed list of choices (you provide the Options) |
| Date | A date |
Create a custom field
To define a custom field, complete the following steps:
- Go to Administration › Custom Fields and select New Custom Field.
- Enter a Name (up to 100 characters, unique in your organization) and choose an Input Type.
- For a Select field, add the Options.
- Optionally turn on Required field, give it a Default Value and a Description (up to 500 characters), and set its Display Order. The Default Value input matches the Input Type: On or Off for Boolean, a date picker for Date, a number for Number, one of the Options for Select. A default that does not fit is refused when you save.
- Select Create Custom Field.
What the default does. When a workflow is saved or imported, every job in it that has no value for the field is given the default, so the value travels into every build. The workflow editor's job editor leaves the field empty and names the default in a hint under it (Default: …, applied when you save), and a required field with a usable default counts as filled in. A value someone cleared stays empty, and jobs that already hold a value keep it. Existing workflows pick up a new default the next time they are saved. See How a default reaches a job.
- A Select field must have at least one option.
- Set Display Order to control where fields appear: lower numbers first, then by name. It defaults to 0.
- Custom fields apply to jobs today.
- Keep the set small: the Process View job editor lists only the first 100 definitions.
Edit or delete a custom field
On the Custom Fields page, select a field and then:
- Edit opens it, for one field at a time. Change what you need and select Save Changes.
- Delete removes the fields you selected, after you confirm. You can also delete a field from inside it. Only the fields the list shows are deleted — changing the Input Type filter clears your selection. If a field cannot be deleted, the dialog stays open and names it with the reason, and only the fields that failed stay selected.
What a change does to the values jobs already hold is applied the next time a workflow is saved or imported:
- If you change a field's Input Type, or a Select field's Options, a job's value that no longer fits is kept, and workflows still save while it is untouched. The job editor flags the value — This value is no longer allowed — and a save that changes it to another value that does not fit is refused, naming the job, the field and the value.
- If you mark a field Required field, jobs saved before then still save without a value; a new job, or one whose value is cleared, needs one.
- If you delete a field, its value is removed from each job. The save says so: the confirmation after you commit in the workflow editor lists the removed values, and an API save or import returns a removedCustomFields list.
See A field that changes after jobs use it.
Where the values get filled in
Defining the field is your job; filling it in is the builder's and the operator's. The field appears in a Custom Fields section in both job editors:
- in the workflow editor, on the job definition — this is where a required field is enforced;
- in the Process View, on a job of a build that is already running, where an operator can correct a value mid-run. A required field the build was made with is enforced here too: its value cannot be cleared.
A field you mark required after a workflow has been built is not enforced on that build's jobs. Their values were fixed when the build ran, so there is nothing on the instance to check, and refusing an operator's unrelated edit over it would be unhelpful. The requirement applies to a job definition when somebody adds the job or clears its value. See Where values are set.
Related topics
- Custom fields — full configuration reference and troubleshooting
- Manage permissions (Administrator)