Description
As part of the Next Generation Certifications rollout, certification email templates run on a new template runtime. We migrate your customized template content automatically, and for most customers no further work is needed.
A small number of variable patterns behave differently on the new runtime. Where we could map an old variable to a new equivalent, we did so on a best-effort basis. This post covers those cases so you know what to check.
Uncommon attributes
These are edge cases. Adoption across the customer base of these attributes is very low (usually fewer than 10 total customers). None of these patterns were formally supported, and in several cases we expect they never worked as intended in the first place, or exist only in sandbox templates that were experimented with and left in place.
If none of the patterns below look familiar, your templates are almost certainly fine and no action is needed. We still recommend reviewing all templates and test sending beforehand for any attributes not supported formally in the available email templates.
Date values
Dates are the most likely place you will see a difference.
The new runtime cannot pass date objects the way the previous engine did. Date values now need to be wrapped in a $__dateTool.toDate() call before they can be used.
Old templates referenced dates in several different ways:
- Direct references, such as
$certification.expiration - Method calls on the date object, such as
$certification.expiration.toInstant().toEpochMilli() - Formatting helpers, such as
$spTools.formatDate($certification.expiration, "dd/MM/yyyy")
We map these where we can, but we strongly recommend testing them.
Custom variables created with #set
The previous engine let you define your own variables in a template using #set, including multi-line definitions. That capability carries forward, but the migration of existing #set blocks is best-effort and may not come across cleanly in every case, particularly for more complex or multi-line definitions.
If your templates define their own variables this way, we strongly recommend testing them.
Certification IDs
The variable $certification.id still exists and still resolves. The value it returns has changed format: the new certification engine uses UUIDs.
Nothing needs to change in your template. But if you have downstream automation, links, or integrations that parse or pattern-match on the old ID format, those will need updating. We saw this rarely, but not never, during our large scale Limited Availability.
Variables with a direct replacement
Two variables have been mapped to a new equivalent. If you used them, the migration substitutes the new name.
| Old variable | New variable | Notes |
|---|---|---|
certification.type |
campaign.type |
The old value could not be mapped one-to-one. The previous engine returned values such as Manager, ApplicationOwner, Identity, Group, BusinessRoleMembership, and BusinessRoleComposition from a single field. The new engine splits this across campaign.type and campaign.reviewerType, so depending on what your template was displaying you may need one or the other. Calls that reach into the old type class directly — for example ${certification.Certification.Type.getDefaultType()} — are not mapped and need to be rewritten. |
certification.activated |
campaign.activationDate |
Direct replacement. |
Variables with no replacement
The following are no longer available to certification email templates. If a migrated template references one, it will not resolve. Many of these were already not resolving, as they are not supported.
The list of available variables supported per template will be available in our documentation here: Available Email Templates - SailPoint Identity Services
| Variable |
|---|
certification |
certification.workitem |
certification.attributes |
certification.groups[] |
certification.entities[] |
certification.entities[].items |
$certification.getCertificationDefinition($spctx) |
workitem |
workitem.notificationConfig |
owner |
spctx, spcon, sailpointContext, spConn, SailPointFactory |
certification.getCreator() |
certification.getDescription() |
certification.description |
certification.displayName |
ordinalNumReminders* |
remindersRemaining* |
A note on reminders: While these were not resolving in a helpful way in the as-is platform, our team is planning to begin work on a revamp of Reminders and introducing Escalations later this year, which will include new variables to achieve what admins were attempting to do with these attributes before.