Phabricator/Help/Forms

Forms in Phabricator

New content is entered into Phabricator primarily by filling out forms. Forms can be customized in various ways and custom forms can be saved server-side for specialized use-cases. Forms are explained in the upstream Phabricator 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

Favorites Menu

Example screenshot of the Phabricator 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.

• Visit the Favorites editor which can be accessed by clicking "Edit Favorites" at the bottom of the favorites menu.
• 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."
• 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.
• Select a form.
• Optionally you can enter an alternate name for the form, otherwise the default name will be used.
• Finally, click the blue button labeled "Create Menu Item" to add the form to your favorites menu.

Phabricator administrators can also make a form visible to specific group of people (e.g. ACL projects or members of some project tag).

Pre-filling forms

One quick way to pre-fill a task creation form with default values (outside of Phabricator) is creating a link with URL parameters. This requires no special permissions in Phabricator.

Anyone can create and share links with values for any form field encoded in the URL. People who use your link will get a pre-filled form that they can complete and submit to create a task. This is generally used to create prototype forms.

You can customize almost every field of a maniphest task form. For more info, see Phabricator/Help/Task Creation URL.

To have values pre-filled server-side, in Phabricator, see the section #Creating custom forms.

Creating custom forms

For more customization beyond what is possible with pre-filling forms by passing URL parameters, Phabricator administrators can create custom forms for task creation and editing. Upstream documentation is available and a custom form just to demonstrate the possibility is available.

If you need a custom form, create a task to request a custom form and explain your use-case. A Phabricator admin will take a look.

If you regularly need to create or edit forms, create a task to request being added to phab:tag/acl*phabricator/ and elaborate.

Some of the possibilities include:

• Custom markup at the top of forms
• Pre-filling information in fields
• Hiding or locking certain fields and changing the order in which they appear (however, hidden or locked fields cannot be pre-filled by passing URL parameters to a form)
• Specialized workflows involving custom fields specific to a particular type of task or process.

A great deal of caution is required when using this functionality. Form creation is limited to administrators and members of phab:tag/acl*phabricator/ because it is too easy to accidentally override existing forms when someone creates a new form without fully understanding the subtleties of how forms interact with other Phabricator features. We have not established a formal process for this yet.

"Create" vs "Edit" Forms

It's important to understand the distinction between "Create" and "Edit" forms when making changes to custom forms because of how this affects phabricator's behvior.

• Despite the naming, all forms can be used to create a task.
• Only those forms marked as "Create forms" are shown in the +Create Task dropdown menu.
  • Do not mark a form as a Create form if it is not of general interest to every Phabricator user. See #Adding forms to your Favorites instead.
• A form can be marked as both "Create" and "Edit" at the same time.
• Only those forms marked as "Edit" forms can be used to edit pre-existing tasks.

There are several factors that determine which form is used to edit any given task. The choice of form is affected by the task type, the form's priority as well as the project membership of the user who is doing the editing. For a form to be used, it must meet all of the following conditions:

1. Marked as an "edit" form
2. Type must match the task
3. It must be visible to the current user (based on the view policy applied to each form)

When there are multiple forms which meet all of the above conditions, task editing will use the form with the highest priority. Priority is configured on the maniphest.task edit engine configuration interface (Click "Reorder edit forms")

Task Types (aka "Subtypes")

As of May 2020, the following task subtypes exist: Task, Bug Report, Feature Request, Spike, Design, Deadline, Release, Goal, Administrative Request, Security Issue, Production Error. Task subtypes are disjunctive, a task can only have one subtype.

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 and version number.
• Deadlines have a due date.
• Log error reports can have an error id, URL and stack trace.
• Security Issues have a severity, affected hosts.

Each custom form can apply to exactly one task type. For each subtype that is defined, there must be at least one form marked as an "edit" form and assigned with the corresponding subtype. The reason for this is as follows: when editing a task with a subtype, Phabricator looks for a form with the matching subttype. If there is no form for a given subtype, then an error occurs and the task cannot be edited.

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.

The separate edit forms associated with each task type control what 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.

Further Reading

See also this blog post introducing the task types feature.