Phabricator/Help/Forms

Forms in Phabricator
New content is entered into Phabricator primarily by filling out forms. The forms can be customized in various ways and custom forms can be saved for specialized use-cases. Forms are explained in the official Phabricator documentation topic User Guide: Customizing Forms

Some examples of custom forms used by the Wikimedia Foundation include the following:
 * Report Security Issues for security-related bug reports
 * Create Access Request for requesting shell access to the Wikimedia production cluster.
 * Request Wiki Config Change for requesting changes to a wiki's configuration

"Create Forms" vs "Edit Forms"
Phabricator differentiates between "Create forms" and "Edit forms" - essentially all forms can be used to create a task, however, only forms marked as "Default Edit Forms" will be used when editing a given task.

The way phabricator determines which form to show when editing any given task is quite complex and it's based on the project membership of the user who is doing the editing.


 * 1) Consider all forms marked as "edit forms"
 * 2) With a subtype that matches the type of the task
 * 3) That are visible to the current used (based on the view policy applied to each form)
 * 4) Show the one with the highest priority according to the order which is configured on the maniphest.task edit engine configuration interface (Click "Reorder edit forms")

Creating custom forms
Phabricator allows Phabricator administrators to create custom forms for task creation and editing. Upstream documentation is available and a custom form just to demonstrate the possibility is available.

Some likely use cases include:


 * Custom markup at the top of forms
 * Pre-filling information in fields
 * Hiding certain fields and changing the order in which they appear
 * Bug reporting and template tasks can be entered more easily
 * Specialized workflows involving custom fields specific to a particular type of task or process.

A great deal of caution is required when using this new functionality. Form creation is limited to administrators because it is currently too easy to accidentally override existing forms when someone creates a new form without fully understanding the subtleties of the new system. Anyone with a use-case for a custom form can request that one be set up by Phabricator administrators. We have not established a formal process for this yet.

Task Types (aka "Subtypes")
Different types of tasks can have different fields that describe details which are unique to a given type. For example:


 * Release tasks have a release date.
 * Deadlines have a due date.
 * Log error reports can have an error id, URL and stack trace.
 * Security Issues have a severity, affected hosts.

What determines the type of a task
The type of a task is initially determined by the form that was used to create the task. The type of a task can be changed manually by some users (via the "Add Action… → Change Subtype" dropdown) and also via automated edits when a task matches a specific Herald rule.

Different edit forms are associated with each task type so that the appropriate fields are shown when editing tasks of a custom type.

Generally users should not modify the type of a task unless there is a very specific reason for doing so. The maintenance of task types is best left to Phabricator administrators and experienced project managers.

Favorites Menu
There are other specialized forms and some are used by small groups of people so it doesn't make sense to clutter the interface with forms that are not used by the majority of users in Phabricator. This consideration has lead to the development of the Favorites menu. The Favorites menu can be customized by each user according to their needs. This menu is accessed by clicking the Bookmark button which is near the upper right corner of the Phabricator interface, just to the left of the user menu and search box.

Adding forms to your Favorites
You can add any available form to your favorites menu for easy access from anywhere inside Phabricator. To edit your favorites menu, visit the favorites editor which can be accessed by clicking "Edit Favorites" at the bottom of the favorites menu.

To add a form, click the link labeled "+ Form" in the menu on the right side of the page. This will present a dialog with two fields, "Form" and "Name." You can select a form by typing into the "Form" field or by clicking the browse button (magnifying glass icon) on the right side of the dialog. Browsing is easier if you do not already know the name of the form you want to add. That will bring up a dialog with a list of all available forms for you to choose from.

Once you have selected a form you can optionally enter an alternate name for the form, otherwise the default name will be used.

Finally, click the blue button labeled "Create menu item" to finish adding the form to your favorites menu.