Skip to content
Snippets Groups Projects

CiviCRM v5.79 Form Token Notice

Last edited by totten

Synopsis

If you send emails with secure links to custom forms ("Form Builder" / "Afform"), then 5.79 has new options. You may wish to update them to use a simpler model.

Audience

Site-builders and system-administrators who:

  1. Upgrade to v5.79+, and
  2. Use custom forms ("Form Builder") with the "Message Token" feature.

About Form Tokens

"Form Builder" includes optional support for "Message Tokens". When enabled, the feature allows email-authors to easily link to the form:

screenshot

These links include an authentication code to identify the recipient/viewer. Links may work in two different ways:

  • Portal/Login Access: When you click the link, it opens the form and logs into the web UI. This is useful if you are curating a portal with several additional pages and forms.
  • Single Page Access: When you click the link, it opens the form. You can only access the one web-page.

These building-blocks must fit into your overall approach to designing the constituent experience. Compare:

  • With a portal approach, you need to design several pages. You should tend to the navigation-menu and be thoughtful about roles, permissions, security trade-offs. This can be rewarding if you're providing many features to your constituents, but it's more work.
  • With a single-page approach, your design is simpler. You design independent, free-standing pages -- they don't need to appear in a menu or use sophisticated role-configurations. This may not deliver as many features, but it is easier and safer to setup.

Prior to v5.79, there was no choice -- anyone who enabled authenticated form-links would use Portal/Login Access. However, we believe that Single Page Access is a better starting point for many CiviCRM administrators.

Going forward, Single Page Access will be available by default on old+new sites. Portal/Login Access will be an alternative option provided by an extension.

Upgrading

If you previously enabled Portal/Login Access on an earlier version, then you need an extension to continue this behavior. The extension will be auto-enabled.

However, you may wish to inspect the configuration and/or switch the options. Below, we give some tips and details about using different tools.

The Upgrader

When the upgrade starts, the system will identify any forms that use the "Message Token" feature. It will print a list of affected forms.

  • If you want to inspect more before the upgrade, then stop and restore your old code. (You may use other tools like "Form Builder" to inspect the initial configuration.)
  • Or proceed with the upgrade. It will preserve your current behaviors and auto-enable the appropriate extension. Later, you may use "Form Builder" to inspect/revise the options.

Form Builder UI

As a web-based user, you may inspect an individual form using the "Form Builder" UI:

  • Navigate to Administer > Customize Data and Screens > Form Builder.
  • Edit a form
  • Inspect the "Permissions" and "Placement" ("Expose To", "Accessible on front-end").

The display has changed on 5.79. Here are some example values you might see on 5.79:

Screenshot_2024-11-07_at_8.35.25_AM

If you wish to use Single Page Access, then:

  • "Permissions" must include a generic option. Good options are:
    • "Generic: Anyone with secret link"
    • "Generic: Allow any authenticated contact"
    • "Generic: Allow all users (including anonymous)"
  • "Accessible on front-end" should be enabled.
  • "Expose To" must specify "Message Tokens" (plain).

If you wish to use Portal/Login Access, then:

  • "Permissions" are open-ended. However, you must be mindful that the email recipients should actually have these permissions. (It doesn't make sense to send someone a link if they're not allowed to open it!)
  • "Accessible on front-end" should be enabled.
  • "Expose To" must specify "Message Tokens (Login)".

NOTE: It is easiest to understand if you only declare one permission. If you have multiple permissions, then pay attention to whether the "operator" is AND or OR.

API/CLI

If you manage many CiviCRM deployments, it may be easier to inspect the configuration via API/CLI. Here are a few example commands that may be useful:

## Display a list of forms which use portal/login-access
cv api4 Afform.get -T +s name,server_route,placement \
  +w 'placement CONTAINS msg_token'
## Display a list of forms which use single-page-access
cv api4 Afform.get -T +s name,server_route,placement \
  +w 'placement CONTAINS msg_token_single'
## Summarize key settings for a single form
cv api4 Afform.get +s server_route,placement,permission,permission_operator,is_public \
  +w name=afformExample

Appendix: Token Comparison

Version Approach Example
<=5.78 Portal/Login Template: Please login to the portal:
{afform.myFormUrl}

Output: Please login to the portal:
https://example.com/civicrm/my-form?_authx=XXX_authxSes=1
<=5.78 Single-Page (not available)
>=5.79 Portal/Login Template: Please login to the portal:
{login.myFormUrl}

Output: Please login to the portal:
https://example.com/civicrm/my-form?_authx=XXX&_authxSes=1
>=5.79 Single-Page Template: Please update your profile:
{form.myFormUrl}

Output: Please update your profile:
https://example.com/civicrm/my-form?_aff=XXX

Notes:

  • In 5.79, {form.*} indicates a single-page link to the form.
  • In 5.79, {login.*} indicates a login-link to the form.
  • In 5.79, {afform.*} is quietly deprecated. (The web UI no longer suggests it. It works as an alias for {login.*}.)
  • The notation {afform.*} is deprecated in 5.79. {login.*} is functionally equivalent.
  • In the "Example Output", the tell-tale sign of portal-login link is &_authx=....
  • In the "Example Output", the tell-tale sign of single-page access link is &_aff=....

Comments

    Please register or sign in to add a comment.