Searching Activity

This feature is currently in beta and we’ve been actively porting our frontend to use our API over CORS. Our long-term vision is that our frontend and our customers’ API applications use identical endpoints.

The new Activity API has three endpoints.

  •  /api/activities/search.json - Includes activity entries across all products.

  •  /api/products/{product_id}/activities.json - Includes activity entries for a single product.

  • /api/products/{product_id}/items/{item_number}/activities.json - Includes activity entries for a single item.

All endpoints accept the the following arguments:

  • q – The query you’d like ran (e.g. “dashboard bug”). This item is optional. Querying with an empty query string will return all items for all products the requesting user is a member of.

     

  • sort – Which field to order results by. By default, we return the best match according to the search index.

  • order – Which order to sort the results in (asc or desc).

  • offset – Which record in the result set to start at. Defaults to 0.

  • limit – How many records to return starting from offset. Defaults to 250.

The search query syntax supports a number of fields for filtering. These fields work by showing activity entries that belong to items that match these filters. The following fields can be appended to your query specified in q to either filter results for keywords in q (e.g. design -tag:mobile) or as values in the facets argument:

  • assignee – Filter items assigned to the user ID specified (e.g. assignee:1)

     

  • author – Filter items created by the user ID specified (e.g. author:1)

  • accepted_by – Filter items accepted by the user ID specified (e.g. accepted_by:1)

  • loved_by – Filter items that have been favorited by the user ID specified (e.g. loved_by:1)

  • mentioning – Filter items that mention the user ID specified (e.g. mentioning:1)

  • team – An item’s team consists of anyone who has had a meaningful interaction. Anyone that favorites, follows, comments on, is mentioned in, or uploads an attachment to is added to an item’s team along with the creator, any assignee, and acceptor. Rather than using loved_by:1 mentioning:1 assignee:1, you could use team:1.

  • blocks – Filter for items that are blocking the user ID specified (e.g. blocks:1)

  • title – Filter for items whose title matches the search terms specified. title:"dashboard"would filter for items whose title matches the phrase “dashboard”.

  • description – Filter for items whose description matches the search terms specified. description:"firefox" would filter for items whose description matches the phrase “firefox”.

  • product – By default all queries will return all items for any product the requesting user has access to. To filter items by a specific product, or products, you use the product ID (e.g. product:1 for just product ID 1’s items or product:1 product:4 for both product ID 1 and 4’s items).

  • favorites – Filter for items with a given number of favorites (e.g. favorites:>0).

  • blocking – Filter for items that are blocking a given number of items (e.g. blocking:>0 would return items blocking at least 1 other item).

  • blockers – Filter for items with a given number of blockers (e.g. blockers:>2 would return items with more than 2 blockers).

  • status – Filter items for a given status. Valid values are someday, backlog, in-progress, completed, and accepted (e.g. status:backlog status:in-progress would return all items that are in the Backlog or Current columns).

  • type – Filter for items of a given type. Valid values are task, story, defect, and test.

  • size – Filter for items with a given size estimate. Valid values are ~, S, M, L, and XL.

  • has – Items possess a number of qualities; this field allows you to query for items that possess a certain quality. For instance, you might be looking for stories that have sub-items. type:story has:children would get you what you want. We assess each item with a number of these possessive qualities:

    • moved – Whether the item has been moved to another product or not.

       

    • pr – Whether the item has had a PR issued against it.

    • commit – Whether or not an item has had a commit pushed relating back to it.

    • attachment – Whether or not an item has one or more attachments.

    • comment – Whether or not an item has one or more comments.

    • favorite – Whether or not an item has been favorited.

    • children – Whether an item has sub-items or not.

    • tag – Whether or not an item has one or more tags.

    • estimate – Whether or not an item has been assigned a size estimate.

  • is – Items also have a number of qualities related to its state. The is facet allows you to filter an item’s state attributes. For instance, is:duplicate will return any item marked as a duplicate while is:unassigned will return any item lacking an assignee. We assess each item with a number of these state attributes:

    • duplicate – Whether or not the item is a duplicate of another item.

       

    • duplicated – Whether or not one or more items has been marked as a duplicate of the item.

    • blocked – Whether or not the item is currently blocking another item.

    • blocker – Whether or not the item is a blocker for one or more items.

    • unassigned – If the item does not currently have an assignee.

    • assigned – If the item does have an assignee.

    • child – If the item is a sub-item.

  • parent – Filter for items with the given parent. parent:55 would return any item whose parent is #55. Keep in mind the API is cross-product by default and ticket numbers are not globally unique. This mean it is possible to get sub-items for two parents that share the same number.

  • number – Filter for items specifically by their number. Again, ticket numbers are not unique across product so it’s entirely possible number:1 would return more than one ticket for customers that are members of multiple products.

  • tag – Filter for items by a specific tag. This is an OR operation grouped by modifier. In other words tag:foo tag:bar will return items tagged either “foo” OR “bar”, while tag:foo tag:bar -tag:baz -tag:bitz would return items tagged with either “foo” OR “bar” AND are NOT tagged with “baz” OR “bitz”.

  • created – Filter for items that were created before or after a given date. Date fields support >, <, >=, and <= as well. Try created:>=2014-01-01 to find all items created on or after January 1st, 2014.

  • triaged – Filter for items that were triaged (moved from Someday to Backlog) before or after a given date.

  • started – Filter for items that were started before or after a given date.

  • closed – Filter for items that were closed before or after a given date.

  • accepted – Filter for items that were accepted before or after a given date.

  • last_active – Filter for items that were last active before or after a given date.

  • modified – Filter for items modified before or after a given date.

  • who – Filter for stories whose who field matches the search terms specified. who:"paying customer" would filter for items whose who field matches the phrase “dashboard”. You can also facet by this field to get a breakdown of stories by the who field.

  • what – Filter for stories whose what field matches the search terms specified. what:"dashboard" would filter for stories whose what field matches the phrase “dashboard”.

  • why – Filter for stories whose why field matches the search terms specified. why:"use firefox" would filter for stories whose why field matches the phrase “use firefox”.

All of the above facets allow for negative querying. To apply a negative facet simply add - to the front of the facet name (e.g. -tag:foo would return activity for items that are not tagged with “foo”). This is particularly interesting when you consider the has and is facets. For instance -has:pr would return any activity for an item that does not have a PR issued against it. You can, of course, do -keyword or -title:"some phrase".

The API is JSON only and returns the following arguments:

  • q – The query as parsed by the backend. I would give our query parser a solid B- right now; there’s for sure some edge cases that may not work. Please let us know on Twitter if you have a query mis-match. We’re logging them in Kibana as well to keep an eye on any issues.

     

  • total_count – The total number of items that matched the given query.

  • activities – A list of activity objects.

It’s important to note a few things about the way search works:

  • Keywords and search phrases are special. Unlike other facets, they are grouped with an AND as opposed to an OR. In other words foo "my stuff" matches foo AND "my stuff" while assignee:1 assignee:2 matches assignee:1 OR assignee:1.
  • The + modifier is implied. No need to do +tag:foo +tag:bar.

  • It is possible to create nonsensical search queries, such as is:child has:children, which would never return results because our data model doesn’t allow sub-items to have sub-items. Use your newfound powers responsibly.

  • The API returns total_count and allows offset and limit. This should make pagination reasonably easy to implement.

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.
Powered by Zendesk