@title Maniphest User Guide: Adding Custom Fields
@group userguide

How to add custom fields to Maniphest.

= Overview =

Maniphest provides some support for adding new fields to tasks, like an
"cost" field, a "milestone" field, etc.

NOTE: Currently, these fields are somewhat limited. They primarily give you a
structured way to record data on tasks, but there isn't much support for
bringing them into other interfaces (e.g., querying by them, aggregating them,
drawing graphs, etc.). If you have a use case, let us know what you want to do
and maybe we can figure something out. This data is also exposed via the Conduit
API, so you might be able to write your own interface if you want to do
something very custom.

= Simple Field Customization =

If you don't need complicated display controls or sophisticated validation, you
can add simple fields. These allow you to attach things like strings, numbers,
and dropdown menus to the task template.

Customize Maniphest fields by setting ##maniphest.custom-fields## in your
configuration. For example, suppose you want to add "Estimated Hours" and
"Actual Hours" fields. To do this, set your configuration like this:

  'maniphest.custom-fields' => array(
    'mycompany:estimated-hours' => array(
      'label'     => 'Estimated Hours',
      'type'      => 'int',
      'caption'   => 'Estimated number of hours this will take.',
      'required'  => false,
    ),
    'mycompany:actual-hours' => array(
      'label'     => 'Actual Hours',
      'type'      => 'int',
      'required'  => false,
    ),
  )

Each array key must be unique, and is used to organize the internal storage of
the field. These options are available:

  - **label**: Display label for the field on the edit and detail interfaces.
  - **type**: Field type, one of **int**, **string** or **select**.
  - **caption**: A caption to display underneath the field (optional).
  - **required**: True if the user should be required to provide a value.
  - **options**: If type is set to **select**, provide options for the dropdown
    as a dictionary.

= Advanced Field Customization =

If you want to add fields with more specialized validation, storage, or
rendering logic, you can do so with a little work:

  - Extend @{class:ManiphestAuxiliaryFieldSpecification} and implement
    your specialized rendering, validation, storage, etc., logic.
  - Extend @{class:ManiphestTaskExtensions} and return a list of fields which
    includes your custom field objects.
  - Set 'maniphest.custom-extensions' to the name of your new extensions
    class.

This is relatively advanced but should give you significant flexibility in
defining custom fields.