Macro Substitution

Macro substitution lets you insert variables into an app during runtime execution, where ${variable} will be replaced with the actual value of the variable.

Let’s first look at some common cases that illustrate the use of macros.

Example: Set a custom channel name
channelName: "_bug-report_${YYYY}-${MM}-${DD}-${title}"

If somebody reports “Database error” on November 15, the channel name of the bug report will be “_bug-report_2020-11-15-database_error”. Conclude automatically translates space and other illegal channel name letters to underscore.

Example: Invite the initiator
members: "#requests ${initiator}"

This will invite the initiator (the person who submitted a request for approval) to become a member of the activity channel. This technique is used by the ‘approval’ template.

Example: Set a default attribute value
  - name: conclusion
    type: text
    label: Resolution
    defaultValue: "${bug_status.label}"
    placeholder: What was the resolution?

The ‘bug’ template sets the resolution (conclusion) text to the value of the bug_status select dropdown.

Macro substitution is context sensitive

Macro expansion knows the context, and the substituted value depends on the context in which the macro is used.

For example, ${initiator} will expand to different values depending on the context:

  • As a Slack alert or message: converted to a Slack user reference.
  • In the To/Cc: of an email: The email address of the initiator.
  • In the body text of an email: The full name of the initiator.

Role-based macros

${initiator}The user who created the activity.
${owner}The owner of the activity.
${members}The members of the activity.
${admins}The admins of the app.
${superusers}The superusers of the app.

For initiator and owner you can choose how to represent the user by adding a suffix:

  • .firstname or .lastname to display the first or last name.
  • .mention to display the name like Slack shows it.
  • .email to display the email address of the user instead of the name.
  - name: title
    type: string
    label: Expense report
    defaultValue: "Submitted by ${initiator.firstname}"

Attribute macros

${attribute}Expands to the attribute value. Examples:e ${title} or ${conclusion}
${attribute.label}Expands to the label of a select attribute. Example ${severity.label}

Date and time macros

${YYYY}The current year (4 digits).
${YY}The current year (2 digits).
${MM}The current month (01..12).
${MMM}The current month (Jan..Dec).
${MMMM}The current month (January..December).
${DD}The current date (00..31).
${DDD}The current weekday (Sun..Sat)
${DDDD}The current weekday (Sunday..Saturday)
${hh}The current hour (00..23).
${mm}The current minute (00..59).
${ss}The current second (00..59).
${date[.format]}The current date with an optional format.

Date formatting uses the Go date formatting, where you can use a format specification based on the reference date Mon Jan 2 15:04:05 MST 2006.

  - name: body
    type: text
    label: Incident details
    defaultValue: "Received on ${date.Jan 02 2006 at 15:04 pm}"

Activity ID, URL etc.

${ID}The activity ID, for example i3Ht7b89.
${SHORT_URL}The short URL of the activity, for example
${URL}The URL of the activity, e.g.
${channel}The activity channel, for example #_incident-38

Connect. Collaborate. Conclude