Introduction
Cogniss Markup Language (CML) can be leveraged to call specific parts of users' data from your app's databases to create unique and personalized experiences. For example, you may want to personalize text across the app to mention the name of the app user ("Hello, {{user.displayname}}"), or reference an app user's response in a previous question or activity.
Basic CML is mostly a direct replacement of the reference, whereas Advanced CML allows for additional conditions or processing of the data before displaying the content to the app user.
Generally, CML references are denoted with double curly brackets, for example:
{{ CML reference }}
To the user, they will not see this CML reference code - it will be dynamically replaced with the relevant content that is referenced/processed.
Please note: accuracy is important in using CML references within your app. If any references are incorrect or syntax has been copied incorrectly, the context will not display properly if at all. It is critical to test as you go!
Basic CML
Here are some common CML references that can make your text content more dynamic. You can use this anywhere Rich Text Formatting text can be entered and displayed to the user.
Question response:
{{questionResponse "questionID"}}
This CML reference displays the content of the user's response to a specific question, determined by the questionID. This displayed response can be a number, text, or an option/s selected (such as in a multiselect/multichoice question).
In the case that the user has responded with multiple options (e.g. in the case of a multiselect question), you can use a slight extension of the questionResponse CML reference to present these multiple responses in a bulleted list:
{{questionResponse "questionID,bulletPoints,true"}}
Question score:
{{questionResponseScore "questionID"}}
This CML reference displays the score for the question that the app user received for the defined question, determined by the questionID.
Please note: this is only applicable for scored survey activities.
Activity score:
{{activityResponseScore "activityID"}}
This CML reference displays the total score for the activity that app user received for the defined activity, determined by the activityID.
Please note: this is only applicable for scored survey activities.
Activity shortcut link:
{{activityLink "activityID"}}
This CML reference displays a link to a specific activity. When the user clicks this link, it will launch the specified activity determined by the activityID.
One application of this CML reference is to create a Navigation page.
Subject shortcut link
{{subjectLink "subjectID"}}
This CML reference displays a link to a specific subject. When clicked, it will launch the specified subject determined by the activityID and a list of all of the activities (that are not flagged as 'hidden) within this subject.
This will only work if the "explore" tab has not been hidden from the user.
App shortcut Link
{{appLink "appID"}}
This CML reference displays a link to a specific app within super app. When the user clicks this link, it will launch the specified app determined by the appID.
If you use a super app model that interconnect multiple sub-apps, this is a good way to present apps within the context.
Example form: {{appLink "5f32243aa957630017d22ce1"}}
Page shortcut link
{{pageLink "pageID"}}
This CML reference displays a link to a specific page, which is listed under the "more" tab. When clicked, it will launch the specified subject determined by the pageID.
Date of user's last activity completion
{{lastActivityResponseDate "activityID"}}
Use this CML to retrieve the date of the last time the app user completed the specified activity, determined by the activityID.
Mainly used for calculations in Advanced CML.
Timestamp of user's last activity completion
{{lastActivityResponseTimestamp "activityID"}}
Use this CML to retrieve the timestamp for the last time the app user completed the specified activity, determined by the activityID.
Mainly used for calculations in Advanced CML.
Image or file CML
{{file "fileID"}}
This CML reference displays a file such as image that is uploaded to Media Library
User profile CML
Here are some users' personal profile CML references that can make your text content more personalized. You can use this anywhere Rich Text Formatting text can be entered and displayed to the user.
User display name
{{user.displayName}}
Retrieves the display name the app user has set at account creation as part of their profile information.
Email address
{{user.email}}
Retrieves the account email the app user has set at account creation.
Platform profile: Last Name, First Name, Gender, Date of birth and Country
{{user.profile.lastName}}
{{user.profile.firstName}}
{{user.profile.gender}}
{{user.profile.dateBirth}}
{{user.profile.country}}
To reference Last name and First name, the app should enable those attributes on the app user profile information. (App Creator > Settings > User profile information). If you can't find these checkboxes from the profile list, please contact the platform admin.
Platform custom profile
{{user.profile.customData.dataLabel}}
{{user.profile.customData.dataLabel(csv).csvColumnName}}
Samples:
{{user.profile.customData.stateName}}
{{user.profile.customData.schoolName}}
{{user.profile.customData.Operation.BusinessName}}
{{user.profile.customData.Operation.Name}}
To reference the platform's custom profile, the platform should have a custom profile field set up on the Admin page (Admin > Account > User profile Information > Custom profile) and the app should enable those attributes on the app level.
If the custom profile used a .csv file with multiple columns, you can reference each column of data by using the header of the .csv file's column name.
App custom profile
{{appUser.profile.dataLabel}}
Samples
{{appUser.profile.workshopDate}}
{{appUser.profile.ageRange}}
{{appUser.profile.childInfo.childBirth}}
{{appUser.profile.childInfo.childName}}
{{appUser.profile.childInfo.childBirth}}
If it's repeatable group,
{{appUser.profile.childInfo.[0].childName}}
{{appUser.profile.childInfo.[1].childBirth}}
Finding specific IDs
Some CML references may require you to specify specific IDs for a question, subject, activity, option, or page.
Generally, all IDs are a string of numbers and characters, for example, it looks like this: 6026132abbe6cf002dcae33c.
The process of retrieving specific IDs involves navigating to the relevant section of Creator to copy the ID from the URL. The exception to this is for OptionIDs, where the ID of each option is displayed within the creator interface next to the individual options.
How to find QuestionIDs and Activity IDs
To get the questionID for a specific question:
Navigate to the desired content block (question) in Creator.
Copy the string of characters at the end of the URL address bar (after "question/")
For ActivityIDs, go to the Activity page, and copy the characters after "activities/" on the URL address bar.
For OptionIDs
To get the optionID for a specific question:
Navigate to the desired question in Creator.
Find the desired option in the question and copy the string of characters below "Id", located at the top of the options box
For ImageIDs or FileIDs
To get the imageIDs :
Navigate to the App Media Library in Creator by select any ‘upload media’ button.
Copy the string of characters from the selected media file details information.
