In this article:
1. Introduction to the Outcome Rules Panel
2. What Are Outcome Rules
3. How to Set Up an Outcome Rule
3.1 How to access the feature
3.2 Outcome rule configuration elements
3.2.1 Outcome Rules for Initiatives with Children
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 an Outcome 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 Outcome Rules
6. Outcome Rule Limits
This article focuses on Outcome Rules and how to configure them. Please refer to our guide on Outcomes (OKRs) in Businessmap to get started on the topic.
1. Introduction to the Outcome Rules Panel
The Outcome Rules panel is only available to Account Owners and users with the “Manage outcome rules” privilege and can be accessed from the Account Administration icon located at the top right corner of the Businessmap interface. From there, Account Owners and users with the respective privilege can create, edit, disable, and delete Outcome Rules.
2. What Are Outcome Rules
Outcome Rules (short for Calculated Outcome Value rules) 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 outcome 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 an outcome 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.
3. How to Set Up an Outcome Rule
3.1. How to Access the Feature
To create an outcome 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 an outcome 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.
3.2. Outcome 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 outcome 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. You can choose between internal (your Businessmap account), external data sources (through External Web Service), or pull hierarchical data (from first-level child initiatives into a parent initiative). Below, we have covered how to set up an outcome rule using an internal source.
To set up an external source, please refer to the dedicated external source configuration article. To learn how to use hierarchical source types, please refer to our guide on hierarchical outcome rules.
(4) Source configuration
This is where you set up the filter for your data. The Search configuration modal is split into four sections — Filter, Properties, 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 outcome rule*.
- Properties — 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 test the output. You have the option to test with sample data or with real data. The first option will show a sample output and what JSON structure to expect when the rule is executed. The second option will show a real data output.
3.2.1. *Outcome Rules for Initiatives with Children
One of the most common scenarios of using Outcome rules would be to define an OKR for the company or the department and place it into a global initiative. You can then break it down into different teams as child cards or initiatives for execution. Each team will contribute toward achieving the global objective with their results from the completion of those smaller initiatives.
To help list and collect all values from the children's cards of that global initiative, there is a new operator added to the search parameters — “is inherited.” It applies to the Card ID and Custom card ID properties (as well as to the Internal card id in the subquery parameters), and it helps you filter cards that share the same internal or custom ID (i.e. the ID of the parent card to which the outcome rule is assigned).
Let's look at the following example:
You want to track the costs generated in two separate initiatives → Project A and Project B.
To do that, create an Outcome rule that is set up to sum all Costs from the initiative's child cards.
Where the search configuration looks like this:
- Select the “Parent cards” filter and the “all match” operator.
- Click the “This filter” button below it to set up your subquery parameter.
- In the subquery parameter modal, click on Refine search criteria and select “Card ID” or “Internal card ID.”
- Select the “is inherited” parameter.
Note: If you are using a custom card ID for the initiative, you can select "Custom card ID" as the subquery parameter.
You can then apply the Outcome rule to both initiatives. Keep in mind that the outcome rule will give different results in both initiatives because their children are different.
(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.
(7) Test button
3.3. 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 property 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 property of type date from your configuration and adds it to the sample expression.
3.4. 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. By clicking on “Get the data from the source configuration,” you can test your input either with sample or real data.
The sample data results window will look like this:
It shows predefined expressions (1) and sample results (2). Below that is a sample JSON query (3), and underneath you can see and edit 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 result (5) will change accordingly.
3.5. Using Custom Fields and Location Properties
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 outcome 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 properties 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.
4. How to Edit an Outcome Rule
4.1. From the Outcome Rules Panel
Just as you have two options to create outcome 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.
4.2. From the Initiative’s Outcomes Window
The second way to edit outcome rules is through an initiative. Open the initiative that contains the outcome 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 outcome rule from the Associated field dropdown, and click on the pencil icon.
You can then modify every element of the outcome rule from the Edit outcome rule modal window.
Aside from that, you can modify the outcome associated with the outcome rule from the initiative’s Edit outcome window (see image above) the same way you would edit a normal outcome.
4.3. Enforce Recalculation
Since the goal of the outcome rules is to automate goal tracking across initiatives and projects, the system does an automatic recalculation of your outcome 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.
5. Practical Examples of Using Outcome 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 (e.g. in a custom field called “MRR”). You can create an outcome 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 specify the workspace, board, workflow, swimlane, and/or column you will be pulling data from in the Filter section. In the Properties section, you need to pick the custom field that agents will be using to input their MRRs.
In this example, the search configuration can look like this:
And the overall rule setup will look like this:
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
Outcome 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 an outcome rule that takes all cycle times of a select group of cards (e.g. from a specific board) and calculates the average value.
Specify the location (e.g. board, workflow) and cycle time data in the Filter section, and select “Cycle time” in the Properties section.
In this example, the search configuration can look like this:
And the overall rule setup will look like this:
Example 3
Another great use of outcome 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 outcome rule to count the number of cards of type “incident” and recalculate the value in your Outcome.
This is what the search configuration for this example can look like:
Note: Instead of card types, you can also use tags or stickers to set up the rule.
The overall rule setup will look like this:
6. Outcome Rule Limits
To ensure the system runs smoothly, there are certain limitations when it comes to using outcome rules. Generally, they include:
- Number of included outcome rules per account = available business rules * 10 (e.g. if you have 20 available business rules, you will have 200 outcome rules). The maximum number of outcome rules per account is 1000. For trial accounts, the limit is 200 outcome rules.
- Search results = 1000** per search (same as the Advanced Search)
- Number of Outcomes per outcome rule = 50 (e.g. you can use one outcome rule in up to 50 Outcomes).
- Number of outcome rules per board = 10
- Number of test calls = 10 test calls per minute and 100 per hour.
- Number of enforced recalculations = 10 per minute and 100 per hour.
- External source data limit = 200kb.
** This number may vary depending on the account subscription. If you have any questions about your account's limitations, please contact Support.