@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-field-definitions` 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(
      'name'     => 'Estimated Hours',
      'type'      => 'int',
      'caption'   => 'Estimated number of hours this will take.',
      'required'  => true,
    ),
    'mycompany:actual-hours' => array(
      'name'     => 'Actual Hours',
      'type'      => 'int',
    ),
  )

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

  - **name**: Display label for the field on the edit and detail interfaces.
  - **type**: Field type. The supported field types are:
    - **int**: An integer, rendered as a text field.
    - **text**: A string, rendered as a text field.
    - **bool**: A boolean value, rendered as a checkbox.
    - **select**: Allows the user to select from several options, rendered
      as a dropdown.
    - **remarkup**: A text area which allows the user to enter markup.
    - **users**: A typeahead which allows multiple users to be input.
    - **date**: A date/time picker.
    - **header**: Renders a visual divider which you can use to group fields.
  - **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.
  - **default**: Default field value.
  - **copy**: When a user creates a task, the UI gives them an option to
    "Create Another Similar Task". Some fields from the original task are copied
    into the new task, while others are not; by default, fields are not copied.
    If you want this field to be copied, specify `true` for the `copy` property.

