Reference

Macros and roles

On this page

Roles control who can do things; macros let YAML reference who and what dynamically. They share a syntax — a role is essentially a macro that resolves to one or more users or channels.

Role expressions

A role expression is a comma-separated list of tokens that resolve to a set of users, a set of channels, or both. The same expression syntax is used for roles.*, attribute.viewers, attribute.editors, settings.alert, setAttribute.value, message.to, email.to, and the trigger actions owner, members, alert.

Tokens

TokenMeaning
teamAll team members (excluding external/guest users)
externalAll external/guest users on the activity
@username:{{U-key}}A specific user (encoded form; the editor renders as @username)
#channel:{{C-key}}A specific channel (encoded form; the editor renders as #channel)
${initiator}The user who created the activity
${owner}The current owner
${channel}The activity’s channel
${<attribute>}A user-typed attribute’s value (e.g. ${assignedTo})
${__installer}The user who installed the app (install-time only)
${__channel}The channel the app was installed on (install-time only)
${__blank}Empty value (install-time only — see ${__blank} semantics)

roles block

roles:
  owner: ${__installer}             # default owner is the installer
  members: ${__channel}             # whole channel is members
  admins: team                      # any team member is admin
  superusers: "@alice:{{U-12345}}"  # one specific user
RoleCardinalityUsed for
ownersingle userActivity owner; can edit owner-restricted attributes
membersset of users/channelsParticipants in each activity
adminssetCan edit the app config and any activity
superuserssetElevated privileges (e.g. for approvals; see approval.yaml)

owner is single-user (any expression that resolves to more than one user is rejected during validation). The other three are chat roles (sets).

Combining tokens

members: ${__channel} ${initiator}    # everyone in the install channel + the initiator
alert: "#oncall ${owner}"             # oncall channel + the current owner
viewers: "team,external"              # everyone, including guests
editors: ${owner}                     # only the owner

Separators are whitespace or comma. Whitespace inside {{...}} keys is not allowed.

Install-time macros

Install-time macros (${__installer}, ${__channel}, ${__blank}) are expanded once, when the app is installed (or pasted into the Expert editor). After expansion the YAML stores concrete user/channel references, not the macro.

MacroExpands toNotes
${__installer}@<mention>:{{<user-key>}} (full role form) or @<mention> (as text)The user who installed the app
${__channel}#<name>:{{<channel-key>}} (role form) or <name> (as text)The channel the app was installed on
${__blank}empty stringUsed to opt out of role/alert defaults

Expansion happens when the app is installed on a channel. For each field:

  1. If the field is empty AND there’s a default for the field (e.g. owner defaults to installer, members defaults to channel), apply the default.
  2. Otherwise, if the field contains ${__...}, expand the macros.
  3. The result is stored as the literal value.

${__blank} semantics

A field set to ${__blank} is treated as user-specified empty — the field is cleared and the default is NOT applied. Useful for opting out of default behavior:

roles:
  owner: ${__blank}     # no default owner; the activity starts unowned

Compare to leaving the field unset, which DOES apply the default (installer for owner).

Fields that get install-macro expansion

  • roles.admins, roles.superusers, roles.owner, roles.members
  • settings.alert
  • settings.channelName (as text — ${__channel} becomes the bare channel name, not the role form)
  • settings.errorLog
  • review.members, review.alert, review.ignore, review.include
  • For each attribute: editors
  • For each attribute’s trigger (and each option’s trigger): owner, members, alert

Runtime macros

Runtime macros are resolved every time a value is read or a trigger fires. They reference per-activity context.

MacroResolves to
${initiator}The activity’s creator (user reference)
${owner}The current owner
${channel}The activity’s channel
${title}The activity’s title
${body}The activity’s body
${conclusion}The conclusion text
${status}The status attribute value
${<attribute>}Any custom attribute value
${<attribute>.label}For select attributes: the option’s label
${<attribute>.<sub>}Dotted access for compound attribute values (e.g. ${jira.id}, ${jira.url})

Used in:

  • Attribute defaultValue
  • Attribute display template
  • Trigger actions: setAttribute.value, message.body, email.subject/body/to, alert, etc.
  • settings.channelName template

The result is encoded for where it is used (plain text, Markdown or platform-native).

Examples

Pre-fill an attribute with the activity’s creator

- name: assignedTo
  type: user
  defaultValue: ${initiator}

Alert the owner and a fixed channel

triggers:
  - onCreate:
      - alert: "${owner} #oncall"

Channel name templated per activity

settings:
  mode: channel
  channelName: inc-${title}

Approval app — superusers only

roles:
  owner: ${__blank}                     # no auto-owner
  members: ${__channel}
  superusers: ${__installer}            # installer becomes the first superuser

attributes:
  - name: decision
    type: select
    editors: superusers                 # only superusers can decide
    options:
      - name: approve
        label: Approve
        state: closed
      - name: reject
        label: Reject
        state: closed

- name: jira.id
  type: string
  display: "[${jira.id}](https://acme.atlassian.net/browse/${jira.id})"