Overview
CML (Cogniss Mark Up Language) allows you to perform simple calculations directly in your app. This is useful when you want to perform calculations on data points collected in your app.
CML currently supports the four basic arithmetic operations:
Addition
( + )Subtraction
( - )Multiplication
( x )Division
( / )
Note: These are the only arithmetic operators currently available (no exponents, square roots, unary plus/minus, modulo, etc.)
If you are not familiar with CML, please refer to our CML Overview article before trying to implement your own CML calculations.
Rules of CML Calculations
CML performs calculations linearly, meaning they are processed strictly from left to right
CML does not follow the “order of operations” that normal arithmetic adheres to
CML does not recognise parentheses; therefore, parentheses cannot be used in CML calculations (the use of parentheses will break the calculation)
CML calculations allow for the mix of static values (i.e. 1, 2, 3, 4, 5, etc.) and dynamic data (CML references)
Unless specified, the calculation result will be rounded to the nearest whole number. To display decimal points, you must specify this within the calculation
Static calculations are processed instantly, but each back-end data fetch adds load time (too many of these might slow down the processing time of your calculation)
By default, CML will use the value of the most recent attempt/completion of an activity. You must specify if you want to use a value from a previous attempt of a particular activity (if the attempt number doesn’t exist, CML falls back to the closest available one)
CML does not support automatic aggregation. Each value must be referenced in the formula
Please use the table below as a guide for what CML tags are supported when writing CML calculations:
CML | Description |
| These calc tags define a calculation in CML |
| The hash symbol is used to separate values and symbols in CML. For example, to write 2+3, you would need to write |
| Operator for addition |
| Operator for subtraction |
| Operator for division |
| Operator for multiplication |
| Tag used for specifying a calculation to display decimal points in the result.
The number between the tag will be the number of decimal points shown
|
| Tag used for saving a value as a variable |
| Tag used for using a previously saved variable |
| The cumulative score of a particular activity completion, activity is defined by the activityID
Info on how to locate activityIDs is here.
|
| The score of a particular question, question is defined by the questionID
Info on how to locate questionIDs is here.
|
Writing CML Calculations
Fundamental Operations
To write a CML calculation, you’ll utilise the [calc],[/calc] tags to specify what you’d like Cogniss to calculate.
We use the # to seperate values and symbols. The # is always used around the operators ( + , - , x , / ).
CML calculations, like all CML, follows a general structure:
[calc] value (static or dynamic)#, operator, #other value (static or dynamic) [/calc]
So, for example, to write “2+3” in CML, you’ll write [calc]2#+#3[/calc]. This will display 5 in your application.
Adding Decimal Places
When working with CML calculations, you can control how many decimal places your result is shown to. This is done using the [dp] and [/dp] tags.
Think of these tags as a way of telling the calculation, “I want my answer rounded and displayed to this many decimal places.”
Inside the decimal tags, write the number of decimal places you want.
For example:
[dp]2[/dp]→ shows results with 2 decimal places.[dp]3[/dp]→ shows results with 3 decimal places.
There’s no strict limit; you can extend the result to as many decimal places as needed.
The decimal place tags must always come after the operation inside the [calc] tags.
For example:
[calc]53#/#100[dp]3[/dp][/calc]
Will return 0.530 (always showing 3 decimal places, even if the final digit is a zero).
Tip: The number of decimal places you specify will always appear in the result, even if they are trailing zeros.
Examples of CML Calculations
Simple addition:
[calc]5#+#3[/calc]
Displays: 8 (because 5+3=8)
Mixed operations:
[calc]5#+#3#x#2[/calc]
Displays: 16 (because 5 + 3 = 8 → 8 × 2 = 16), remember CML does not follow the rules of the order of operations
[calc]1#+#2#x#2[/calc]
Displays: 6 (because 1+2 = 3→ 3 × 2 = 6)
[calc]20#-#4#/#2[/calc]
Displays: 8 (because 20 − 4 = 16 → 16 ÷ 2 = 8)
Dynamic & Static Value Calculations:
[calc]{{activityResponseScore “activity ID”}}#+#10[/calc]
Displays: The total of the user’s activity score (for the specified activity) + 10
Calculating Percentage:
[calc]20#/#100#[dp]2[/dp]x#100[/calc] %
Displays: 20.00% ( 20 / 100 to two decimal places = 0.20 → 0.20 x 100 =20.00)
CML Variables in Calculations
Variables in CML allow you to store a number or result from one calculation, then reuse it in another. This is especially useful when you want to reference the same value multiple times without having to repeat the entire formula. This reduces data calls and will improve processing times for calculations that draw on multiple points of dynamic data.
Saving a Variable
You save a variable inside [calc] tags by adding the [saveVar] tag.
Example:
[calc]5#+#3[saveVar]total[/saveVar][/calc]
Here:
The calculation 5+3 is performed.
The result (8) is saved as a variable named total.
From now on, whenever you call total, it will return the value 8.
Reusing a Variable in Another Calculation
To reuse a variable, wrap its name in [useVar] tags and input it where desired on the page. This could be in another calculation, a condition, or even just referenced on its own.
Example:
[calc][useVar]total[/useVar]#x#2[/calc]
Here’s what happens:
[useVar]total[/useVar]is replaced by the saved value 8The calculation becomes 8 * 2
The result returned is 16
Chaining Calculations with Variables
Variables shine when you want to build calculations step by step.
Example:
[calc]20#-#7[saveVar]step1[/saveVar][/calc]
[calc][useVar]step1[/useVar]#+#3[saveVar]final[/saveVar][/calc]
[calc][useVar]final[/useVar]#x#2[/calc]
Step by step:
20 - 7 = 13 → saved as step1.
step1 + 3 = 16 → saved as final.
final * 2 = 32 → result shown.
This way, you can break complex calculations into smaller, reusable parts.
Tip: Use clear, descriptive names for your variables (height, weight, finalScore) so it’s easy to keep track of what each one represents. Variable names must be one word and must not include any spaces.
Real Use Case for Reference (calculating a user’s BMI):
Description:
The example below shows how it’s possible to calculate a user’s BMI based on metrics captured within an app. The formula utilises CML calculations, CML variables, and CML conditions to achieve this.
The formula for calculating BMI is BMI = weight (kg) / [height (m)]²
To achieve this in CML, we need to first calculate height in meters squared before we can divide by the weight in kilograms.
Example:
Calculating Height and Weight
You reported your height as {{questionResponse "questionID"}} centimetres and your weight as {{questionResponse "questionID"}} kilograms.
Calculating BMI
Based on your height and weight measurements, your BMI is:
[calc]{{questionResponse "questionID"}}#/#100[dp]2[/dp][saveVar]heightInMeters[/saveVar][/calc]
[calc][useVar]heightInMeters[/useVar]#x#[useVar]heightInMeters[/useVar][dp]4[/dp][saveVar]squareRootHeightInMeters[/saveVar][/calc]
[calc]{{questionResponse "questionID"}}#/#[useVar]squareRootHeightInMeters[/useVar][dp]1[/dp][/calc]
[calc]{{questionResponse "questionID"}}#/#[useVar]squareRootHeightInMeters[/useVar][dp]1[/dp][saveVar]bmi[/saveVar][/calc]
Displaying a User’s BMI Range
[condition][useVar]bmi[/useVar]#<=#18.4[result]Underweight[/result][/condition][condition][useVar]bmi[/useVar]#<=#24.9#[useVar]bmi[/useVar]#>=#18.5[result]Normal weight[/result][/condition][condition][useVar]bmi[/useVar]#<=#39.9#[useVar]bmi[/useVar]#>=#25[result]Overweight[/result][/condition][condition][useVar]bmi[/useVar]#>=#40[result]Obese[/result][/condition]