Action tags are case sensitive, specifically, uppercase is required for action tags. This means action tags written in lowercase won't work, i.e. @hidden-survey will not hide a field from being presented on a survey, and @today does not add today’s date to a text field.

During our routine monitoring operations, we discovered a number of projects with lowercased action tags. We reached out to project point persons to recommend corrective action, which we are sharing below, to help folks, moving forward, should they run into the same issue.

Tips About How Action Tags Work

It's important to review, at a high level, how action tags work, especially when considering making changes to them.

  • Actions Tags are Real Time Actions

    • When staff open a form for data entry or a participant opens their survey, any action tags that have been added to the fields that make up that form or survey will try to perform their action. 

  • Types of Actions

    • Some action tags modify how a field behaves. For example, consider the @HIDDEN-SURVEY action tag. Applying this action tag to a field will hide it from being displayed for the participant when they complete their survey, but show it for the study staff when they are reviewing the participant's survey response.
      • Some other action tags that modify field behavior are: all the @HIDDEN- or @HIDE tags, @READ tags, @MAX tags, and @NONEOFTHEABOVE.
    • Some action tags return a value. For example, consider the @TODAY action tag. Applying this action tag to a field will automatically add today's date to the field, if its empty when the the participant or staff open the survey or form.
      • Some other action tags that return a value are: @SETVALUE, @DEFAULT, @CALCTEXT and @CALCDATE.
    • Because new action tags are introduced regularly, we're not listing out all the action tags and whether they modify field behavior or return a value.

  • Validate Action Tags by Testing

    • The only way to know an action tag is working as expected is to create test records and enter test data and/or test survey responses.

Find Action Tags with Invalid Syntax

  • In your project, open the Codebook.
  • Use your browser find feature and search for @.
  • Examine all the results, to check for action tags in lowercase.

Tips for Modifying the Case of Action Tags

  • Projects in Development

    • For any action tag that's been written in lowercase, change the case to upper, i.e. change @hidebutton to @HIDEBUTTON, and retest.

  • Projects in Production

    • In general, we recommend testing in a test copy of the project what happens when you change the case of an action tag from lowercase to uppercase, following the guidance for modifying forms or surveys.

    • For action tags that modify how a field behaves, we expect that testing will validate that when you change the action tag's case to uppercase, the outcome will be what was originally intended, i.e. action tag will perform it's action

    • For action tags that return a value, we expect that testing will help you determine if you want to change the case to uppercase or remove the action tag, so as not to return values on survey responses that have already been submitted or for data entry forms where data has already been collected. 

      • For example, if @today was added to a field on a survey, that field is empty for survey responses that have already submitted. But if you corrected the case and changed the action tag to @TODAY, it would create a data quality issue if any staff opened an already completed response and re-saved it, by saving today's date for the response, not the date the participant opened and submitted the survey. For that reason, we would recommend removing any occurrences of @today you discover in your project if it's in production.

  • No labels