Action Tags (Field Annotation)

1. Go to Project Setup → Online Designer → select the instrument

2. Next, either add a field or edit the field you would like to add the action tag to (edit by clicking on the pencil in the top, left corner of the question)

3. In the "Edit Field" or "Add New Field" box that pops up, go to the "Action Tags / Field Annotation" box in the bottom, left corner and click on Action Tags to see a list of Action Tags and to learn more about them

   Open

   

    

4. Select the action tag(s) you would like to use by clicking on "ADD" button on the left side of the action tag name.  Then close this action tag box. 

    

5. The action tag(s) will then be applied to the project field.  (Note: if the project is in draft mode, the changes will first have to be approved by a REDCap administrator before the action tag(s) work.)

• @DEFAULT: Sets a field's initial value. This allows a field to have a specified default value when viewing the field on a
  survey or data entry form that has not yet had any data saved for it

  • Use cases:
    1) Having numerous yes/no questions on a form, where almost all users will have the answer of ‘No’ for every
    question (saves data entry time).
    2) Setting a field’s value when all records will have the same value, such as project close out date or date of
    continuing review.

• @HIDDEN: Hides the data field on the survey page and the data entry form. Field will stay hidden even if branching
  logic attempts to make it visible

  • Use cases:
    1) Retiring a question/data field on both the form and survey so that the question no longer appears but no
    existing data for this question will be lost.
    2) Hiding calculated fields from those entering data and submitting surveys so that they cannot view that data but
    the data is still stored in the database and can be viewed by downloading the data.

• @HIDDEN-SURVEY: Hides the field only on the survey page (i.e., not on the data entry form). Field will stay hidden even
  if branching logic attempts to make it visible.

  • Use cases:
    1) Hiding questions or data fields from survey participants, such as fields calculating their BMI, age, instrument
    scoring, etc., but not from the data entry staff.
    2) Retiring a question/data field on a survey form so that the question no longer appears but no existing data for
    this question will be lost.

• @NONEOFTHEABOVE: Allows for the designation of a checkbox choice to be a 'none of the above' option, thus
  ensuring that no other choices are checked if that one choice is selected. This means that if that particular option is
  selected, it will alert the user that all other checked-off choices will be unchecked.

  • Use cases:
    1) Making it possible to have a 'None of the above' and/or ‘Refuse to answer’ option for a checkbox field without
    the risk of users mistakenly having other choices selected at the same time.
    2) Being able to use the ‘required field’ feature for checkbox field types when adding a 'None of the above' and/or
    ‘Refuse to answer’ option.

    • Example:  If you have a list of comorbidities you would not want someone to be able to select ‘None of the above’ and
      a comorbidity, since you would now know which answer was correct.

• @TODAY: Loads the current user's date into a blank Text field - similar to the @NOW tag but without the time portion.
  If the field has validation, the value will adjust to match the date format. Also, do not use this tag on fields with
  branching logic because it will always prompt the user to erase the value, so look at using @HIDDEN instead if you wish
  to hide the field.

  • Use cases:
    1) Having the today’s date or date/time field automatically populate today’s date or date/time to reduce data
    entry.
    2) When used with one of the @HIDDEN action tags, capturing a survey submission date on the last page of a
    survey which cannot be changed by the survey participant. Otherwise, a project user would need to run a report
    that includes the survey submission date/time stamp to get this information.

• It is important to realize that a field with @CALCDATE will not be editable on the survey page or data entry form, and the field will function almost exactly like a normal calculated field, in which its value may get updated via a data import of the date field it is referencing , when running Data Quality rule H, or in real-time during normal data entry on a form or survey.

• They function as a "pseudo calculation" field. They look and behave like a calculated field but are actually a date time field not a calculation field like the (datediff )calculation 

• This function can be used to produce a future or past date that is used in logical scenarios. For example, it can be used to calculate a date 6 months from enrollment, which is then used to trigger when 6mo surveys should be sent.
  
  

The Process - @CALCDATE

1. In Online Designer, create a date field. In this example the variable is [date1]

2. Create a separate field that is also a Text Box Date field

3. Add Action Tag @CALCDATE([date1],2,"d") to the field. 

   1. In this example…

   2. [date] = field name of the text field with date, datetime, or datetime_seconds validation)

      • You may specify (if needed) the event and repeating instance - e.g., @CALCDATE([baseline_event][visit_date], 7, 'd'

   3. 2 = the offset number amount that should be added or subtracted. It can be a decimal number or integer.

      • Tip: To subtract (i.e., go backwards in time), use a negative number

   4. "d" = represents the time specification units of the offset amount,

      • Can be represented by the following options: 'y' (years, 1 year = 365.2425 days), 'M' (months, 1 month = 30.44 days), 'd' (days), 'h' (hours), 'm' (minutes), 's' (seconds).

      • The unit option must be wrapped in quotes or apostrophes.

        • NOTE: Both the source field and the result field must be a text field with date, datetime, or datetime_seconds validation.
          
          

4. Below is a screenshot showing the field type, validation and Action Tag for a date 6 months in the future from a dob field

5. It is possible to have the initial field be a date-time field and the @CALCDATE field be a date field that would thus truncated the time if you just need the date later in the project.
   
   

6. You can also pipe in smart variable  to modify the fields as depicted in the clip below 
   
   

   1. Above you create the CalcDate unit value field [datacal_unit_value] and then pipe it into the Action Tag formula

   2. Change the value of the field (eg from 2 to 10) and the calculated date below will update
      
      

7. Using Piped Fields in the CALCDATE function - Example

   1. It is possible to combine use of @CALCDATE Action Tag with field piping.  Below is an example of inserting piped fields into a @CALCDATE equation:

       

      These are piped fields in the above screen shot.  So, if you are doing a research study and need to auto determine the dates of visits it can be done with @CALCDATE ACTION TAG.    

   2. [date1] = Date value of 10-23-2020 is normal Date / Time field (circled in green)

   3. Create the field CalcDate_unit_value [datecalc_unit_value] to type in an integer in the record. For example, 7 months (circled in blue). 

   4. Use the field CalcDate Units [datecalc_units] field as an offset to determine future time events.

      • As you change the CalcDate radio option, the @Calcdate Action Tag field beneath automatically changes.

   5. This is done by using piping in the CalcDate rules depicted below

• It is important to realize that a field with @CALCTEXT will not be editable on the survey page or data entry form, and the field will function almost exactly like a normal calculated field, in which its value may get updated via a data import, when running Data Quality rule H, or in real-time during normal data entry on a form or survey

The Process – @CALCTEXT
Below are screen shots of two text outputs based on the age of the participant:

1. In Online Designer, create field. In this example the variable is [age]

2. Create a Text Box field with an Action Tag of @CALCTEXT to output value as a non-numeric string.

   • In the above example the Action Tag formula is: @CALCTEXT(if([age]>=18,"adult","child")) which is stating that if the age is greater than or equal to 18, insert adult. If not, insert child

   • Note that is it possible to pipe the output of child like a normal calculated field.  Example above: You are a child

     • To pipe the output of the CALCTEXT field create a descriptive field,

     • Add in field label: You are a [age_status] where [age_status] is the calculated field with @CALCTEXT in this example

3. If desired, it is possible to return the value as a number - e.g., @CALCTEXT(if([age] >= 18, 'adult', 5[other_field])).

   • In this example the formula state if age if >18, insert Adult, otherwise insert 5.

4. You can use nested "if" statements (if inside of if) that result in multiple outcomes to differentiate logic.  Just like calculated field but output is alpha instead of numeric.

5. @CALCTEXT provides a way to do conditional piping (condition of child / adult in the above example)  into emails and other instruments

Additional Considerations

• CALCTEXT  cannot concatenate strings (eg put two or more text strings together). Must be static text or reference to a field

• These pseudo calc ACTION TAGS act like calculated fields so the Quality Rule H and with data import apply as they would with calculated fields

• You can not pipe field values into the quoted results (e.g., adult / child in the equation below)

  • @CALCTEXT(if([age]>=18,"adult","child"))