Table of contents:
1. Introduction to the Outcome Rules Panel
2. What Are Calculated Outcome Value Rules
3. How to Set Up a Calculated Outcome Value Rule
3.1 How to access the feature
3.2 COV rule configuration elements
3.3 Using the EXTRACT_VALUE function
3.4 The "EXTRACT_VALUE" Configuration Panel
3.5 Using custom fields and location columns
4. How to Edit a Calculated Outcome Value Rule
4.1 From the Outcome Rules panel
4.2 From the initiative’s Outcomes window
4.3 Enforce recalculation
5. Practical Examples of Using COV Rules
6. COV Rule Limits
This article focuses on Calculated Outcome Value rules and how to configure them. Please refer to our guide on Outcomes (OKRs) in Kanbanize to get started on the topic.
Introduction to the Outcome Rules Panel
The Outcome Rules panel is only available to Account Owners and can be accessed from the Account Administration icon located at the top right corner of the Kanbanize interface. From there, Account Owners can create, edit, disable, and delete Calculated Outcome Value rules.
What Are Calculated Outcome Value Rules
The Calculated Outcome Value rules ("Outcome Rules" or “COV rules” for short) are automatic functions that let you automatically track your work progress and goals. This goal-tracking feature significantly reduces the need to manually update your Outcomes.
The way COV rules work is they pull data from a source you have specified (e.g. cards located on a certain board containing a particular regular or custom field) and calculate a single numeric value from that data source, through an aggregation formula that takes it as input. For example, you can search for the cards in a given position and perform the following operations on any of their numeric properties (e.g. size): sum, average, min, max, etc..
If your goal is to reach a certain number of new product subscriptions, for example, you can create an initiative to capture this outcome and define a COV rule to sum the values of a custom field from the linked child cards, which may represent the different geographies. Then, as the custom field is populated with the subscriptions generated by country, the rule will take into account the new values when being recalculated (every 24 hours). That way, you will not have to manually sum numbers and update the outcome, as it will sum the values of all the child cards and populate the outcome value in the parent initiative.
How to Set Up a Calculated Outcome Value Rule
How to access the feature
To create a COV rule, head to the Outcome Rules panel from Account Administration, and click on the plus icon at the upper right corner of the screen.
Alternatively, you can also create a COV rule directly from an initiative. To do so, open the initiative you want, click on “Define desired measurable outcomes,” and select “Create new outcome rule” from the associated field dropdown.
COV rule configuration elements
Once you access the “New outcome rule” modal window, you will see it has the following elements:
(1) Name
Give a name to your new COV rule.
(2) Description
Describe the goal or purpose of the new rule. This field is optional.
(3) Source type
This is the source you will be pulling data from. For now, the system supports only internal data sources, but external options (through web service invoke) will also be included at a later stage.
(4) Source configuration
This is where you set up the filter for your data. The Search configuration modal is split into four sections — Filter, Columns, Time unit, and Options:
- Filter — you can use the same options as the “refine search criteria” in the Advanced search to filter results. Just select the properties you want to include in your configuration. Here you also have the option to filter cards that belong to the initiative where you will be applying the COV rule.
Note: There is a new operator added to the search parameters — “is inherited.” It is applicable to the Card ID and Custom card ID properties (plus Internal card id in the subquery parameters) and it helps you filter cards that share the same internal or custom ID. A common use case would be to filter the child cards that belong to the initiative where you will be applying the COV rule. Please note that if a child card has multiple parents, the "all match" operator will not include that child card. Use the "some match" instead.
Check the image below for reference.
- Columns — filter the properties you want to include in your formula (you will see them in the sample JSON when you start configuring your EXTRACT_VALUE function).
- Time unit — choose the preferred time unit (Days, Hours, Minutes, and Seconds).
- Options — choose to include archived and/or discarded cards in your data source. By default, both options are disabled.
Note: Once you have set up your Search configuration modal, you can click on the Test button in the lower right corner to see the sample output. It will show you what JSON structure to expect when the rule is executed.
(5) Value extraction function
In the most popular scenarios, you will only need to configure the EXTRACT_VALUE function, as it supports the most popular aggregation functions natively (sum, avg, min, max, length, etc). However, if you want to extract the value out of the dataset and then perform additional operations with it, you can do it in the same way as with the calculated custom fields, i.e. use “@” to add functions and dynamic values (e.g. card deadline, card size, custom fields of type number/date).
(6) Result name
Set a name for the result of your function. This is the name you will see in the initiative's outcome.
Once you have configured all fields, click on the Save button. If your formula is incomplete or there is another inconsistency in your rule configuration, you will get a pop-up message explaining the issue.
Using the EXTRACT_VALUE function
The EXTRACT_VALUE function uses JMESPath library. JMESPath is a query language for JSON to help you extract and transform elements from a JSON document. To help you better understand how to construct an expression, you can check out these Tutorials and Examples. You can also read the Specifications and Built-in Functions if you want to get an insight into all of JMESPath’s capabilities.
There are six predefined expressions that you could use to get results of type number:
- length([])
- sum([].size)
- avg([].size)
- min([].size)
- max([].size)
- sum([?size > `20`].size)
Note: You can change “size” in the expression to any other element (of type number) you need for your use case, e.g. cycle time, total subtasks count, times moved to, etc. By default, the system takes the first column of type number from your configuration and adds it to the sample expression.
You can also use two predefined expressions of type date, but keep in mind these can only be used as part of the function since the result should always have a numeric value:
- min([].created_at)
- max([].created_at)
Note: You can change “created_at” in the expression to any other element (of type date) you need for your use case, e.g. deadline, end date, planned start, etc. By default, the system takes the first column of type date from your configuration and adds it to the sample expression.
The "EXTRACT_VALUE" Configuration panel
If you select the EXTRACT_VALUE function in the Value extraction function field, the system will open a new window with the predefined expressions (1) and sample results (2) based on your search configuration. Below that, you will see a sample JSON query (3), and underneath that is where you should input your Expression (4). You can copy and paste one of the predefined expressions or make an expression yourself. Depending on what expression you input, the sample result (5) will change accordingly.
Using custom fields and location columns
When you're creating an expression that contains a custom field, you need to input the custom field's ID (key), and not its name (e.g. sum([].cf_1234)). If you're using a custom field in your COV rule, the system will generate a Legend (1) in the "EXTRACT_VALUE" configuration panel that shows each custom field (2) and its corresponding ID (3).
Therefore, if you want to calculate the average value of the "Operating costs" custom field, your expression will look like this: avg([].cf_2547) (4)
Likewise, if you're using columns of type location (e.g. last date moved to, times moved to, first/last date moved to), the Legend will show each location's corresponding key which you can use to make an expression.
How to Edit a Calculated Outcome Value Rule
From the Outcome Rules panel
Just as you have two options to create COV rules, there are two ways to edit them. The first one is from the Outcome Rules panel where you need to click on the three-dot icon next to each rule and choose Edit from the dropdown list of options.
From the initiative’s Outcomes window
The second way to edit COV rules is through an initiative. Open the initiative that contains the COV rule, click on the three dots next to the Outcome you want to modify, and select the edit icon. Once the Edit outcome window opens, find the COV rule from the Associated field dropdown, and click on the pencil icon.
You can then modify every element of the COV rule from the Edit outcome rule modal window.
Aside from that, you can modify the outcome associated with the COV rule from the initiative’s Edit outcome window (see image above) the same way you would edit a normal outcome.
Enforce recalculation
Since the goal of the COV rules is to automate goal tracking across initiatives and projects, the system does an automatic recalculation of your COV rules every 24 hours. However, you can also refresh your data manually and track changes in real time through the Enforce recalculation option.
You will find it in the Outcome’s settings dropdown when you click on the three dots menu.
You can also do an enforced recalculation from the Edit outcome window by clicking the icon next to the outcome’s current value.
Practical Examples of Using COV Rules
Example 1
Let's say you want to set a goal for your Sales team to increase the MRR from $10,000 to $50,000 for the month of September. Each agent has their own card/initiative where they update the MRRs they've generated over the month. You can create a COV rule in an initiative that calculates the sum of all MRRs, so you can easily track how you progress toward your goal. That way, all MRR updates will be automatically calculated in the initiative's Outcome.
You need to configure your results and apply the EXTRACT_VALUE function to extract the sum of all values from the MRR custom fields your agents will use.
Example 2
COV rules can also be used to track time-related metrics that can be measured in numeric values. For example, you may set a goal to decrease the average time it takes your QA team to test products before they are released to the customer. To do that, you can set a COV rule that takes all cycle times of a select group of cards (e.g. from a specific board) and calculates the average value.
Example 3
Another great use of COV rules is to keep track of incidents. For example, you may set a goal of keeping incidents below number X per year. In this case, you can configure your COV rule to count the number of cards of type “incident” and recalculate the value in your Outcome.
COV Rule Limits
To ensure the system runs smoothly, there are certain limitations when it comes to using COV rules. Generally, they include:
- number of included COV rules per account = available business rules * 10 (e.g. if you have 20 available business rules, you will have 200** COV rules)
- search results = 1000** per search (same as the Advanced Search)
- number of Outcomes per COV rule = 50** (e.g. you can use one COV rule in up to 50 Outcomes)
** This number may vary depending on the account subscription. If you have any questions about your account's limitations, please contact Support.