maniphest_custom.diviner

@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. The supported field types are:
    - **int**: An integer, rendered as a text field.
    - **string**: 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.
    - **user**: A single user typeahead.
    - **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.
  - **checkbox-label**: If type is set to **bool**, an optional string to
    show next to the checkbox.
  - **checkbox-value**: If type is set to **bool**, the value to show on
    the detail view when the checkbox is selected.
  - **default**: Default field value.
    - For **date**, you can use a string like `"July 4, 1990"`, `"5PM today"`,
      or any other valid input to `strtotime()`.
    - For **user** and **users**, you can use an array of user PHIDs.
  - **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.

= 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.