Page MenuHomePhabricator

Provide conduit access to related tasks and in particular 'mentions'
Closed, ResolvedPublic


I just noticed that doesn't return the related tasks and in particular the 'mentions'. We are using mentions to group related tasks and our documentation generation tool can use that information, if it's available via conduit, to group the related tasks. Thanks.

Event Timeline

This runs into T5873, which is a large task. The very short version is:

  • Tasks can have an arbitrarily large number of edges (mentions, related tasks, etc) so I don't want to just dump this information into the results by default without support for limiting result sizes and paginating results, since running an innocent and getting back 1GB of data 17 minutes later isn't good. Obviously, this isn't common, but users can make mistakes with bots / API access and extreme cases exist in the wild (for example, T8871 discusses a task that had more than 2,000 comments in 2015 -- who knows how many comments it might have by now!).
  • The underlying store for this data and many other types of similar relationship data ("edges") is generic and fairly straightforward to query in a policy-safe and security-safe way (usually, we just have to check that you can see the object or objects you're running the query on). So it would be nice to do the work to provide a generic that works for all these relationships rather than providing them one-by-one on,, etc. This would also solve the pagination issues.

Unless this is higher priority than the other two requests, let's do T12314 and T12335 first and then I can come back here and plan the pathway forward more clearly. The two major paths are:

  • We may be in a position to build a generic now, since the infrastructure has matured substantially since T5873 was filed and I think there are no major blockers. I believe this path is likely available to us.
  • If a generic approach seems more complicated once I plan it more carefully, we can give you a small piece of extension code which will provide this as an "attachment" for However, it won't support pagination so you may get into trouble some day if a task gets mentioned on 1M other tasks (but hopefully we'll have built a generic solution by then).

sure, I'm fine with letting the dust settle after these changes and deciding then. The approach would be totally fine since I'm writing a custom client, also, the attachment approach would work since our set of related tasks will be small for the foreseeable future.

I've implemented a new API method. This method generally works similarly to other *.search API methods:

Because some edges are internal and not every edge has a human-readable identifier, only some edges (those we've whitelisted and written some help text for) are queryable. Supported edges are listed in the "Edge Types" table on the API method page.

To query edges, pass one or more sourcePHIDs and one or more types. For example, to find object which a task mentions, run a query like this:

  "sourcePHIDs": ["PHID-TASK-..."],
  "types": ["mention"]

Some general notes:

  • Pagination should work, but is a little flimsy because edges do not currently have any sort of unique id column. They'll probably get one eventually.
  • All sourcePHIDs must be of the same type: for example, all tasks. If they aren't, you'll get an error. We may lift this restriction in some future version, but we must run one database query per source PHID type, which is why this restriction exists.
  • As a convenience, you may pass object monograms in place of PHIDs -- for example, T123 instead of PHID-TASK-.... Since the results always use PHIDs and don't identify which objects have which PHIDs, this is probably mostly useful for testing, but is a reasonable shortcut if you're running queries with just one source.
  • Currently supported are: objects mentioned on an object, objects which mention an object, parent tasks, and subtasks. We can add more stuff fairly easily as use cases arise.

I don't suppose users count as objects in this context? I'd love to have a way to be notified of new @mentions for my username. A client app that queries conduit occasionally and sends me desktop notifications, well, that would just be super cool.

Users do count, but I thiiiiiink user mentions are a special kind of mention because they have more complicated rules and you can't read them with today. T4654 discusses better rules around "notify me when I'm mentioned"; there are some related Conpherence-specific tasks too.

epriestley claimed this task.

From elsewhere, it sounds like this is working.