Dispatch

Query format

The query format starts with the specific items to query for followed by the details of the query.

Qualifier* Range? Search? Sort? Limit? Status?

Qualifiers are separated by comma which acts as a logical OR so that the result contains the combination of all the qualifiers provided.

Results are returned either as a Range or if no range is provided as a Stream. Range results will be the specific start and end requested sorted ascending while Stream will return the current date descending for up to one year.

Examples

all users

given trackers [notes] from today as year

given swimlanes [announcements] from today to -2 weeks

Qualifiers

Qualifiers identify what data to return. They can be combined together to bring back several different kinds.

Syntax

qualifier1, qualifier2, ...

Keywords

Qualifier	Definition
`all users`	Return all users
`given users [<uid>\|<email>\|$context,*]`	Just specific users
`given author [<uid>\|<email>\|$context,*]`	Just specific authors
`current user`	The current user
`current user [cohort\|program\|following\|followers]`	Users based on their relation to the current user
`given\|except groups [<uid>\|<handle>,*]`	Including or excluding specific groups
`given\|except user-labels [<handle>,*]`	Users with a specific label
`given programs [<uid>\|<handle>,*]`	Users who are in a specific program instance
`given program-kind [<uid>\|<handle>,*]`	Users that have taken a program kinds
`given program-kind-active [<uid>\|<handle>,*]`	Users currently active in a program kinds
`given cohorts [<uid>,*]`	Specific cohorts
`all swimlanes`	All swimlanes
`given\|except swimlanes [<uid>\|<handle>,*]`	Specific swimlanes
`given shares [<uid>,*]`	Specific global swimlane shares
`given\|except dispatch-labels [..handle list]`	Dispatch labels

Client side replacements for uid / email lists: * $user = the user being displayed * $span = a time span if applicable * $cohort|$program = cohort or program id * $start|$end = start or end date if applicable * $date = anchor date for a view

Server side replacements for uid / email lists: * $context = the logged in user

Trackers

Qualifier	Definition
`given trackers [...]`	Return specific trackers
`except trackers [...]`	Return all trackers except the specific trackers
`given tracker-group [...]`	Return all trackers from a specific group
`no trackers`	Return dispatches without trackers
`.. on user\|swimlane`	Narrow the above to just users or just swimlanes

Range

Range specifies the time frame to retrieve. If not provided it returns from today backwards up to either the limit or one year.

Syntax

from [date] to [date]
from [date] to [measure] [period]
from [date] as [period]
from [measure] to [measure] [period]
from today|past|future|all time

Measures: +/- number
Dates: YYYY-MM-DD (2020-08-01) or YYYY-MMM-DD (2020-Aug-1) or YYYY-MMM (2020-Aug) or today
Periods: day, week, isoWeek, month, year
Periods can be plural for greater readability

Examples

from today as week
from 2020-01-01 as month
from today to +3 weeks
from -1 to +6 months
from all time

Security

By default public and org security are returned. To retrieve other security levels provide a security clause. Note that in user mode the security clause will be overridden by the actual permission level.

given security [..opts]
all security
opts: public, private, admin, org

Events

Events - filter by dispatch event status.

given events Events* Payload? [..user|email list]
Events: answer|confirm|like|bookmark|
process|participant|leader|organizer
Payload: yes, no, undecided

Example

given event participant [$context]

Search

Search allows the query to narrow results based on some criteria.

where [entity] [operator] "literal" [conjunction]?
entity: body | state
operator: contains, starts, ends, is, not
conjunction: and | or

Sort

Sort the resulting dispatches either ascending or descending. Range defaults to ascending while stream defaults to descending.

asc|desc 
asc|desc created|updated|when

Limit

Limit the number of returned records. Note that many UI components have a default limit so this can be used to raise the number of records returned.

limit [Number]

Status

Return dispatches with a specific status.

status in [active, draft]

More examples

all swimlanes

all users from today to +7 days

all users from -7 to +7 days

all users from today as day

given labels[public]

all users where body is "hi"

given events bookmark [$context]