This page has migrated to https://helpdocs.conducttr.com/feature-documentation/designing/scenario-design/dynamic-content/functions

Goal
After reading this article you'll:
  • know what functions are to you
  • be able to use functions in your exercises

Summary

Functions allow you to create more dynamic content by manipulating text and numbers.

 Name
Functions
 Benefits
Saves time and improves engagement through greater personalisation.
 Features
  • Many popular functions available for use in calculations and content.
  • Functions can be nested for even greater power


Available Functions


We've grouped the functions into several tables:

  • text functions 
  • number functions 
  • data functions

 Text Functions
 Purpose
CONCAT()
Adds together strings to create a new string.

|CONCAT("Rob","Bert")| returns RobBert

Can be any number of strings |CONCAT("rob","ert"," is ", " ","working"," ","today")|  returns "robert is working today"

Use with other nested string functions too |CONCAT("Rob",RIGHT("Bert",3))| returns Robert
LEFT()
Returns a new string for the length of characters starting from the left LEFT(string,length)

|LEFT("Robert",3)| returns "Rob"
LEN()
Returns the length of a string Example LEN("Robert") returns 6
LOWERCASE()
 Forces strings to lowercase.

|LOWERCASE("HElen")| = "helen"
MID()
 Returns part of a string MID(string, start, length) Example MID("Robert",3,4) returns "bert" All string functions cane be nested.

|UPPERCASE(MID("Robert",3,4))|                     returns "BERT"
REPLACE()
Replaces occurrences of a string within a string with another string :)

Format is REPLACE(string,what,by)

|REPLACE("i like to eat apples","a","@")| returns "i like to e@t @pples"
RIGHT
Returns a string of length characters starting from the right

Format is RIGHT(string, length)

|RIGHT("Mary had a little lamb",4)| returns "lamb"
STRCOUNT()
Returns the number of times a substring is found within a string.

|STRCOUNT("bird","a little bird sat on my window")| = 1

|STRCOUNT("a","it was a cold night and a bird pecked at an apple")| = 2
UPPERCASE()
 Forces string to all uppercase.

|UPPERCASE("hello")| = "HELLO"



Number Functions
 Purpose
 ABS()
ABS returns the absolute value (ie. removes the negative sign!)

ABS(-1) = ABS(1)
 AVG()
Returns the average in a list of numbers.

e.g AVG(56,27, audience.sender.my_score)

|AVG(partition.custom_data["a"], partition.variables[CONCAT("a.",audience.sender.hash,".my_score")])|

To find an average of an array:
AVG(partition.scores)

 FORMAT()
Used to make numbers look attractive - usually to reduce the number of digits after the decimal point. 

Example |FORMAT(3.1276565,"###.##")|  gives 3.13
 INT()
Forces value to an integer.

for example INT(12.45) = 12

Useful for converting a boolean to a value such as INT(5>2) = 1
 MAX()
MAX() returns largest number.

MAX(5, 4, 1, 12, 56,72) returns 72
 MIN()
MIN() returns the smallest number.

MIN(5, 4, 1, 12, 56,72) returns 1
 MOD()
MOD stands for modulo.

The function returns the remained after a division. The format is MOD(number to be divided, the dividing number).

This is most easily shown with an example such as breaking out hours, mins and secs from a duration:

Hours = |audience.sender.duration|/3600 Minutes = MOD(|audience.sender.duration|/60,60) Seconds = MOD(|audience.sender.duration|,60)
 SUM()
Returns the sum of all values e.g SUM(56,27, audience.sender.my_score)

|SUM(partition.custom_data["a"], partition.variables[CONCAT("a.",audience.sender.hash,".my_score")])|

To find the sum of an array:
SUM(partition.scores)
 
 




Date Functions
 Purpose
 DATETIME()
Formats dates and times. Please see the DATETIME() article for the full specification

Example
|DATETIME(NOW(),'MMMM d')| returns the current date in the format April 20

Recipe
You can add and subtract time from NOW() to calculate dates in the past on in the future. For example
|DATETIME(NOW()-'02:00:00:00','dddd')| will subtract two days from today's date and print the day of the week.  For example

"Hey, I know it was 2 days ago you looked into that issue because it was a |DATETIME(NOW()-'02:00:00:00','dddd')| "
 NOW()
 Returns current date and time
 NEXTWEEKDAY()
Creates a future date based on which day of the week and how many weeks from now. Use with DATETIME formatting for most practical result.

NEXTWEEKDAY(date, day of week number, number of weeks from date)

Example  
|DATETIME(NEXTWEEKDAY(NOW(), 6, 1),'dddd D MMM')| returns the date of Saturday one week from the scenario run date (i.e. from NOW())  e.g. from function given here Saturday 13 May 


Day of Week number
Sunday 0
Monday 1
Tuesday 2
Wednesday 3
Thursday 4
Friday 5 
Saturday 6

Recipe
Imagine you need a persona to send an email warning about a protest on a Wednesday four weeks from the time of the exercise. The content might look like this: 
"Hi, I'm writing to warn you of a march affecting access to your offices on |DATETIME(NEXTWEEKDAY(NOW(),3,4), 'ddd D MMM')|. I hope 4 week's notice is enough for you to organise remote working"