Team Practices Group/Phabricator tips/Maniphest

This is a brief walkthrough of the Phabricator search feature, Maniphest.

Overview
Maniphest can be found on your home page, in the navigation bar on the left.

Inside Maniphest, custom, saved searches and advanced search options are on the navigation bar.

Queries/Searches in Maniphest
Maniphest allows users to search for tasks using multiple data fields. Some fields allow for complex queries using Typeaheads (more on those below). To create a new search, click on "Advanced Search". Enter a few details to look up a new set of tasks and click "Search". Results will appears in a list below the advanced search UI. If you want to save this search, select the "Save Custom Query" button at the bottom of the Advanced Search UI. Note: once you save a search you cannot edit the parameters again but you can rename the search.

Selecting Dates and Date Ranges
Using the Date fields like "Created After" and "Created Before" can be rather difficult. The fields are very sensitive and do not give autocomplete options or hints.

Absolute Dates
If you want to search using an absolute date the you must write in this format: Month/Day/Year

Example:
 * "02/25/2015"

NOTE: This might be helpful if you want to look up tasks created after the start of a project (or a sprint).

Relative Dates
You can also use a relative date. Let's say you want a query that will always look up anything that was created in the last 5 days. There are two ways you can do this.

Example 1:
 * "5 days ago"

Example 2:
 * "2:45 AM 5 days ago"

''NOTE: This might be helpful if users are constantly putting new tasks in your backlog. If you have a search like this, you could come in every day and scan this query to see if anything new entered the backlog''

Note on UTC and counting days in Maniphest
Please note that Maniphest uses UTC. You must be aware of where the UTC date line occurs relative to your time zone. You could accidentally lose or gain a day in your searches. Here are examples of how Maniphest interprets searches.

Examples:
 * "02/25/2015" is interpreted as "12:01 AM on February 25th, 2015" (UTC)
 * "5 days ago" is interpreted as "12:01 AM on the fourth calendar day before today" (UTC)
 * "2:45 AM 5 days ago" is interpreted as "12:01 AM on the fourth calendar day before today" (UTC)

The "X days ago" range can seem really confusing. Phabricator interprets today as part of any data set. Even if it is 12:30 AM UTC, Phabricator will interpret that as a potential day in the range.

Example:

Let's say it is currently January 15th, 2015 at 9 AM UTC. You want to know if any tasks were created in the last 5 calendar days. If you write in "5 days ago" in the "Created After" field, you will get the tasks created starting on 12:01 AM 01/11/2015.

Problems with "Updated" fields
The "Updated After" and "Updated Before" fields return any and all changes to a task. For example, when a task is moved to another column in a board it registers as "updated". Some teams may find this valuable. However this may add noise to your data set. You should consider this when using these fields.

Typeaheads (AKA autocomplete)
Some fields in Maniphest have a feature called "Typeaheads". Typing in an expected piece of data will bring up a list of options under the data field. These extra options allow the user to create complex queries. The example below shows several options when attempting to type the project "Fundraising Backlog". The user can click on one of the menu items to add the desired string of text to the data field. Several typeaheads can be combined to create a complex query.

Here are a few common typeahead prefixes and their meaning:
 * "In Any:" indicates a data type is optional
 * "Not in:" indicates a data type should not appear on a task in the query
 * A box with a colored background and an icon (and no prefix) indicates a data type is required

Let's examine the typeaheads below to see what they mean in a query. Here we are searching against 3 boards in Phabricator: "Fundraising Tech Backlog", "Fundraising Sprint Miles Davis", and "Fundraising-Backlog"

The tasks in this query COULD be in the "Fundraising Tech Backlog". They SHOULD NOT be in the "Fundraising Sprint Miles Davis". They MUST be in the "Fundraising-Backlog".

Autocomplete limit
There's a limit of 5 items in the maniphest autocomplete. To increase this limit, see these userscripts for Chrome and for Firefox.

Saving and Managing Searches/Queries
As stated before, queries can be saved and managed inside Maniphest. When looking at the main navigation in Maniphest, click on the "Edit Queries" link. You will see a list of your saved queries. All users have a default set which can be deleted in this UI.

Some options in this UI
 * Use the line elements on the left to drag queries up and down in the list.
 * The "x" will permanently delete a Query.
 * The Pencil icon allows a user to edit the name of a query
 * Clicking on the name of a Query will bring up the search options and results of that query

Please note: Once you save a query, you cannot change its parameters, but you can change its name. To edit a query, click on it's name, change parameters and save it as a new query. Also, Phabricator allows users to save multiple queries with the same name. TPG recommends you form your own naming conventions to keep your list organized.