In this article:
1. How to Access It
2. External Source — Configuration Elements
2.1. Method
2.2. URL
2.3. Authentication
2.4. Headers
2.5. Body
2.6. Test Your Response
3. Practical Example
This article focuses on how to configure an external source to set up Outcome Rules in Businessmap. To get started on the topic, you need to be familiar with the concept of Outcomes (OKRs).
To learn more about Outcome Rules and how to set them up, please refer to our dedicated guide.
How to Access It
To create an outcome rule, go to the Administration panel and select the Outcome Rules menu. Click on the plus icon at the upper right corner of the window, and you are ready to start setting up your rule. Alternatively, you can create an outcome rule straight from an initiative. Open the initiative where you want to create the rule, click on “Define desired measurable outcomes,” and select “Create new outcome rule” from the dropdown.
External Source — Configuration Elements
Once you access the “New outcome rule” modal window, click on External under the “Source type” setting. Select the “Open configuration” button to configure your data. This will open the Web Service Invoke modal window, which has the following elements:
1. Method
Select the request method you want to use. You can choose from the following options:
- GET — The GET request is used to retrieve data from a specified resource. In an Outcome Rule scenario, this is the most commonly used request type.
- POST — Use a POST request when you want to create or update a resource. In a sales scenario, you can use it to update a contact form.
- PUT — Similar to POST requests, a PUT request can create or update a resource. The difference is that PUT requests are idempotent (i.e. calling the same PUT request multiple times will always return the same result).
- PATCH — Use a PATCH request to make partial updates to a resource.
- HEAD — A HEAD request is identical to a GET request, except that the server will not return a message-body in the response. It is generally faster to use it if you don’t need the information in the body of a GET response.
- OPTIONS — An OPTIONS request lets you determine what communication options are available for a specific source (e.g. GET, POST, DELETE, etc.).
- DELETE — The DELETE request is exactly what it sounds like: it lets you delete a specified resource.
2. URL
Input the URL of the endpoint service, i.e. the source where you will be making a request.
Alternatively, you can type in the “@” symbol in the URL field, which will open a “Parameter builder” window where you can set up a dynamic parameter. You can choose to input either plain text or select a value from a card. The values are taken from the card where there is an Outcome rule applied with the respective Outcome. When the Outcome rule is executed, card: deadline for example will return the card’s deadline.
Parameter Builder: Card Values
The card values are:
- card:workspace id
- card:workspace name
- card:board id
- card:board name
- card:workflow id
- card:workflow name
- card:column id
- card:column name
- card:lane id
- card:lane name
- card:section number
- card:section name
- card:id
- card:custom id
- card:effective id
- card:color
- card:deadline
- card:priority
- card:size
- card:title
- card:sticker ids*
- card:sticker labels*
- card:tag ids*
- card:tag labels*
- card:type id
- card:type name
- card:owner user id
- card:owner username
- card:co-owner user ids*
- card:co-owner usernames*
- card:reporter user id
- card:reporter username
- card:reporter email
You can also select custom fields:
- card:custom field:slt:<field_id>:value
- card:custom field:mlt:<field_id>:value
- card:custom field:number:<field_id>:value
- card:custom field:date:<field_id>:value
- card:custom field:link:<field_id>:value
- card:custom field:calculated number:<field_id>:value
- card:custom field:calculated date:<field_id>:value
- card:custom field:dropdown:<field_id>:value ids*
- card:custom field:dropdown:<field_id>:value names*
- card:custom field:dropdown:<field_id>:value names with other value*
- card:custom field:dropdown:<field_id>:other value
- card:custom field:contributor:<field_id>:user ids*
- card:custom field:contributor:<field_id>:usernames*
- card:custom field:cardpicker:<field_id>:selected card ids*
- card:custom field:vote:<field_id>:votes for
- card:custom field:vote:<field_id>:votes against
- card:custom field:vote:<field_id>:votes for percent
- card:custom field:vote:<field_id>:votes against percent
* The system returns the values separated by a comma.
Where:
- value will return the field’s value
- value ids will return the IDs of the values, separated by a comma (e.g. 1,2,3)
- value names will return the names of the values, separated by a comma (e.g. Value 1,Value 2,Value 3)
- value names with other value will return the names of the values and the other value**, separated by a comma (e.g. Value1,Value,2,Other value)
- other value will return the other value**
- user ids will return the IDs of the users, separated by a comma (e.g. 123, 555, 2589)
- usernames will return the names of the users, separated by a comma (e.g. User 1,User 2,User 3)
- selected card ids will return the IDs of the selected cards, separated by a comma (e.g. 1111, 2255, 45678)
- votes for will return the “thumb up” votes
- votes against will return the “thumb down” votes
- votes for percent will return the percent of “thumb up” votes without the “%” in the end
- votes against percent will return the percent of “thumb down” votes without the “%” in the end.
** If the “Allow other value” setting is enabled for the respective custom field.
Parameter Builder: Functions
You can also apply functions to the card values you have selected in the Parameter Builder. For all functions except ENCODE and ENCODE EACH, you can choose to add plain text or card values. The following functions are available:
- AFTER EACH — adds a value after each array element. For example, if you want to take a dropdown field with A, B, and C values, and you have selected card: custom field:dropdown:<field_id>: value names in the endpoint configuration, and apply AFTER EACH: “;” the result will be: A;,B;,C;
- BEFORE EACH — it is the same as AFTER EACH with the exception that it adds a value before each array element. Using the example from above, the result will look like this: ;A,;B,;C
- ENCODE — encodes the value. The available encoding options are base64, JSON, URL, and XML.
- ENCODE EACH — encodes each array element separately. The available encoding options are base64, JSON, URL, and XML.
- IF_EMPTY — if “X” is empty, take “Y.” For numeric values, 0 counts as empty.
- IF_NULL — if “X” is null, take “Y.”
- JOIN WITH — adds a value between each array element. Using an A, B, C dropdown example, if you set JOIN WITH: “|” the result will be A|B|C
- REPLACE — replaces one value with another. It has 2 parameters: PATTERN (the value that is to be replaced) and REPLACEMENT (the value that will replace the old one).
Important: The order in which you arrange your functions matters. The system reads the functions (including nested functions) from top to bottom and inside out.
Let’s illustrate that with an example. We have a sequence of 3 functions with the following configurations:
- BEFORE EACH: “<”
- AFTER EACH: “>”
- JOIN WITH: “&”
This is what the input would look like in this sequence:
The output would be:
<A>&<B>&<C>
Now if we change the sequence to:
- JOIN WITH: “&”
- BEFORE EACH: “<”
- AFTER EACH: “>”
The input will look like this:
And the output will be:
<A&B&C>
3. Authentication
The supported authentication methods are None, Basic, and API Key.
4. Headers
The custom headers that will be sent to the endpoint service.
5. Body
There are 3 supported body types: Form data, JSON, and Advanced. For Form data and JSON, you have the option to encode the key and/or encode the value (accessible from the gear icon next to the Key and Value fields). For Form data, the encoding is of type URL, while for JSON, the encoding is of type JSON.
6. Test Your Response
Click on the Test button in the lower left corner of the Web Service Invoke modal to test your request configuration. This will open a Search configuration test window where you can change the card the test is applied to. To do that, just click on the Change card button and look for the card you want. You can search by card ID, custom ID, and title.
Note: There is an external source data limit of 200kb. If the response from the external service exceeds that limit, the rule will not go through. You can check the request status from the Admin Panel → Security & Audit → Audit Logs → Outcome Rules.
Now that you have configured your external source, you can proceed to set up your outcome rule (the same way you would create a standard Outcome rule).
Practical Example
Let’s look at a practical example of an outcome rule using an external data source.
A company with branches spread throughout the globe may have an OKR to track revenue by region (measured in the local currency). To automate the daily calculation, you can send a request to an external source (in this case an online currency converter) that will convert the revenue into USD from the respective local currency.
The team uses two custom fields — “Region Currency” where they input the local currency (EUR, BRL, etc.), and “Amount” where they add the revenue.
This is what the Web Service Invoke configuration can look like:
You can use a dynamic parameter in the URL for the local currency by taking the value from the “Region Currency” custom field (with a card:custom field:dropdown:<field_id>:value names parameter). That way, the outcome rule will always convert the local currency set in the card the rule is applied to.
This is what the outcome rule’s setup can look like:
And this is what a successful calculation can provide: