Using tokens in WMS Webforms


OVERVIEW

Target audience: Site Administrators, Site Managers

In the Web Management System (WMS), tokens make it possible to reference data provided by users when filling in a webform.

In this article:

Webform tokens

Tokens can be used to:

If an email template was created, view a complete list of available tokens by going to the E-mails settings on  the WEBFORM tab , clicking Edit on a template, and then clicking on the Browse available tokens link beneath the E-MAIL TEMPLATE text area.

This article only covers Current user and Submission tokens.

info

IMPORTANT:

The Webform Calculator module also makes use of tokens in Formula fields. However, these tokens can only be used to reference Number and Textfield components and have a different structure. To learn more about how tokens are used in Formulas, see Webform Calculator (Formula) module in the WMS.

Current user tokens

Current user tokens can be used to obtain information about the user, provided that the form requires authentication and the user is logged in. Below is a selection of tokens:

Name

Token  

Description

Example*

Name

[current-user:field_mcgill_user_name]

McGill username

Dylan McKay

Department

[current-user:field_mcgill_user_department]

McGill department to which the user belongs

Student Services

Email

[current-user:mail]

McGill email address

dylan.mckay@mcgill.ca

IP address

[current-user:ip-address]

User's IP address

132.456.789.101

Last login

[current-user:last-login]

Date and time user last logged in

Fri, 10/20/2020 - 09:46

McGill ID

[current-user:field_mcgill_user_id]

User's McGill ID

260123456

Roles

[current-user:roles]

User's role in the WMS

authenticated user, McGill Staff and Faculty

Telephone

[current-user:field_mcgill_user_phone]

McGill phone number

(514) 398-1234

Title

[current-user:field_mcgill_user_title]

McGill title

Event Coordinator

How to use Current user tokens

Current user tokens can be used with most components, particularly in the Default value and Description fields.

For instance, to create a form where the user's name is automatically filled in and cannot be changed, follow these steps:

  1. Add a textfield
  2. Place the following token in the Default value field: [current-user:field_mcgill_user_name]
  3. Check the Disabled option under DISPLAY
  4. Click Save component
  5. View the form and verify that the name of the current, logged-in user's name appears in the textfield
info

IMPORTANT:

Current user tokens can be used in webform emails. Please be sure to follow the security best practices outlined for the collection of confidential data (including McGill ID) in Create a Webform in the WMS.

Submission tokens

Submission tokens can be used to relay information collected from a form, when the user clicks on Submit or Next in a multi-page form where drafts are saved.

Below is a selection of submission tokens:

Name

Token  

Description

Example*

Date submitted

[submission:date]

Date the webform was first saved as draft or completed by the user

Mon, 05/07/2020 - 14:28

IP address

[submission:ip-address]

The User's IP address

132.456.789.101

Serial number

[submission:serial]

The serial number of this webform submission

1**

Submitter

[submission:user]

The user that submitted the webform result

dylan.mckay@mcgill.ca

URL

[submission:url]

The submission's URL

https://www.mcgill.ca/it/node/1234/submission/5678

Webform submission values

[submission:values:?]

Webform tokens from submitted data. Replace the "?" with the "form key", including any parent form keys separated by colons

See: Structure of a Webform Submission values token

*Default number for first submission

Structure of a Webform Submission values token

To include submitted form answers in emails or confirmation pages, use the Webform Submission values token.

The typical token structure is [submission:values:?] where ? is the form key.

The form key is the machine-readable name of the component which is being referenced. For instance, the submission token for a field labelled First Name, with the default form key first_name, would be [submission:values:first_name]. The form key can be seen by going to Webform > Form components. 

If this field is nested inside a fieldset labelled User Information with the default form key user_information, then the token would be: [submission:values:user_information:first_name] 

Additional keys

Webform Submission values tokens can be further refined by appending additional keys.

Question key:

This is the key for a specific question in a grid component. For example, a grid labelled Student Feedback with the question: How would you rate your course?

Question key

would have the token: [submission:values:student_feedback:course] 

Option key:

This is the key for a specific option in a grid or select component. For example, a grid labelled Student Feedback with the option:

option key

would have the token: [submission:values:student_feedback:excellent]

Display-related keys

How to use Webform Submission values tokens

Use Webform Submission tokens to include answers submitted by users in webform emails and confirmation pages.

For example, to include the name of an event for which a user is registering in an email from the form, do the following:

  1. Add a Select Options component labelled My Event (form key my_event) 

    select options component

  2.  Add at least 2 events as options
    • orientation|Orientation
    • career_fair|Career fair
  3. After saving the component, go to E-mails under the WEBFORM tab and click on Add or Edit
  4. In the E-MAIL TEMPLATE text area, remove the following text:

    Submitted values are:
    [submission:values]

  5. In its place, add the following:
    I will be attending the [submission:values:my_event] 

    email template

  6. Click Save e-mail settings. The email recipient would now receive an email that looks like this:

    submission value in email

references

ADDITIONAL REFERENCES: