The templates endpoints manage notifications templates and notifications contents. Each content is based on one specific template. Each template can be associated with multiple contents.

Each environment has a set of predefined notifications templates it can access. A template represents a specific process flow, for example, device_pairing or strong_authentication, that requires a notification. Each template defines the deliveryMethods (Email, SMS, Voice or Push) that it supports. You can read templates with this API, but you cannot create, update, or delete them.

Notifications templates settings

A content defines one message text choice for a notification. Each content is always associated with one template and has one deliveryMethod and one locale. Each template comes with one predefined default content for each of its supported deliveryMethods. You cannot delete or update the default contents with this API. However, you can create custom contents for a template (up to 1000 custom contents per template). To create custom contents, see Creating custom contents.

Notification templates assignment and initiation

A notification template is defined for a specifc process flow to convey information about the process flow to its user. Typically, a service provides a request that can assign a specific variant or a specific locale or both (for more information on variants and locales, see Creating custom contents) for a notification used by its process flow. For example, Create Credential Issuance Rule has a notification.template object that can set the notification template variant and locale for notifications sent when a user credential is created, updated, or revoked through Apply Credential Issuance Rule Staged Changes or its automated equivalent.

In this table, the notification template in Template name is assigned a variant or locale in the request in Defined by and the supported process flow begins with the request in Initiated by.

Runtime logic for content selection

Each content, whether default or custom, is associated with one template, one deliveryMethod, one locale, and optionally, one variant (for more information on variants, see Creating custom contents). When a request for content is executed at runtime, it includes a template, deliveryMethod, locale and, optionally, a variant.

1. PingOne matches the best text notification content for the user based on locale and variant name.

2. If a locale is specified on the request (for example, on the notification.template.locale property on POST /environments/{{envID}}/users/{{userID}}/devices), it overrides the user’s preferred language setting.

3. If the locale on the request (or the user’s preferred locale) does not match a notification content with the exact locale, PingOne uses the best matching locale (based on the language, ignoring the region) if available. For example, es-ES falls back to es.

4. For the locale property value, PingOne supports language tags with quality values as described in Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content.

5. For voice notifications, PingOne uses the best matching language based on the supported languages of the provider (Twilio, Syniverse, or a custom provider).

Content language selection examples

Creating custom contents

Add and update custom contents with POST /environments/{{envID}}/templates/{{templateName}}/contents and PUT /environments/{{envID}}/templates/{{templateName}}/contents/{{contentID}}. Each content is associated with one template and has one deliveryMethod and one ISO language code (locale). You can define multiple custom contents for each template + deliveryMethod + locale combination with the variant property.

Variants

If you have more than one custom content that uses the same template, deliveryMethod, and locale, these contents must have different values for the variant property. The variant property holds the unique user-defined name for each content variant that uses the same template + deliveryMethod + locale combination.

variant values can be reused by contents across different template + deliveryMethod + locale combinations. They need to be unique within the same template + deliveryMethod + locale combination only. As a best practice, use the same variant value for contents with the same message text. For example, the variant value variant_A can be used by a content with the strong_authentication + email + en combination and also by a content with the strong_authentication + push + en combination. For two contents that both use the strong_authentication + email + en combination though, if one content uses the variant value of variant_A, the other content must use a variant value such as variant_B.

Use PATCH environments/{{envID}}/templates/{{templateName}}/contents?filter=variant eq {{variantName}} to bulk update the variant value in contents with the same variant value. Use DELETE environments/{{envID}}/templates/{{templateName}}/contents?filter=variant eq {{variantName}} to bulk delete contents with the same variant value.

Variables

Variables are placeholders for values that change depending on the context. For example:

• The SMS content is Hi ${user.username}! Your one time passcode is ${otp}.
• The ${user.username} variable has a value of John.
• The ${otp} variable has a value of 548263.

The resulting message is:
Hi John! Your one time passcode is 548263, which includes the variable values John and 548263.

Predefined variables

If a template includes predefined variables, the template lists which variables can be optionally used in its contents and which variables are required in its contents. For example, user.username can be optionally used by strong_authentication contents, while otp is required for all SMS, Voice and Email contents.

"variables": {
    "user.username": {
        "required": false
    },
    "otp": {
        "required": true,
        "requiredForDeliveryMethods": [
            "SMS",
            "Voice",
            "Email"
        ]
    }
}

Dynamic variables

In addition to predefined variables, most templates also allow dynamic variables. If a template has the property allowDynamicVariables set to true, its contents can contain any user-defined variable in the format ${variable_name}.

Filtering result data

You can filter GET /environments/{{envID}}/templates and GET /environments/{{envID}}/templates/{{templateName}}/contents results by applying a SCIM filtering expression to the request URL. For large collections, a filtering expression appended to the query returns a targeted, more useful data set. For example, the following URL-encoded SCIM filter returns templates created before 2018-07-30 and updated after 2018-08-30:

https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/templates?filter=(createdAt%20lt%20%222018-08-30%22)%20and%20(updatedAt%20gt%20%222018-07-30%22)%20

SCIM operators can be applied to the following attributes:

Additionally, the logical and and or operators may be used for building compound expressions.

Ordering result data

You can order the collections returned by the GET collection endpoints according to the createdAt and updatedAt attribute. Ordering by any attribute returns the collection in a descending order. Using the attribute with the “-” prefix returns the collection ordered in descending order. For example, the following URL returns all the templates ordered by ascending creation date:

https://api.pingone.com/v1/environments/5caa81af-ec05-41ff-a709-c7378007a99c/templates?order=-createdAt

For more information about SCIM syntax and operators, see Conventions.

Properties

Template Properties

Content Properties {#notifications-templates-content-properties}

Audit reporting events

To see the effects of these events for an API call, see the event types in the Audit Report, Audit Activities API, or Webhook stream.

Response codes