Variables
Variables are special pieces of text enclosed in curly brackets that are replaced by a current value when a command is executed.
Variables can be used in list names, card titles, card descriptions and comments, e.g.:
every monday at 9am, create a list called "Tasks for week #{weeknumber}"
when a card is moved to "Done", post a comment "Closed by {username} on {date}"
when the red label is added to a card by anyone, rename it to "{cardname} BLOCKED"
This article contains a complete list of variables currently understood by Butler.
Time related
- {date} e.g. October 3, 2016
- {monthdaynumber} e.g. 3
- {monthdaynumberlong} e.g. 03
- {yeardaynumber} e.g. 277
- {yeardaynumberlong} e.g. 277
- {weekdaynumber} e.g. 1
- {weekdayname} e.g. Monday
- {weekdayshort} e.g. Mon
- {dateshort} e.g. Oct 3, 2016
- {datelong} e.g. October 3, 2016
- {datenumber} e.g. 10/3/2016
- {isodate} e.g. 2016-10-03
You can prepend tomorrow and yesterday to the above, e.g. {tomorrowmonthdaynumber}, {yesterdayisodate}.
You can prepend nextworkingday_ and previousworkingday_ to the above, e.g. {previousworkingday_monthdaynumber}.
- {weeknumber} e.g. 40 (ISO week numbering -- starts on Monday)
- {weeknumberlong} e.g. 40 (ISO week numbering, zero-padded)
- {usweeknumber}, e.g. 41 (U.S. week numbering -- starts on Sunday)
- {usweeknumberlong}, e.g. 41 (U.S. week numbering, zero-padded)
- {weekyear} e.g. 2016 (year the week started, ISO week numbering)
- {weekyearshort} e.g. 16
- {usweekyear} e.g. 2016 (year the week started, U.S. week numbering)
- {usweekyearshort} e.g. 16
- {monthweeknumber} e.g. 1 (week within the month)
- {usmonthweeknumber} e.g. 1
You can prepend last and next to the above, e.g. {lastweeknumber}, {nextusmonthweeknumber}.
- {monthnumber} e.g. 9
- {monthnumberlong} e.g. 09
- {monthname} e.g. September
- {monthshort} e.g. Sep
- {quarternumber} e.g. 4
- {year} e.g. 2016
- {yearshort} e.g. 16
You can prepend last and next to the above, e.g. {nextmonthnumber}, {nextquarternumber}, {lastyearshort}.
- {time} e.g. 9:59pm
- {time24} e.g. 21:59
- {timelong} e.g. 21:59:59 EDT
Note: 'long' numbers are zero-padded to be of consistent length (good for sorting)
Note: see also the related article on Arithmetic in Date Variables
Board data
- {boardid} the id of the board
- {boardname} the name of the board
- {boardlink} the link to the board
After a create board
command, the above with the new
prefix (e.g. {newboardlink}) refer to the new board.
After a copy board
command, the above with the copy
prefix (e.g. {copyboardlink}) refer to the new copy of the board.
- {cardboardname} (only after
finding card with id
) the name of the board where the card was found
Card data
Variables available generally when a card is involved:
- {cardname} the card's name
- {carddescription} the card's description (not always available)
- {cardlink} a link to the current card
- {cardlistname} the name of the list where the card is (not always available)
- {cardid} the internal id of the card, e.g. FY2OWrnc. This is always constant.
- {cardidlong} the internal long id of the card, e.g. 571d07b591c8b68aeb4f6acc. This is always constant.
- {cardnumber} the internal number of the card on the board, e.g. 48. This changes when a card is moved to another board (not always available)
- {cardlabels} the names and colors of all the named labels in the card, comma separated
- {cardlabelnames} the names of all the named labels in the card, comma separated
- {cardlabelcolors} the colors of all the named labels in the card, comma separated
- {cardlabelcount} the number of labels in the card
- {cardmemberusernames} the usernames of all the members of the card, comma separated
- {cardmemberfullnames} the full names of all the members of the card, comma separated
- {cardmembercount} the number of members of the card,
- {cardfirstmemberusername}, {cardfirstmemberfullname}, {cardfirstmemberinitials} the details of the first member in the card.
- {cardduecomplete} "true" if the due date has been marked as complete, "false" otherwise.
- {cardcheckliststate} a formatted text with the state of all the checklists in the card, useful to add a comment with a snapshot of the state of a card's checklists.
- {cardchecklistcount} the number of checklists on the card.
- {cardcompletechecklistcount} the number of complete checklists on the card.
- {cardincompletechecklistcount} the number of incomplete checklists on the card.
- {cardduedate} the due date of the card (not always available). Also,
{cardduedateweekdayname}, etc... - {cardcreationdate} the date the card was created.
- {cardagedays} the age of a card in days, with two decimals (e.g. 1d 6h =>
1.25
). - {cardagehours} the age of a card in hours, with two decimals (e.g. 1h 40m =>
1.67
). - {cardageminutes} the age of a card in minutes, with two decimals (e.g. 1h 40m 30s =>
100.5
).
Note: For the last three (age), adding round
at the end (e.g. {cardagedaysround}, rounds the number to the nearest integer.
When the trigger involves a card, the variables above preceded by trigger
({triggercardname}, {triggercardlink}, etc) refer to the trigger card (not all variables may be available).
After creating a card, the variables above preceded by new
({newcardname}, {newcardlink}, etc) refer to the new card (not all variables may be available).
After copying a card, the variables above preceded by copy
({copycardname}, {copycardlink}, etc) refer to the new card (not all variables may be available).
After finding a card, the variables above preceded by found
({foundcardname}, {foundcardlink}, etc) refer to the found card (not all variables may be available).
After the multiplier for each card
, the variables above preceded by multiplier
({multipliercardname}, {multipliercardlink}, etc) refer to the current card (not all variables may be available).
When the trigger contains a condition, e.g. when a card with a due date...
, the variables above preceded by condition
({conditioncardduedate}, etc) refer to the card involved in the condition (typically the trigger card).
Variables available only in commands with triggers that involve a source card, such as when a card is copied
:
- {sourcecardname} the title of the source card
- {sourcecardlink} a link to the source card
Card time in list
- {carddaysinlist} the number of days a card has spent in the current list, with two decimals (e.g. 1d 6h =>
1.25
). Useful to track time spent on tasks. - {cardhoursinlist} the number of hours a card has spent in the current list, with two decimals (e.g. 1h 40m =>
1.67
). Useful to track time spent on tasks. - {cardminutesinlist} the number of minutes a card has spent in the current list, with two decimals (e.g. 1h 40m 30s =>
100.5
). Useful to track time spent on tasks. - {carddaysinpreviouslist} the number of days a card spent in the previous list.
- {cardhoursinpreviouslist} the number of hours a card spent in the previous list.
- {cardminutesinpreviouslist} the number of minutes a card spent in the previous list.
Note: adding round
to any of the time variables above, e.g. {cardagedaysround} gives the time rounded to the nearest integer.
If the trigger involves the movement of a card to a new list:
- {triggercardpreviouslistname} the name of the list from which the trigger card comes from
Member data
Variables available only in commands with when
triggers (i.e. not on due date
or every
):
- {username} the username of the user that triggered the command
- {fullname} the full name of the user that triggered the command
- {initials} the initials of the user that triggered the command
Variables available only in commands with when
triggers that refer to a card that refer to a card and on due date
commands:
- {creatorusername} the username of the user that created the card
- {creatorfullname} the full name of the user that created the card
- {creatorinitials} the initials of the user that created the card
Variables available only in commands with triggers where a user is matched, e.g. when someone is added to a card
trigger, when someone is mentioned
, etc. Also, in multipliers (for every member in the card
, this is only available for comments and emails notification actions). There's also variables for particular types of match (add, mention):
- {matchedusername} the username of the member that matched in the command (added, mentioned, etc)
- {matchedfullname} the full name of the user that was matched in the command (added, mentioned, etc)
- {matchedinitials} the initials of the user that was matched in the command (added, mentioned, etc)
- {addedusername} the username of the member that was added to the card
- {addedfullname} the full name of the user that was added to the card
- {addedinitials} the initials of the user that was added to the card
- {removedusername} the username of the member that was removed from the card
- {removedfullname} the full name of the user that was removed from the card
- {removedinitials} the initials of the user that was removed from the card
- {mentionedusername} the username of the member that was mentioned to the card
- {mentionedfullname} the full name of the user that was mentioned to the card
- {mentionedinitials} the initials of the user that was mentioned to the card
Other
Variables available for commands with certain triggers, such as when a list is created
:
- {listname} the name of the list
Variables available for the when a due date is added
trigger:
- Date variables for the due date: {cardduedate}, {cardduedateweeknumber}, {cardduedatemonthdaynumber} etc
Variables available for the when a comment is posted
trigger:
- {commenttext} the text of the comment
- {commentlink} a link to the comment
Variables available only in commands with mentioning triggers such as when a card is mentioned
and when a member is mentioned
(also after the find the mentioned card
action):
- {mentionbacklink} a link to the card where the mention occurred
- {mentiontext} the text (comment, card description, checklist item) that includes the mention
- {linklessmentiontext} the text (comment, card description, checklist item) that includes the mention, with all card mentions (links) removed
- {usernamelessmentiontext} the text (comment, card description, checklist item) that includes the mention, with all user mentions (@username) removed
- {mentionlessmentiontext} the text (comment, card description, checklist item) that includes the mention, with all user or card mentions removed
Variables available only in when
triggers involving a checklist, such as when a checklist is added
:
- {checklistname} the name of the checklist
Variables available only in commands with triggers such as when a checklist item is checked/unchecked
:
- {checklistitemname} the name of the checklist item
- {checklistitemstate} the word "complete" or "incomplete"
Variables available only in triggers such as when a green label is added
:
- {labelname} the name of the label
- {labelcolor} the color of the label
Variables available only in commands with triggers such as when the name of a card starts with
and trigger conditions such as when a card with a name containing
:
- {matchedtext} the text that matched the condition, typically used with a condition including a
{*}
wildcard. - {textbeforematch} the text before the matched text.
- {textaftermatch} the text after the matched text.
Variables available only in commands with triggers such as when the name of a card contains a date
:
- {matcheddate} the date interpreted by Butler.
Variables available only in commands with triggers such as when an attachment is added to a card
:
- {attachmentlink} the link to the attachment.
- {attachmentname} the name of the attachment.
Variables only available in commands with triggers like when the name or the description of a card starts with
:
- {changedfield} the name of the field changed (name or description).
- {textbefore} the text of the name or description before the update.
- {textafter} the text of the name or description after the update.
Variables available after an HTTP request:
- {httpresponse} the body of the response.
[LEGACY BOT] You can see the current value of most variables by entering the action:
print variables
e.g.:
when a label is added to a card, print variables
After you add a label to a card, go to the rule log to see the values.
If you need a variable and it's not here, let us know and we'll do our best to make it available.