Skip to content

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