Lotus Documentation

Placeholders

A placeholder is a string of the form ${type.name} or ${type.name(arguments)}, that will be replaced by the right value at run-time, that is when it is needed.
For example, in an email, in place of sending a message with ‘Dear pariticipant’, you can send a message with ‘Dear ${user.username}’ that will be replaced by ‘Dear Jan’ if the username of the participant is Jan.

There are different types of placeholders. Here is the complete description.

User placeholder: ${user.<name>}

<name> can be:

  • id: participant id, that is automatically generated by Lotus
  • status
  • Any participant parameter.
If you use a linked user parameter, per default the placeholder returns the value of the parameter that identifies the linked user. If you want another parameter of the linked user, use a second '.': e.g. if therapist is a linked user parameter, ${user.therapist} return the username of the therapist (if username is the parameter that identifies the user in the therapist project), and ${user.therapist.email} will returns the email address of the therapist.

Session placeholder: ${session.<name>}

<name> can be:

  • Any session parameter
  • name: name of the session

Project placeholder: ${project.<name>}

<name> can be:

  • Any project parameter defined in the ‘Custom parameters’ in the project main menu.
  • name: name of the project
  • url_name: URL suffix of the project
  • url_path: URL path of the project (where you can add custom files)

Timestamp placeholder: ${timestamp.<name>(arguments)}

This placeholder displays session timestamps in a format specified in the arguments.

<name> can be any timestamp name as:

  • StateInitialized
  • SessionOpen
  • SessionClose
  • TaskStarted (if the user has started the task)
  • ProjectPaused (if the user has been paused)

2 arguments are possible:

  • locale: defines which language will be used. Default is English. For Dutch, use ‘nld_nld’
  • format: this is the same format used by the PHP strftime function (cf. http://php.net/manual/en/function.strftime.php).
    The default format is '%A %d %B %Y %H:%M:%S'. The most used formats are:
    %A A full textual representation of the day Sunday through Saturday
    %d Two-digit day of the month (with leading zeros 01 to 31
    %b Abbreviated month name, based on the locale Jan through Dec
    %B Full month name, based on the locale January through December
    %m Two digit representation of the month 01 (for January) through 12 (for December)
    %Y Four digit representation for the year Example: 2038
    %H Two digit representation of the hour in 24-hour format 00 through 23
    %M Two digit representation of the minute 00 through 59
    %S Two digit representation of the second 00 through 59
    %s Unix Epoch Time timestamp: number of seconds sinds 1 jan 1970 305815200 for September 10, 1979 08:40:00 AM

Example: ${timestamp.SessionOpen(format=>%d %B %Y,locale=>nld_nld)} will display something like: 04 Mei 2013

Temporary placeholder: ${temp.<name>}

This placeholder displays the value of a temporary variable. A temporary variable is kept by Lotus as long as the participant is logged in. It can be set via the 'Set Random Parameter' action (typically used to set a random password, that can be sent in an email), or via the 'Set Parameter' action with the 'type' parameter set to 'temp'.

Link placeholder: ${link.<name>(arguments)}

This placeholder displays a URL link.

Name can be:

  • page: arguments is then the name of the page
  • event: arguments is then the name of the event
  • invitation: arguments can be then:
    • name: name of the invitation link. This is used in the participant log to identify which invitation link was used. If not set, it will use the name of the event or the page
    • page (default Status): which page has to be displayed if the user click on the invitation link
    • event: which event has to be triggered if the user click on the invitation link (if no page is defined).
    • days (default 5): how many days will be the invitation available. If set to 0, this invitation will be always available
    • only_once (default false): if true, the user can click only once on the link.
    • length (default 50): number of characters that composes the invitation link.
    • linked_user: if you want to send an invitation not to the current user, but to a linked user, you can specify here the ID of this linked user in this way:
      • linked_user=><user id>: e.g. linked_user=>123
      • linked_user=>array(temp=><name>) where <name> is the name of a temporary variable which was set previously to the ID of the linked user
      • linked_user=>array(urlQuery=><name>) where <name> is the name of a URL query variable that contains the ID of the linked user. This URL Query parameter can be set in the user event that calls the Email action: e.g. lotus/my_project/event/my_event?clientID=123
Example: ${link.invitation(page=>Status,days=>5}: the link will be available 5 days, and the user will be directed to the status page.

Input placeholder: ${input.<participant parameter>(arguments)}

The arguments is a list of parameter/value pairs separated by ',' in this way: param1=>value1,param2=>value2,...
This placeholder must be used in a form to display an HTML input field. The arguments are used to change the default settings. For example a label is associated to the input field, and per default this is the name of the participant parameter. But you may change this label in this way: ${input.username('label' => 'Give your username')}
Also you may want the input to be required, so that the form can't be submitted before this input is filled in: ${input.username('label' => 'Give your username', 'required' => true)}.
The type of the participant parameter will determine the (default) type of the HTML input:
  • String type: an HTML text input is generated. A typical argument would be the width of the text input.
  • Enum type: an HTML select element is generated, the options of this select correspond to the values of the enum parameters
  • Integer type: an HTML number input is generated.
  • Password & Encrypted types: an HTML password input is generated, the value is then masked
  • Date & Datetime: 3 or 5 HTML select input are generated corresponding to the year, month, day, hour and minute of the parameter. Typical arguments for this kind of input are:
    • minYear, maxYear: this set the range of the possible years
    • dateFormat: use it to set order of the Day, Month and Year input, e.g DMY for Day-Month-Year or YMD for Year-Month-Day
    • timeFormat: use it to set the hour range, i.e. 24 or 12 hour range.
  • Text: an HTML textarea input is generated. Typical arguments are rows and cols which define the number of rows and columns the textarea will have.
  • Linked user: an HTML select element is generated, the options of this select corresponding to the different values of the linked users.
The input type can be changed. For example a enum parameter can be set to generate radio buttons, by setting the type parameter to radio: e.g ${input.gender(type=>radio)}
Lotus uses the cakePHP form library to generate this input, and many more options are possible. For more detailed information about it, see CakePHP Form
One think to realize is that a participant parameter can get only one value. So to generate checkbox HTML elements with an 'enum' parameter with several values won't work, since this parameter can get only 1 value.
The only possibility to use a checkbox is with a enum parameter with only 1 value and with null value allowed. You can use this for example for informed consent: you make a enum participant parameter 'consent' with 1 value 'yes' and with the 'Allow null value' set. Then in your registration page, you add: ${input.consent('type' => 'checkbox', 'required' => true, 'label' => 'Do you agree in ...')}

It is also possible to use a name of a Timestamp in place of a participant parameter. For this add in the arguments the option isTimestamp=>true. If you want to set a permanent timestamp (a permanent timestamp is kept when the user goes to a new session), add the option: permanent=>true. If you want to set the time of this timestamp (when only the datum part is displayed), add the option setTime like this: setTime=>10:00

Typically a form with input placeholders will call a user event that creates a user (using the Create User action), or modify parameters (or timestamps) of a user (using the Save User Parameters action). The default settings of these actions are fitted to work smoothly with the input placeholders.

There exists also one special Input placeholder: the linkedUsers input placeholder. This placeholder will generate per default a dropdown input with all users linked to the current user. If you have several linked projects, you can specify which one(s) you want to use in the input by adding a 'projects' argument:
  • ${input.linkedUsers(projects => Clients)}
  • ${input.linkedUsers(projects => 'Clients1, Clients2')}

LinkedUser placeholder:
${linkedUser(<user id parameter>).<name 1>.[<name n>]}

Sometimes you would like to link a project to another one. For example, you have a project defined for the pupils and another one defined for the teachers: you would like to be able to link one pupil to his teacher.
For this, Lotus gives you the possibility to link a project to another one, and to define a participant parameter that links to a participant parameter of the linked project.
In the teacher/pupil example, you will add in the Pupil project the Teacher project as linked project in the 'Define project' menu. Then you add a participant parameter 'teacher' of 'linked user' type in the Pupil project. Per default, the 'teacher' parameter will be linked to the participant parameter in the Teacher project that identifies the users (for example, the username). Finally, when you edit a participant, you get automatically a dropdown of all teacher usernames in the teacher parameter: when you choose one, you have linked this pupil to his teacher.
Afterwards, when you want to access data between the linked users, you have 2 cases:
  • A user (let's say a pupil) has a linked parameter (let's say 'teacher') set to another user (the teacher of this pupil): to access data to this teacher from this pupil, you just have to use the participant parameter self:
    • ${user.teacher} gives the username of the teacher
    • ${user.teacher.email} gives the email of the teacher.
  • From the teacher user, you want to access data from one of his pupils: in this case, you need to know in one or another way the ID of this pupil, and use the linkedUser placeholder. This placeholder accepts different ways to specify this user ID:
    • ${linkedUser(<id>).email}: e.g. ${linkedUser(123).email}
    • ${linkedUser(temp=><name>).email}: where <name> is the name of the temp variable which was set previously to the ID of the pupil.
    • ${linkedUser(urlQuery=><name>).email}: where <name> is the name of a URL Query parameter which is passed in the URL of the page or user event (e.g.: /lotus/my_project/page/my_page?clientID=123, then use ${linkedUser(urlQuery=>clientID).email} to get the email of the pupil
    This works only if the ID you specify corresponds to a pupil that is linked to the teacher: Lotus will check this.
    In the previous examples, you can access a participant parameter (email) of the linked user, but you can access all other information related to this linked user (session, temp, project, etc...) in this way:
    • ${linkedUser(123).session.name}
    • ${linkedUser(123).project.name}
    If this user is also linked to other users, you can even nest the placeholder as many times as you want:
    • ${linkedUser(123).linkedUser(234).email}

To set a parameter in a linked user, use the Set Parameter action, with its linkedUser parameter.

Actions

Here is the list of all Lotus actions with their parameters. With all parameters, you can use placeholders.
The parameters are of type String, Text or Expression:

  • With a String parameter, you may use maximal 255 characters.
  • With a Text parameter, you can use as many characters as you need. You get also a popup window to allow you to write down a longer value for this parameter.
  • Expression means that the string will be evaluated: that means that you can use for example: '2 + ${user.points}' or 'substr(${session.name}, 10)'. All PHP functions are allowed, but only 1 PHP expression can be used, and PHP variables are not authorized.

It is also possible to have an expression inside a String or Text parameter: use for this '$expression[...]'. This might be useful in the message of an email for example:
Dear $expression[${user.gender} == 'M' ? 'Mr' : 'Ms'] ${user.username}.
You may start the training ${session.trainingNr}. For this click <a href="${link.page(Login)}">hier</a> to log in.
You still have $expression[10 - ${session.trainingNr}] to go, before getting your reward!
Kind regards.

When you use placeholders with String or Text parameters, the placeholders are just replaced in the string or text value.
When you use placeholders with Expression parameters, Lotus will automatically add single quotes around (except for placeholder that uses 'integer' parameter), so that it can be correctly evaluated by PHP.


Send Email

  • Goal: send an email
  • Parameters:
    • required to: email address(es) where the email will be sent. Several email addresses must be separated by a ‘;’.
    • required message: message of the email
    • optional subject: subject/title of the email
    • optional from: From which email address will be the email sent. This is of course fake, since the email is sent via Lotus. But this what the user will see. If the user wants to reply, this email address will be used (if no reply_to is used).
    • optional reply_to: Used if you want to use another address than the ‘from’ address, when the user sends a reply.
    • optional cc/bcc: list of email addresses (separated by ‘;’) where the email will be also sent as copy (or blind copy for bcc)
    • optional html_message: In message you can write (simple) HTML message, but you have to be careful that no all email clients support (complex) HTML. If you want to have 2 variants of your email, one with text and one with HTML, use the message & html_message parameters, so that both variants will be sent, and the email client can then decide which one it will use.
    • optional condition: expression that can be used to conditionally send the email
  • Explanation: If the email address(es) in the ‘to’ list are real email address(es), then this action will send the email. It can take 1 minute before the email is sent. If the server can see that the email has not arrived, a warning email will be sent to the from or reply-to email.
    If you use the condition parameter, you can precondition the sending of the email with any expression you want. Typically, use here placeholders to check whether the participant verify some conditions.

Send SMS

  • Goal: send an SMS
  • Parameters:
    • required to: 06 number where the SMS will be sent.
    • required message: message of the SMS. If the message has more than 160 characters, then it is divided in several messages. There is a maximum of 459 characters.
    • required title: title of the SMS. Its max length is 11 characters.
    • optional fallbackEmail: in opposite to E-Mail, it is possible to check whether an SMS has been received. In this case, you can set an email address to the fallbackEmail parameter so that the message will be sent as an E-Mail.
    • optional warningEmail: You can set also this parameter to send a warning E-Mail (to the E-Mail address set by this parameter) if the SMS has not been received.
    • optional condition: expression that can be used to conditionally send the SMS
  • Explanation: If the 06 nummer is correct, the SMS will be sent. The cost is 6 cents per SMS. The SMS provider will check whether the SMS is really received by the user: in the participant log, you should see when the SMS is sent, and when the SMS is received.
    If the SMS is not received, you can use the notReceivedEmailAddress to specify an email address where a warning EMail will be sent.
    It is also possible to condition the sending of the SMS by using the condition parameter: use here placeholders to check whether the participant verify some condition.

Randomization

  • Goal: randomize a participant parameter with an evenly distribution
  • Parameters:
    • required target: participant parameter that will be randomized. This must be an ‘enum’ type.
    • optional stratification: List of participant parameters (separated by ‘,’) of ‘enum’ type, used to stratify the randomization.
    • optional exclude: List of name/value (separated by ‘,’: name1=>value1, nam2=>value2) of participant parameter (of ‘enum’ type). All participants having for this parameter the associated value will be excluded from the stratification of the randomization.
    • optional weight_per_target_value: List of value/weight (separated by ‘,’: value1=>10, value2=>20). The values must be one of a value of the target parameter, weight must be an integer. If a target value is not in this list, its weight is set per default to 1. These weights are used for the randomization. For example if the target parameter has for value A en B, A has for weight 1 en B has for weight 2, then the chance to get the value B is 2 times bigger.

  • Explanation: The randomization can be done only with enumerative parameters. For example, let say that a project has for parameters:
    • condition: experiment/control
    • gender: male/female
    • studyLevel: high/middle/low
    • tester: yes/no
    You want to randomize condition with stratification on gender and studyLevel, you want to exclude the tester, and you want to have 2 times more experiment than control. Then you will set the action in this way:
    • target: condition
    • stratification: gender, studyLevel
    • exclude: tester=>yes
    • weight_per_target_value: experiment=>2, control=>1
    The randomization action will take care of an evenly distribution of the values (including the weight per value). That is, if in the project there are already these (not tester) participants:
    • 10 with condition=> experiment, gender=>male, studyLevel=>high
    • 5 with condition=>control, gender=>male, studyLevel=>high
    • 10 with condition=> experiment, gender=>male, studyLevel=>low
    • 6 with condition=>control, gender=>male, studyLevel=>low
    Then a new participant with gender male and studyLevel low, will get automatically the condition experiment, but a new participant with gender male and studyLevel high will get randomly experiment or control as condition.

Set Status

  • Goal: set the status of the participant.
  • Parameters:
    • required status: status that the participant will get. This can be StateInitialized, SessionOpened, TaskStarted, TaskFinished, SessionClosed, ProjectCompleted, ProjectExcluded, ProjectPaused or StateError.
    • optional condition: expression that can be used to conditionally set the status
    • optional actionsWhenSessionIsClosing: List of actions (separated by a ‘,’) that will be called when the status is set to SessionClosed.
    • optional actionsWhenSessionIsClosingAndTaskIsStarted: List of actions (separated by a ‘,’), that will be called when the participant has for status ‘TaskStarted’ and the status is set to SessionClosed.
    • optional endPauseOffset: if the status is set to ProjectPaused, you can use this parameter to the ProjectEndPause timestamp. This will be calculated from the current time, plus the offset (in days)
    • optional resetTimestamps: if the status is set to StateInitialized or SessionOpened, you can set this parameter to true, to reset the StateInitialized, SessionOpen en SessionClose timestamps relative to the current time.
    • optional taskName: if the status is TaskStarted, you can use this parameter to start another task than the current task.
  • Explanation: This sets a status to a participant, and in the same time, set a timestamp corresponding to this status. Some status have some rules:
    • The TaskStarted status can be set only if the participant has for status SessionOpened.
    • The TaskFinished status can be set only if the participant has for status TaskStarted.
    When status TaskFinished is set, Lotus sets automatically the participant to the next session (and gets the StateInitialized status) if a next session is defined. If no 'Next Session' is defined in the current session, then the participant's status is set to 'ProjectCompleted'.
    When status SessionClosed is set, if the setting 'Is Excluded If missed' in the current session is set, Lotus sets the participant's status to 'ProjectExcluded'. If 'Is Excluded If missed' is not set, Lotus reacts in the same way as with TaskFinished.
    When status TaskStarted is set, the task corresponding to the session (or the task set by the taskName parameter) is automatically started (if this action is activated by the participant).
    When status ProjectPaused is set, Lotus prevents all timed events for this user (and thus all reminders) to be fired, except timed events relative to the ProjectEndPause timestamp. Lotus sets also 2 timestamps to the user: the ProjectPaused and the ProjectEndPause timestamps. The latter is set per default to over 1 week, but you can change this with the endPauseOffset parameter.
    The resetTimestamps option works in this way: if you set the status to SessionOpened with resetTimestamps set to true, then the SessionOpen timestamp will be set to the current time, the SessionClose (and the StateInitialized) timestamp will be set to the current time plus the current difference between the SessionOpen and the SessionClose (resp. StateInitialized) timestamps.
    This option is interesting, for example, when you want to set a participant active after a pause: at the end of the pause period, you can trigger an event that executes an action that sets the status to SessionOpened with resetTimestamps. In this way the timestamps are set as if the participant had naturally passed the SessionOpen timestamp, and all the Timed events based on StateInitialized, SessionOpen or SessionClose will be fired at the appropriate time.

Set Session

  • Goal: Set the session of the participant.
  • Parameter:
    • required session: Name of the session
    • optional SessionOpen: Set the SessionOpen timestamp.
    • optional SessionClose: Set the SessionClose timestamp.
    • optional condition: expression that can be used to conditionally set the session
  • Explanation: Normally, the participants get the first session when they are created, and follow the session flow when they complete each task associated to the sessions. But there might be situation, where some participants cannot follow this flow, and must be set directly to a particular session. In this case, you can use this action.
    If you want also to change the SessionOpen & SessionClose timestamps from the default settings, use also the SessionOpen & SessionClose parameters.

Set Timestamp

  • Goal: Set a timestamp.
  • Parameter:
    • required name: Name of the timestamp to be set
    • optional value (default current time): value of the timestamp. Per default it is expected to be an integer representing the Unix timestamp (seconds since 01 jan 1970). If you use a string, set the format with the format parameter
    • optional format (default unix timestamp): set the format used if timestamp is a string. Format syntax is explained here: createDateFormat. Warning: this is not the same format as used in the timestamp placeholder!
    • optional offset (default 0): offset in second added to the timestamp value.
    • optional permanent (default false): if set to true the timestamp will stay over the sessions.
    • optional delete (default false): if set to true the timestamp will be deleted.
    • optional resetTimedEvents (values: no/always/onlyIfSetInFuture, default: no): per default if the timed events based on this timestamp are already fired, they won't be fired again. Use this setting to be able to fire them again.
    • optional condition: expression that can be used to conditionally set the timestamp
    • optional setYear, setMonth, setDay, setHour, setMinute: overwrites the year/month/day/hour/minute of the timestamp.
  • Explanation: Set a particular timestamp to a user. This timestamp can then be used for example in a timed event to trigger some actions.
    Per default all timestamps are deleted when a participant goes to a new session (SessionInitialized, SessionOpen and SessionClose are then set with the session settings). If you want a timestamp to stay across the sessions, set it as permanent.
    You may use this action to delete a (permanent) timestamp by using the 'delete' option.
    A timed event based on this timestamp might be already fired when this action is called. Per default, the timed event won't be fired again even if the timestamp is set in the future. If you want the timed events to be fired again, use the resetTimesEvents parameter: when set to always, all the timed events based on this timestamp will be fired, when set to onlyIfSetInFuture, only those which should be fired in the future (the offset of the timed event included) are reset. If the current time is given to the timestamp (default value when timestamp parameter is not set), then the timed event will be also reset.
    Here are some examples:
    • A participant may set a date participant parameter (myDate) via an input placeholder in the registration page, and you want to set this date as timestamp (triggerDate) to trigger some event. Set then name to triggerDate, value to ${user.myDate}, format to 'Y-m-d H:i:s'.
      If you want to set this date to a particular hour (10:00), add the setHour parameter to 10 and setMinute parameter to 0.
    • You want to set the SessionOpen timestamp to over 2 days from now. Don't set the value parameter (it takes per default the current timestamp) and set the offset parameter to expression 60 * 60 * 24 * 2 (60 seconds * 60 minutes * 24 hours * 2).
    • You want to set a timestamp to 3 days after the SessionOpen timestamp, and this timestamp to be used for the next sessions. Set value to ${timestamp.SessionOpen(format=>%s)}, offset to 60 * 60 * 24 * 3, and permanent to true.
    • You want to send a reminder every day to a user as long as the session is not finished. Set first a timestamp ReminderUser to 1 day after the SessionOpen, then add a SetTimestamp action (Reset Reminder) with name:ReminderUser, value:${timestamp.ReminderUser(format=>%s)}, offset to 60 * 60 * 24, resetTimedEvents:true, and set a timed event based on ReminderUser, which sends an email and calls the 'Reset Reminder' action.

Start a task

  • Goal: Start a task.
  • Parameter:
    • optional taskName (default current one): Name of the task to be started
    • optional setTimestamp (default false): Name of a timestamp to be set with the current time
    • optional setParameter (default false): set 1 or more parameters with a value. This list of parameter/value must be set in this way: param1=>value1, param2=>value2, etc...
    • optional permanentTimestamp (default false): set whether the timestamp will be a permanent one. If yes, then this timestamp will stay over the sessions
    • optional condition: expression that can be used to conditionally start the task
  • Explanation: This action starts directly a particular task. This action has to be used when you don't want to use the task associated to a session, but a task outside of the normal session flow. The task will be started, but Lotus won't update the status of the user.
    You can set a particular timestamp when using the setTimestamp parameter, this timestamp will be set then to the current timestamp. You can use this timestamp, if you want, in a timed event to trigger some actions.
    You can also set in the same time some parameter to some value by using the setParameter parameter.
    This action works only with a user event, not with a timed event. It has to be also the last action of the user event, since Lotus redirects the user to the task.

Save User Parameters

  • Goal: if on a page, you use input fields associated to some participant parameters, you can use this action so that when submitting the form, the values set by the user on these input fields will be stored to the corresponding participant parameters.
  • Parameters:
    • optional inputPrefix (default 'UserStateParameterValues'): if you use HTML input in your form that are not generated via the Lotus input placeholders (e.g. ${input.phone}), you can use this parameter to set the prefix used by all input names of your form.
    • optional fromQuery (default false): If the input comes from URL input query parameters, set this option to true, and all query parameters starting with the inputPrefix will be saved
    • optional successMessage: message displayed if the values are successfully saved.
    • optional errorMessage: if there is no constraint error, and still the input cannot be saved, this message will be displayed.
  • Explanation: on a (custom) page, if you have a form with input fields (for example: ${input.phone} or ${input.email}), when the participant submit the form, the data will be sent to the server. If you want Lotus to save these data, you can use this action: Lotus will set for each parameter the corresponding value set by the participant. If you have set for this parameter a constraint (in the Parameter Definition page), and that the value does not meet this constraint, the error message corresponding to this constraint will be displayed.
    For example, the email parameter can have for constraint a valid email address, and that it must be unique. If the value set by the participant is not a valid email address or another participant has already this email address, the corresponding constraint message will be displayed.
    If Lotus saves successfully the data, it will display the successMessage. If you do not want a message, set it to false.
    If the input parameters come from URL query parameters, set fromQuery to true. If you have a inputPrefix set to 'user', then an URL like: lotus/myproject/event/myevent?user[tel]=0612345678&user[gender]=man will set the 'tel' and 'gender' participant parameters (if the myevent event calls your action).

Set Random Parameter

  • Goal: generate a random string for a parameter.
  • Parameters:
    • required parameter: participant parameter that will receive the random string
    • optional length (default 8): length of the random string
    • optional message: if set, this will be displayed when the action succeeds.
  • Explanation: This action is typically used for generating new password. A password parameter is afterwards always encrypted and cannot be read anymore with its original value. So if you want for example to send this password in an email, you cannot use the placeholder ${user.password}, since it will give the encrypted value. For this, the random string is also stored in a temporary variable (which is available only the time of the duration of the request). This temporary variable can be retrieved via the ${temp.<name>} placeholder (cf. here).

Set Parameter

  • Goal: Set a value to a parameter. This value can be given via the value parameter, or via the URL.
  • Parameters:
    • required parameter: the parameter to be set.
    • required value: the value.
    • optional condition: expression that can be used to conditionally set the parameter
    • optional fromUrlQuery: name of the URL query parameter, whose value will be used as value. The ‘value’ parameter is then used as default value if the URL query parameter does not exist.
    • optional fromUrlPath: if the value of this parameter is found in the URL path, then it is used as value for the participant parameter. You can set several values separated by commas: red, blue, green. The ‘value’ parameter is then used as default value if the URL path does not contain any of the values.
    • optional fromForm: name of an input HTML field that gives the value of the parameter. If this name is found in the form, then its value is used, if not the 'value' parameter is used as default.
    • optional type (default 'user'): you can specify which kind of parameter is used. You have the choice between 'user' (the default), 'session', 'project' and 'temp'
    • optional linkedUser: if you want to set a parameter not to the current user, but to a linked user, you can specify here the ID of this linked user in this way:
      • <user id>: you can give directly the linked user ID
      • temp=><name> where <name> is the name of a temporary variable which was set previously to the ID of the linked user
      • urlQuery=><name> where <name> is the name of a URL query variable that contains the ID of the linked user. This URL Query parameter can be set in the user event that calls this action: e.g. lotus/my_project/event/my_event?clientID=123
  • Explanation: Use this action to set a particular value to a parameter. Per default this will set a participant parameter (type is 'user'), but you can also set a session, a project parameter or even a temporary parameter.
    You can use straight value, but you can use also an expression. For example, you can mix a mathematical expression with other participant parameters: 10 * ${user.points} + 1

    If the participant clicks on a link (that can come from another website) that calls an event of your project, you may want to set a particular parameter of this participant. For this, associate this action to the user event, and use the URL parameters. You have 2 kinds of URL parameters for this action: If you want to use a query parameter in the URL, use fromUrlQuery. For example if the URL is: www.test.uva.nl\lotus\my_project\event\my_event?from=hier , and you want to set the participant parameter ‘origin’ to ‘hier’. Then add a ‘Set Parameter’ action to the my_event user event, and set the action parameters in this way:
    • parameter: origin
    • value:
    • fromUrlQuery: from
    Then the participant will get ‘hier’ as origin. The value parameter is used as default (if the from query is not in the URL).
    If you want to use a subpath of the URL, use fromUrlPath. For example, if the URL is www.test.uva.nl\lotus\my_project\event\my_event\there , and you want to set the participant parameter ‘origin’ to ‘there’, then set the action parameters in this way:
    • parameter: origin
    • value: hier
    • fromUrlPath: hier, there, nowhere
    Then the participant will get ‘there’ as origin, because ‘there’ is in the URL path (after the name of the event), and it is one of the value given by fromUrlPath. The value parameter is used as default: if one of the 3 values in fromUrlPath was not found in the URL path, then this default value would be used.

    Another way to set a parameter is to use a page with a form. In this form you have HTML input parameters. When you submit this form, the name/value pairs of this form will be sent. If this is sent to a Lotus event of your project, you can use this action to set a parameter to one of the values of your form. For this set the parameter fromForm to the name of the HTML input, and the corresponding value of this input will be set to the parameter. For example, you want to set the parameter 'origin', and you have an input <input name="from"/>, then set the parameters of this action in this way:
    • parameter: origin
    • value: hier (this will be the default value)
    • fromForm: from
    If you want to set all parameters from a HTML form that uses input placeholders, it is then better to use the Save User Parameters action.

    We have shown until now only examples which set participant parameters, but this action can also set session, project or temporary parameters. A typical project parameter that can be updated via this action is the number of participants registered: add a project parameter, e.g. nbOfParticipants, and set it to 0, and call this action each time a participant is registered by incrementing the value (by using the expression ${project.NbOfParticipants} + 1)
    A temporary parameter does not have to be defined beforehand, Lotus just keeps it in memory as long as the participant is logged in. You can use temporary parameter with placeholders.

Conditional Action

  • Goal: execute one or more actions depending on a condition
  • Parameters:
    • required condition: string that will be evaluated to a Boolean.
    • required trueAction: the name of the actions (separated by ‘,’) that will be executed if the condition is evaluated to true
    • optional falseAction: the name of the actions (separated by ‘,’) that will be executed if the condition is evaluated to false. This is not required. If the condition is evaluated to false, nothing is done.
  • Explanation: this action evaluates the condition parameter, and then process either the trueAction or the falseAction (if it exists). You can use any PHP function and operation in the condition parameter, it will be then evaluated to a boolean.
    The condition parameter can be of String, Expression or even Text type, the placeholders in this case will be replaced in the right way so that the value be a valid PHP expression:
    • ${user.condition} == 'control'
    • substr(${session.name}) == 'Training 2'
    • ${user.trainingNr} < 5

Identify User

  • Goal: identify a user (either via input in a form, or via URL parameters), and if needed, log him in the project.
  • Parameters:
    • optional fromForm (true/false, default true): use the data from the form to identify the user.
    • optional inputPrefix (default 'UserStateParameterValues'): if the user is identified by form, this parameter sets the prefix used by all input names. If you use a page generated by Lotus via Input placeholders, then the HTML Input will have automatically 'UserStateParameterValues' as prefix name.
    • optional fromUrlQuery: name(s) of the URL query parameters used to identify the user. Several names must be separated by ','. Those names must also correspond to the participant parameters that will be used to identify the user.
    • optional fromUrlPath: name(s) of the participant parameters used to identify the user. The values of those parameters must be in the same order in the URL path.
    • optional login (true/false, default true): If the user is correctly identified (either by a form, URL queries or URL path), then you can use this parameter to log in or not the user.
    • optional successMessage: message displayed when the user is successfully identified. If set to false, no message is displayed.
    • optional errorMessage: message displayed when no user could be identified. If set to false, no message is displayed.
  • Explanation: You can identify a user either via a form (with HTML input), via URL queries or via URL Path.
    When you use a page generated by Lotus (like the Login page), the input placeholders generate automatically HTML Input in this way:
    ${input.username} => <input name="data[UserStateParameterValues][username]"></input>
    These input are sent to Lotus when the form is submitted, and their names are used to recognize which participant parameter is used for each value.
    If you don't use this input placeholder, and create your own HTML input, or you use a page not generated by Lotus, then you may change the inputPrefix parameter so that it fits your needs (you can also set it empty).
    If you want to identify the participant via a URL, you have 2 possibilities. If you have a User Event called 'identify' for example, then you can send the values in these ways:
    • Via URL Query: /lotus/my_project/event/identify?username=toto&password=123. For this you need to set the fromUrlQuery parameter to 'username, password'
    • Via URL Path: /lotus/my_project/event/identify/toto/123. For this, you need to set the fromUrlPath parameter to 'username, password'
    If the user is identified, you can tell Lotus to login the user or not. Typically, a login page uses a 'Identify User' action with parameter login set to true.
    But for example a Forgot Password page needs an action that identifies the user, so that it can send an E-Mail to the right user, but you don't want necessarily the user to be logged in your project. In this case, set the login parameter to false.
    If the user is successfully identified (or not), you can use the successMessage and errorMessage to display a message to the user.

Logout

  • Goal: logout the user
  • Parameter:
    • optional message: if false, no message is displayed. Else this message is displayed when the user is logged out.
  • Explanation: This action is typically used for the logout event.

Create User

  • Goal: create a new user. The data of the user must come from an HTML form or from URL query parameters
  • Parameters:
    • optional login (true/false, default false): If the user is successfully created , then you can use this parameter to log in or not the user.
    • optional inputPrefix (default 'UserStateParameterValues'): This parameter sets the prefix used by all input names. If you use a page generated by Lotus via Input placeholders, then the HTML Input will have automatically 'UserStateParameterValues' as prefix name.
    • optional fromUrlQuery (default false): If you call this action via a user event with query parameters, the action will use these query parameters (if fromUrlQuery is set to true) to set parameters of the created user.
    • optional successMessage: message displayed if the user is successfully created. If set to false, no message is displayed.
    • optional errorMessage: message displayed when the user could not be created. If set to false, no message is displayed.
  • Explanation: This action is used when you want to register a new participant (typically in the registration page, but this can be used in any (custom) page.
    You can use the login parameter to decide whether the created user is directly afterwards logged in your project. For example if you want to send a confirmation E-Mail after the registration (to check whether the E-Mail address is the right one), you will set the login parameter to false so the user cannot log in before he confirms his registration via his E-Mail.
    If you don't need such a check, you can set the login parameter to 'true' so that the new registered user can immediately continue with your project.
    If you make a custom page with input parameter not using the input placeholders, you may set the inputPrefix so that it fits the naming of your own HTML input.
    You may also create a user via URL query parameters. To do this, use the fromUrlQuery parameter, set a User Event (here my_create_user) that calls this action, and call this User Event is this way:
    • https://www.lab.uva.nl/lotus/my_project/event/my_create_user?username=john&email=john@gmail.com&gender=man
    You need in this case to set the inputPrefix parameter to nothing. Otherway you would need to specify the inputPrefix with square brackets: UserStateParameterValues[username]=john&UserStateParameterValues[email]=john@gmail.com

    If you want do display a message to the user, use the successMessage and errorMessage parameters.

Store Results

  • Goal: Store data from a task into the Lotus database.
  • Parameters:
    • optional outputParameters: 1 or several (separated by ‘,’) pair of names (output name => participant parameter name), used to set a particular participant parameter with a value of a result.
    • optional inputPrefix: Use this parameter if the names of the HTML input elements used to store the results have a prefix.
  • Explanation: Use this action to write the results of a task into the Lotus database. These results can be then seen in the ‘results’ page of Lotus.
    In order to work properly, the task must submit a form with (hidden) HTML input elements. The names of the input elements are used to set the names of the results: e.g. if the HTML element <input name="points"> has for value 120, the Lotus result will have for name 'points' and value '120'.
    Per default, if a name of an input element has the same name as a participant parameter, then the value of this input will be used to set this participant parameter. If the name of the input element does not correspond to the name of the participant parameter, you can use the outputParameters parameter. If you set it for example in this way:
    points => totalpoints.
    Then the value of the input element with name 'points' will be set to the participant parameter 'totalpoints'.
    If the HTML input elements have for names data[task][result1], data[task][result2], data[task][result3], etc... set the inputPrefix parameter to 'task' so that each input will be recorded separately with the their own name (result1, result2, etc...).

Store Flash Task Results

  • Goal: Store the data generated by a Flash task (embedded or popup).
  • Parameters:
    • optional taskNotSucceededMsg: message displayed when the task is successfully completed.
    • optional closedByUserMsg: message displayed when the participant close the Flash task (for popup flash task), before the end of the task.
    • optional technicalProblemMsg: message displayed when an error occurs during the task.
    • optional outputParameters: 1 or several (separated by ‘,’) pair of names (output name => participant parameter name), used to set a particular participant parameter with a value of an output of the Flash task.
  • Explanation: Use this action to write the results of a Flash task in the Lotus database. These results can be then seen in the ‘results’ page of Lotus. Per default, if an output of the Flash task has the same name as a participant parameter, then the value of this output will be used to set this participant parameter. If the name of the output does not correspond to the name of the participant parameter, you can use the outputParameters parameter. If you set it for example in this way:
    points => totalpoints.
    Then the value of the Flash task output points will be set to the participant parameter totalpoints.

Store Qualtrics Results

  • Goal: Store some results of a Quatrics survey in the Lotus database.
  • Parameters:
    • required username: username of the account of the survey
    • required token: token of the account of the survey
    • optional surveyID: ID of the survey. If not given, Lotus will try to find it in the URL used at the completion of the survey, or by trying to find it in the parameters of the task of the current session.
    • optional results: list of questionnaire ID’s (separated by ‘,’), that must be stored by Lotus. If this parameter is not set, all results of the survey will be stored.
    • optional parameters: list of pairs of questionnaire ID’s and parameter names (separated by ‘,’), like this: id1=>param1, id2=>param2. Use this option to set value of a question in a participant parameter.
    • optional parameterType (default 'user'): per default, if you use the 'parameters' parameter, you set Participant parameters. If you want to set temporary, project or session variable instead, set parameterType to resp. 'temp', 'project' or 'session'.
  • Explanation: Qualtrics stores the results of a survey in its own database. It is then not needed to store it in Lotus. But sometimes, you prefer to have the results stored in Lotus, or you need some answer to process further the user in Lotus. In these cases, use this action and add it to the user event that handles the end of the survey (cf here)
    This action uses the REST API of Qualtrics. Not all Qualtrics users have the permission to use this API: ask your Qualtrics administrator for this.
    For this API, the username and a token of the account where the survey has been made is needed. The token should be generated in the Qualtrics account (Account Settings/Qualtrics IDs).
    Furthermore, you must send the response ID from Qualtrics to Lotus: each time a participant answers a questionnaire, Qualtrics generates a unique Response ID. This ID is needed by Lotus to ask Qualtrics to send the answers for this Response ID.
    To do this, add in the URL redirect (Survey Options in Qualtrics) the placeholder ${e://Field/ResponseID}, e.g.: https://www.lab.uva.nl/lotus/my_project/event/end_qualtrics/${e://Field/ResponseID}.
    You can use the 'results' or 'parameters' parameters of this action, to store some answers of the questionnaire either in the Lotus results or in some participant parameters. If you don't use the 'results' parameter, all answers will be stored in the Lotus result. You can see then which ID is used by Qualtrics for each question, and use this ID if you want to set particular answer to a participant parameter.
    It is even possible to store a Qualtrics score: you can set in Qualtrics a score for your questionnaire, this score is then also stored in the results and you can use its ID to set it to a participant parameter. e.g. you define a score 'ScoreIQ' in your questionnaire, you have a participant parameter userIQ, then add the 'parameters' parameter in this action and its value would be: ScoreIQ/Sum=>userIQ.
    If you want to set a a Temporary variable instead of a Participant parameter, set the parameterType to 'temp', and then all parameter names listed in the 'parameters' parameter will be considered as names of temporary variables. In the same way, if you set parameterType to 'project' or 'session', you will set Project or Session parameters.

Jasmin Handler

  • Goal: Handle the requests of a Jasmin task
  • Parameters:
    • optional language (default dutch): which language must be used to handle the request.
    • optional folder (default empty): In which folder must be found the translation file.
    • optional translationFileName (default translations): Name of the translation file.
    • optional endTaskEvent (default 'End Task'): User Event that must be called at the end of the Jasmin task.
  • Explanation: A Jasmin task sends continuously requests to Lotus to ask some data, or to store data. For this a user event with this action must be added in your project. This will send all information needed to start the task, and it will store all results in the database.

Send Direct Message Twitter

  • Goal: send a direct message via Twitter to the participant.
  • Parameter:
    • required to : The participant's twitter username, if you declare a new participant paramter named Twitter you use it with this placeholder ${user.twitter}.
    • required message : Message to be sent.
    • optional accessToken : Key to declare if you want to use your own twitter application.
    • optional accessTokenSecret : Key to declare if you want to use your own twitter application.
    • optional apiKey : Key to declare if you want to use your own twitter application.
    • optional apiSecret : Key to declare if you want to use your own twitter application.
  • Description: To get more informations about how to connect lotus with twitter, please check the Advanced Module II : Twitter in the tutorials.

Generate PDF File

  • Goal: Generate a PDF File from a HTML source.
  • Parameter:
    • required content : The HTML content that must be transformed in PDF format. If you specify here a URL (a string starting with 'http'), then this source will be loaded and transformed in PDF
    • optional name : Name of the generated PDF file
    • optional orientation (default 'P') : Orientation of the PDF page: Portrait ('P') or Landscape ('L')
    • optional format (default 'A4') : Format of the page. This can be A4, A5, etc...
    • optional language (default 'en') : Default language used for the locale of the messages.
    • optional font (default 'Arial') : Font used by the PDF.
  • Description: This action transforms a HTML source (either from a string or a URL) into a PDF file. For this, it uses the HTML2PDF library. For more information about this library go here.
    Be careful: this action must be the last one used in a user event, since it downloads the generated file and lets the control to the participant.

Custom

  • Goal: Create a custom action. This action has to be implemented in PHP.
  • Parameter:
    • required class: Name of the PHP class that implements the custom action.
    • Other parameters are possible, depending on the implementation of the action.
  • Description: You can always add your own specific action for your project. This action can be a sub-action of an existing action, so that you can add some functionalities for this particular action, or you can make a complete new action.

Tasks

Here is the list of all Lotus tasks with their parameters. With all parameters, you can use placeholders.
The parameters are of type String, Text or Expression. Text means only that you get a popup window to allow you to write down a longer value for this parameter. Expression means that the string will be evaluated: that means that you can use for example: '2 + ${user.points}' or 'substr(${session.name}, 10)'. All PHP functions are allowed, but only 1 PHP expression can be used, and PHP variables are not authorized.

When you use placeholders with String or Text parameters, the placeholders are just replaced in the string or text value.
When you use placeholders with Expression parameters, Lotus will automatically add single quotes around (except for placeholder that uses 'integer' parameter), so that it can be correctly evaluated by PHP.


Online

  • Goal: start an online task defined somewhere in the web
  • Parameters:
    • required url: the url address where the task can be reached.
    • isPost (optional, default false): set whether the url should be called with a HTTP Post or HTTP Get.
    • All other parameters will be send to the online task. If isPost is false the parameters are sent as query parameters: <url>?param1=value1&param2=value2. If isPost is true, then the parameters are submitted with the Post request.
  • Explanation: When your task is served somewhere in the web, use this task type. Set the url to the site of the task, and Lotus will issue a HTTP request to this site. The user ID will be automatically sent to the site along with all other parameters you define in this task. If the request is done via a HTTP Get request (this is the default), then you will see these parameters added in the URL as query parameters. If you choose to send the request via a HTTP Post, you won't see these parameters. All depends how the task server can read these parameters.
    Moreover, be sure that at the end of the task, the user is sent back to Lotus. For this it must call a user event (e.g. the 'End Task' user event).
    If you use Qualtrics for your task, it is also possible to add a Store Qualtrics Results action in the user event, so that all or some of the results will be stored in the Lotus database, and also to set some participant parameters with these results.

FlashEmbedded/FlashPopup

  • Goal: start a Flash task either embedded in the page, or as a popup page.
  • Parameters:
    • required swf: Name of the Flash swf file that must be called. This file must be uploaded to the server via the 'Upload' menu.
    • optional path (default empty): Path where the swf file must be found.
    • optional width : Width of the Flash task. If this parameter is not set, then the default width of the task will be used.
    • optional heigth : Height of the Flash task. If this parameter is not set, then the default height of the task will be used.
    • optional endTaskEvent (default 'End Task'): user event that must be called at the end of the flash task. IF you want to store the data, add in this event a Store Flash Task Results action
    • optional specialOutput (default empty): all the data returned by a Flash Task will be returned in one big string, that will be stored in a database by Lotus. But Lotus cannot use this data to get specefic information. For this, the Flash task can output specific information to special output. This output must be defined in this parameter. If you have several ouputs, separate them with a semi-colon ';'. The Store Flash Task Results action can read this output and set some user parameter with it.
    • All other parameters will be send as input for the Flash Task.
  • Explanation: Use this task when you have a Flash Task which is not served on another server. Lotus offers the possibility to support such a Flash Task: it can sends input parameters, and can store the results.
    For this, you must first upload the swf file, with all stimuli if necessary, to the server (use for this the 'Upload' menu). The Flash task must be programmed in a way that it fits to the interface Flash/Lotus. For this the Flash task must use these functions:
    • getParameters: this function returns the input parameters (in a array): that is all parameters set in the Lotus task, apart the swf, endTaskEvent and specialOutput parameters.
    • writeExperiment: this function writes the results of the Flash task in an HTML input, that will be submitted at the end of the task.
    • finalize: this function must be called when the Flash task has completed. Lotus then submit the answers to the server, and call the end flash user event.
    • writeSpecial: this function can be used to set a value to a special output parameter (defined in the specialOutput parameter in Lotus)
    It is important to use the Store Flash Task Results action in the user event that will be called at the end of the task, so that Lotus can store the results, handle the special output, and even check whether the task has not finished abnormally.
    If the FlashPopup version is chosen, then the Flash task start on a new window. This has the advantage that Lotus can control better whether the user closes prematurely the task or not. But for this the browser must allow the popups. If you are not sure that the browsers of your users will accept popup, then choose the FlashEmbedded version.

Jasmin

  • Goal: start either a pre-defined Jasmin AAT, VPT, STROOP or a BIAT Task, or a custom configured Jasmin task
  • Parameters:
    • optional config: set the configuration of the Jasmin task. If this is set, then the other parameters won't be used. See Jasmin documentation to know how to specify its configuration
    • required task : can be 'aat', 'vpt', 'stroop', 'biat'. Set which pre-defined task will be started.
    • optional jasmin_handler (default 'Jasmin Handler': set the user event that will handle the jasmin request.
    • optional graphics_folder (default 'graphics': set the folder where the graphics will be located
    • optional stimuli_folder (default 'stimuli/alcohol': set the folder where the stimuli will be located
    • optional stimuli_extension (default '.jpg': set the kind of stimuli files that will be used.
    • optional train.placebo (default placebo): define whether the task will use the placebo or the experimental stimuli
    • Parameter used for aat or vpt tasks. These tasks have 2 versions (training or assessment). A training version has 3 parts (practice, assessment and training), and an assessment version has 2 parts (practice and assessment).
      • optional type: set whether the task will be a training or an assessment version
      • optional aat_approach (default 'right'): define whether a right or left approach will be used for a aat task.
      • optional practice.reps (default 3): define how many reps for the practice part of the task
      • optional assess.reps (default 2): define how many reps for the assessment part of the task
      • optional train.reps (default 2): define how many reps for the training part of the task
      • optional train.stimuli: list of the name of the stimuli used for the training type. This must be a list separated by ',': "a1", "p2", ...
      • optional assess.stimuli: list of the name of the stimuli used for the assessment type. This must be a list separated by ',': "a1", "p2", ...

  • Explanation: Use this task when you want to use either one of the pre-defined Jasmin task (AAT, VPT, STROOP or BIAT), or to use your own Jasmin configuration. Use the 'Upload' menu to load all the stimuli files.
    This task must be used together with the Jasmin Handler action (that must be set in the 'Jasmin Handler' user event).

Expression

  • Goal: use an expression to start a pre-defined task
  • Parameters:
    • required taskName : give the name of the task that must be started.
  • Explanation: You can use this type to use a placeholder or an expression (by using the expression type for the taskName parameter), to determine which real task the user will start.

Custom

  • Goal: start a custom task. This action has to be implemented in PHP.
  • Parameter:
    • required class: The class name used by this task.
  • Description: You can always add your own specific task for your project. This task can be a sub-task of an existing task, so that you can add some functionalities for this particular task, or you can make a complete new task.

Parameter Types

You can define parameter for participants, sessions and projects in Lotus.
Here is a description of what kind of types you can use.

String

This is the most common type. An input field using such a type will use per default an input text. The value may have maximum 1023 characters.

Enum

This is the enumerative type. You can define the values that will be used for this parameter. Moreover you can select a color for each value: in this way, you can have a nice overview of your participants or sessions.
Per default, a ‘enum’ parameter will be displayed with a dropdown input.

Integer

Used for integer parameter. Per default the input field will be of a number type (for HTML5 compatible browser).

Password

This is the typical type used for password.
This is a one-way encryption type: that means that when the value is encrypted, it is not possible (even for Lotus) to decrypt it. The only thing that can be done by Lotus is to compare the encrypted string with another one, and to guess that the password is the same.

Encrypted

This is a two-way encryption type: that means that the value will be encrypted in the database, but Lotus will be able to decrypt it when needed.

Date/Datetime

With such a type, you get per default 3 or 5 dropdowns as input field: day/month/year and hour/minute

Text

For string values that may exceed 1023 characters, use this type. The default input field will be a textarea.

Linked User

This is a special type used only for participant parameter. For this, you must first link your project with another project (in the Define Project/general menu). Then you can define a 'linked user' parameter by selecting the linked project you want to use.
An input placeholder using this parameter, will automatically show all possible users of the linked project (c.f. Input placeholder).
A user placeholder using this parameter, will automatically display the identifying parameter of the linked user (c.f. User placeholder)

Expression

You can use this type to use PHP expression and placeholders to compute a value that is commonly used in your project.
For example, if you have the participants parameter 'firstName' and 'lastName', you can add another participant parameter 'fullName' with as expression: ${user.FirstName} . ' ' . ${user.lastName}

User Parameter Constraints

You can use constraints to ensure that the value entered by a participant for some parameter will follow some rule. Several constraints per user parameter is possible.
For each constraint you have to specify its type, some argument(s) if needed, and the error message that will be displayed if the participant sets a wrong value.

The different types of constraints are:
  • email: Value must be a valid email address. No argument is needed
  • phone: Value must be a valid US phone number. To validate non-US phone numbers, you can provide a regular expression as the second parameter to cover additional number formats (e.g. /^06[0-9]*$/ for 06 mobile number)
  • custom: Used when a custom regular expression is needed. This regular expression is set in the argument field. For example, to ensure that a value will of the form '000..999', use /^[0-9]{3}$/. For more details over regular expression click for example here
  • alphaNumeric: The value must only contain letters and numbers.
  • range: This constraint ensures that the value is in a given range. The range is given by 2 integers separated by a space: '-1 11'
  • confirm: This is used to set the error message when an input element is used to confirm the value of a parameter. For example, a password parameter needs to be confirmed in the registration page. For this use the ${input.password()} and ${input.Confirm.password()} in the page, and set the error message as a confirm constraint.
  • equalTo: Ensure that the parameter is equal to the value set in the Constraint argument
  • unique: Ensure that the value of the parameter is unique amongst all participants. For example, a username or an email should be set as unique.
  • notEmpty: Basic constraint to ensure that a parameter is not empty.:
  • comparison: Used to compare numeric values. In the constraint argument you can set the type and the value of the comparison. For example '>= 18', '< 10' or '!= 5'
  • numeric: Checks whether the value is a valid number.
  • between: Checks whether the length of the string falls within a specified numeric range. This range must be set in the constraint arguments by 2 numbers separated by a white space.
Back to Top