WorkUnitQuery interface
A JavaScript object implementing the WorkUnitQuery
interface represents a query for WorkUnit
objects and provides access as a read only Array
of WorkUnit
objects.
By default, only open and visible work units are returned.
Construction
Use O.work.query()
. You must either specify which type of work is to be found with the constructor, or call ref()
to restrict the search to work units attached to a specific object.
Usage
First, set up the query with actionableBy()
functions and the like. If you are interested in work units which are not currently open, use isClosed()
or isEitherOpenOrClosed()
.
Execution is implicit when you use the Array
-like interface, such as the length
property or access an element with the []
operator.
The results are sorted so that the newest work units (determined by their createdAt
property) are first in the list.
Performance notes
If you just need the most recent work unit, based on the createdAt
property of the WorkUnit
, calling latest()
will return it from your query without loading all the possible results.
If you use any of the Array
interface, such as length
, all the matching WorkUnit
objects will be loaded. Calling latest()
after this will not make an additional load, but return the first object in memory.
Interface (build query)
Every query function returns the object itself, making the query functions suitable for chaining.
function isOpen()
Find open work units. (default)
function isClosed()
Find closed work units.
function isEitherOpenOrClosed()
Find both open and closed work units.
function createdBy(user)
Find work units created by the user. Either a numeric ID or a SecurityPrincipal
object can be used.
function actionableBy(user)
Find work units actionable by the user. Either a numeric ID or a SecurityPrincipal
object can be used.
Actionable means the actionableBy
property of the work unit is that user, or a group to which the user belongs.
function closedBy(user)
Find work units closed by the user. Either a numeric ID or a SecurityPrincipal
object can be used.
function ref(ref)
Find work units referring to the Ref
.
function tag(key, value)
Find work units which have the tag
specified by the key
and value
. key
must be a String
, and value
must be a String
or null
.
Tag queries treat null
and the empty string as equivalent, matching tags which are not set or have the empty value, for consistency with the countByTags()
function.
function isVisible()
Find work units which are visible. (default)
function isNotVisible()
Find work units which are not visible.
function anyVisibility()
Ignore the visible
property when finding work units.
function deadlineMissed()
Find work units where the deadline
property is in the past.
Interface (results)
acts as Array
A WorkUnitQuery
object acts as a read-only JavaScript Array
. Use the []
operator to read rows.
function latest()
Returns the work unit with the most recent createdAt
property, or null
if the query did not find any results.
function first()
Alias of latest()
function count()
Efficiently count the work units matching this query, without loading them into memory.
function countByTags(tag0, …)
Return a nested data structure containing the counts of all the values of the specified tags in the work units matching this query. Up to four tags may be specified as the arguments to this function.
If a work unit does not have a value for this tag, the empty string will be used as the value.
For example, consider the work units with the following tags:
Tag | one |
two |
Values | "a" |
"b" |
"a" |
"b" |
|
"a" |
"c" |
|
"x" |
(no value for this tag) | |
"x" |
"" |
|
"x" |
"42" |
Then query.countByTags("one")
would return:
{ "a": 3, "x": 3 }
and query.countByTags("one","two")
would return:
{ "a": { "b": 2, "c": 1 }, "x": { "": 2, "42": 1 } }