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
    }
}