In this article:
1. How to create the rule?
2. How to set up and enable the rule?
3. Practical examples for using the "Card is Updated" rule
The "Card is Updated" business rule will trigger a predefined action (create, move, update, send a notification, call web service) whenever a card is updated. A typical example would be to move a card to a particular swimlane if its color changes to red.
1. How to Create the Rule?
Only users with "Account Owners" or "Manage Business Rules" privileges can create business rules.
To configure the business rule, please go to the Administration panel at the top right side of your screen → open the Business rule tab → select the "Card is updated" rule option.
Note: In case there is a set of defined rules to your account → use the Add new rule button at the upper right side of the panel.
2. How to Set Up and Enable the Rule?
The "Card is Updated" configuration panel has the following fields and properties:
(1) Name - give a name of the rule to distinguish it.
(2) Description - provide a description of the rule behavior in the system.
Note: when a business rule is created, it will get a rule ID and will be made available in the Business rule panel under name and description.
PRO tip: You can specify the board name in the rule name in order to easily distinguish rules configured for each of your boards.
(3) Share with: this option allows you to share the rule with other users in the system so that they can edit/disable/enable the rule.
Every business rules have three main control settings: When; And; Then.
It is a sort of "point-and-click" programming language with which you can automate any process. The way it works is based on the programming conditional statement "if this then that".
To save/enable a rule, click on Save at the bottom right corner of the configuration panel.
(4) WHEN: "The following card fields are changed" - this is the event that will trigger an action.
→ Click on Any Field → Select a regular field or a custom field. For example, select a "Color" and specify it = red.
As a result, the rule will trigger an action every time a card changes its color to red.
Note: You can add as many fields as you wish by clicking on Add new field and repeating the steps.
(5) AND - define the filters and select the conditions under which the actions should be triggered.
- When users create a new rule, the Board filter will be applied by default. This means that the rule will be executed only for the boards you specify in the filter. If you remove the board property and enable the rule, it will be executed for the entire account.
You can use "or" to add extra boards and optimize the scope of the rule. Use the delete sign to remove a board. - Use "Add new property" to further configure the automation. Select a regular or custom field from the panel (for example - Owner: set it up).
As a result, the rule will be triggered only for cards, whose color is changed to red; are located on the defined board, and have the owner specified in the rule.
(6) THEN - Select an event that will happen if the created card matches your filter.
- create cards or subtasks - click on "add new action" and use the supporting panel to select the type of cards you want to create i.e. a new card, a child card, a parent card, relative card, or a subtask.
Note that you can create multiple cards/subtasks and the cards can be rearranged in order to be created in the desired sequence - simply drag and drop a card in order to rearrange it before or after another.
Note that subtasks cannot be rearranged within the rule configuration, so in case you have a subtask among the cards that are to be created, you would not be able to move a card on the subtask's position.
When you make your choice, please define the new card/child/parent/relative/subtask position via the board minimap.
- update the card details - click on 'add new action' and update the properties that you want to update when a card is created. Select any of the available options and set it up.
- send notifications - click on "add new action"
Every time "a card is created" a user or a set of users will receive an email if you select to configure this option and create a template for the email notification, which is to be sent.
- In the To:/Cc: field → use the "add internal users" dropdown which opens a list of all users in your account including: Self, Owner, Watchers, Contributors, and Reporter.
→ select and add the user/s that will be notified. The "add custom field" option is used if you have a custom field with an email address and the created card contains this custom field, the notification will be sent to this email address. - The Subject of the notification email contains by default: the title of the executed rule, board name, card ID, and the text "New card created". You can modify the title by clicking on "add card fields" and selecting your preferred card properties to display. You can remove all fields and write a custom title.
- Email body: you can either keep the predefined text or change it according to the information you want to share with the users.
- move the card - click on "add new action" to open the Board Minimap option and select where to move the card that has been created.
Choose a Board from the dropdown list (1) and select a position (column/lane) on the board minimap (2).
5) invoke web service - click on "add new action" to add a call to an external web service.
To configure it, select "not set" and set the parameters.
You can configure the following options:
- Name – a human-readable identifier for the web service call
- URL – the address of the endpoint service
- Method – which HTTP method should be used for the call (available options are POST, GET, HEAD, PUT, DELETE, OPTIONS, PATCH)
- Authentication – NONE or BASIC authentication supported for the moment
- HTTP Body – Whether you want to send the payload as raw JSON-encoded values, directly in the HTTP body
- Parameters – parameters to be sent to the endpoint service
- Headers – custom headers to be sent to the endpoint service
To send the parameters in the body of the web service call → activate the checkbox.
Additionally, the POST, PUT, DELETE, and PATCH requests send an additional parameter – ‘kanbanize_payload’ that contains information about the card that has been created or moved. The payload is in the following format:
{
“trigger” : “taskCreated”,
“timestamp” : “2015-03-04T14:19:38+00:00”,
“card” : {
“taskid” : “35156”,
“title” : “”,
“description” : “”,
“tcolor” : “#34a97b”,
“priority” : “Average”,
“size” : null,
“owner” : “testAdmin”,
“deadline” : null,
“typeName” : “”,
“tags” : “”,
“extLink” : “”,
“reporter” : “testAdmin”,
“createdAt” : “2015-03-04 14:19:33”,
“columnname” : “Requested”,
“lanename” : “Default Swimlane”,
“boardName” : “my board”,
“customFields” : [
],
“boardid” : “131”
}
}
When the payload is received by the endpoint, the content of “kanbanize_payload” can be parsed and the required actions can then be performed by the external system.
Click on the green plus sign to add a parameter. Select a field you wish to set as а parameter → click on Apply.
When you have configured your parameters, use the Test Settings button to send a pre-scanned request for testing and debugging purposes only. Click on Save Service to save the configuration.
Check Businessmap API documentation to learn more.
3. Practical Examples of Using the "Card is Updated" Rule
This rule comes in handy when you would like to trigger a certain action based on an updated field of a given card. One can configure the criteria to a specific property being updated with a specific value, or it can be as general as one needs it.
An example scenario would be to monitor a card's tags field and update cards whenever the property has a specific value.
For example, when a card's tags are updated and the new tag matches 'Start', the card is moved to the "Ready to Start" column of the workflow. In this case, after the card is created (presumably in the Backlog or Requested columns), and later on its tags are updated, it will automatically move to the "Ready to Start" column.
Another example of this scenario would be to update a card's color whenever its priority is changed and the new priority is Critical. In addition, the same rule can be used to send a notification to a group of people or call a custom web service (which can notify the users in an external application e.g. Slack).
You can learn more in our dedicated article on copying card properties between linked cards.