Skip to main content

Creating Conditional CML

Learn how to use conditional CML in Cogniss to create dynamic, personalized app content with single & multi-parameter conditions.

Ryan Miller avatar
Written by Ryan Miller
Updated yesterday

Overview

CML (Cogniss Mark-up Language) is a way of enhancing the personalization and customisation of your application. For a full overview (or if you are new to CML), please refer to our CML Overview article on our help site before trying to implement your own conditional CML.

As a guide, CML can typically be written and displayed anywhere in Cogniss that utilises a rich text editor, such as:

  • CML Widget on Dashboard

  • Text Content content block

  • Messages in the Notification Scheduler

Conditions in CML allow an app builder to choose when a particular result is shown to a user based on the defined parameters in the condition. We call this use of CML, conditional CML. Conditional CML is useful if you want to create dynamic content (display custom tips, show different images, recommend different activities) for your users based on different parameters.

There are two different types of conditional CML you can utilise: Single-Parameter conditions and Multi-Parameter conditions.

Please refer to the table below to understand how conditional CML calls are structured and what is used to compose them:

CML

Description

[condition], [/condition]

These condition tags define a condition in CML; conditional CML is only shown if the terms outlined in that condition become true

[result], [/result]

The result tags define a result in CML, usually included as part of a [condition]. This references the result that is shown if the defined condition becomes true

#

The hash symbol is used to reference a number within the condition. For example, to write the number two, you would need to write #2. In the same way, #<=#2 it can be read in plain terms as: a number that is less than or equal to the number 2

>, <, =, =>, =<

Greater than, less than, equal to, greater than or equal to, less than or equal to

These symbols are used to define the parameters of the condition.

#E#

Empty tag, used to define what to show when there are no attempts/completions

{{activityResponseScore “activityID”}}

The cumulative score of a particular activity completion, activity is defined by the activityID

Info on how to locate activityIDs is here.

{{questionResponseScore “questionID”}}

The score of a particular question, question is defined by the questionID

Info on how to locate questionIDs is here.

{{file “fileID’}}

A particular file, defined by the fileID (the most common use case of fileID is to insert an image or graphic)

Info on how to locate fileIDs is here

Writing Conditional CML - Single Parameter

Single-parameter CML conditions rely on a single source of data to determine whether the condition is true or false.

For example, if a user scores less than 2 on a specific question or activity, you can set up a condition to show tailored feedback, such as: “You scored less than 2. This means….”

Let’s take a look at an example:

[condition]{{activityResponseScore "65b7be6d9728842e2ee83242"}}#<=#2[result]{{file “652cdf5b16248e1628f8739a”}}

PHQ4 result (0-2) None. This means you are showing no signs of anxiety or depression.[/result][/condition]

This single-parameter conditional CML states:

If a user’s activity score is less than or equal to two, show the referenced file and the text “PHQ4 result (0-2) None. This means you are showing no signs of anxiety or depression.”

We can see exactly what is defined in the condition by paying attention to what sits between the [condition] and the [/condition] tags. In the same way, we can see what the defined result is by looking between the [result] and the [/result] tags.

To write your own, you’ll:

  1. Start with an open [condition] tag.

  2. Next, you’ll define what the condition is based on; in this case, it will be a user's {{activityResponseScore “activityID’}}, but could also be related to a particular question response (see table above for reference)

  3. You’ll then define the parameter that the score needs to meet using #, <, >, =, etc.

  4. From there, you’ll define the result to be shown if the condition is met using the open [result] tag

  5. Once done, you’ll close off the condition and result with their respective close tags [/result] [/condition]

Following these instructions will have you write the following CML condition:

[condition]{{activityResponseScore “activityID”}}#<=#( number)[result]{{fileID “fileID”}}

(Write your own text here)[/result][condition]

Writing Conditional CML - Multi-Parameter

Multi-parameter conditions enable you to create conditions based on two or more sources of data.

For example, you might want to display specific feedback only when multiple conditions are met, such as when a user scores between 2 and 5 on a certain activity (or question). You can set up a condition to show tailored feedback, such as: “You placed within the moderate range (2-5). This means….”

You can also compare two different activities or questions. For example, if Activity A’s score is higher than activity B’s score, you could show tailored feedback, such as: “Your score in activity A is higher than activity B, This means…”

Let’s take a look at an example:

[condition]{{activityResponseScore "65b7be6d9728842e2ee83242"}}#>=#3#{{activityResponseScore "65b7be6d9728842e2ee83242"}}#<=#5[result]{{file “652cdf5c007c110ed26b34e0”}}

PHQ4 result (3-5) Mild. This means you are showing mild signs of anxiety and depression. We recommend you contact your EAP provider.[/result][/condition]

This multi-parameter conditional CML states:

If a user’s activity score is greater than or equal to three, and less than or equal to 5, show the referenced file and the text “PHQ4 result (3-5) Mild. We recommend you contact your EAP provider.”

We can see exactly what is defined in the condition by paying attention to what sits between the [condition] and the [/condition] tags. In the same way, we can see what the defined result is by looking between the [result] and the [/result] tags.

To write your own, you’ll:

  1. Start with an open [condition] tag.

  2. Next, you’ll define what the condition is based on, in this case, it will be a range that a user's {{activityResponseScore “activityID’}}, falls into, but could also be related to different question responses, different activity scores, or any combination of parameters, etc. (see table above for reference)

  3. You’ll then define the first parameter that the score needs to meet using #, <, >, =, etc.

  4. From there, you’ll then set the second parameter using the same {{activityResponseScore “activityID’}} as you used for the first and #, <, >, =, etc. to define the top of the range in this parameter

  5. You’ll define the result to be shown if the condition is met using the open [result] tag

  6. Once done, you’ll close off the condition and result with their respective close tags [/result] [/condition]

Following these instructions will have you write the following CML condition:

[condition]{{activityResponseScore "activityID"}}#>=#(number)#{{activityResponseScore "activityID"}}#<=#(number)[result](Write your own text/insert result here)[/result][/condition]

Note: CML is extremely sensitive to errors and must be written EXACT to work. One error, extra space, or typo in a page of conditions can cause the whole page to fail.

Common errors in CML result in blank activity pages where the CML should be shown, activities crashing, and navigating users straight to the dashboard page. Please thoroughly test all conditions in your CML to ensure it’s working properly.

Real Use Case for Reference (utilising both single & multi-parameter):

Description:

Upon completion of the PHQ-4 (measuring anxiety and depression) survey, a user will receive the following feedback, which is conditional based on their score

Example:

This is PHQ-4 Feedback (Your Score is {{activityResponseScore "65b7be6d9728842e2ee83242"}})

[condition]{{activityResponseScore "65b7be6d9728842e2ee83242"}}#<=#2[result]{{file “652cdf5b16248e1628f8739a”}}

PHQ4 result (0-2) None. This means you are showing no signs of anxiety or depression.[/result][/condition]

[condition]{{activityResponseScore "65b7be6d9728842e2ee83242"}}#>=#3#{{activityResponseScore "65b7be6d9728842e2ee83242"}}#<=#5[result]{{file “652cdf5c007c110ed26b34e0”}}

PHQ4 result (3-5) Mild. This means you are showing mild signs of anxiety and depression. We recommend you contact your EAP provider.[/result][/condition]

[condition]{{activityResponseScore "65b7be6d9728842e2ee83242"}}#>=#6#{{activityResponseScore "65b7be6d9728842e2ee83242"}}#<=#8[result]{{file “652cdf5f16248e1628f873ed”}}

PHQ4 result (6-8) Moderate. This means you are showing moderate signs of anxiety and depression. We recommend you contact your EAP provider and/or your GP.[/result][/condition]

[condition]{{activityResponseScore "65b7be6d9728842e2ee83242"}}#>=#9#{{activityResponseScore "65b7be6d9728842e2ee83242"}}#<=#12[result]{{file “652cdf61007c110ed26b34fa”}}

PHQ4 result (9-12) Severe. This means you are showing severe signs of anxiety and depression. We recommend you contact your GP.[/result][/condition]

Related Articles
Cogniss key terms
Creating your first app on Cogniss Creator
Content and Survey Activity Template
Cogniss Markup Language (CML) Overview
Easier image placement with CML (Cogniss Markup Language)
Did this answer your question?