Article Maniphest User Guide: Adding Custom Fields

Defined	src/docs/userguide/maniphest_custom.diviner:1
Group	Application User Guides

Table of Contents

Overview
Simple Field Customization
Advanced Field Customization

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 ManiphestAuxiliaryFieldSpecification and implement your specialized rendering, validation, storage, etc., logic.
Extend 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.