Agreements define the details of an agreement to which end users provide consent. An agreement consists of these PingOne resources:
Agreements resources
Defines the top level configuration for all the languages resources associated with the agreement. For more information, see Agreements Resources.
Language resources
Defines the configuation for the locale and for the configuration that applies to all revision resources associated with the language. For more information, see Agreement Languages Resources.
Revisions resources
Defines the specific version text (the agreement content) to manage the lifecycle of the agreement to which users provide consent. For more information, see Agreement Revisions Resources.
An agreement cannot be enabled unless it supports the default environment language. The agreement resource can have its enabled
property set to true
only if there is “agreement content to show” for the default environment language. If the enabled
property on the agreement resource is false
, the agreement cannot be presented to end users.
The condition of having “agreement content to show” requires that at least the environment’s default language is configured as an agreement language resource. The agreement language resource that supports the environment’s default language must be enabled. The agreement language resource can have its enabled
property set to true
only if there is “localized content to show” configured on its associated agreement revisions resource. If the enabled
property on the agreement language resource is false
, the agreement language cannot be presented to end users. Remember, you must enable the agreement language resource that represents the environment’s default language to enable the agreement. Additional agreement languages can also be configured and associated with the agreement.
The agreement revision resource associated with an agreement language resource must have text content (and it can have optional buttons and checkboxes) configured on the resource to meet the “localized content to show” condition to enable the language. For the agreement revision to be active, the agreement revision’s effectiveDate
property must not be set to a future date. However, the effectiveDate
value can be set to a future date, but the revision is inactive until the specified date.
Agreement languages are defined by either the language code (for example, en
) or the combination of language code and country code (for example, en-GB
). For identifying languages, the API follows the tags for identifying languages described in RFC_4646. For selecting a language code to use in an agreement, the API follows the matching of language tags described in RFC_4647.
When an agreement is active, languages are presented to the user in the following order:
User preference: The end user receives agreement content in the language that matches the user’s preferredLanguage
property value.
Browser preference: If the user’s preferredLanguage
is not configured (or enabled) as one of the supported agreement language resources for this agreement, the end user receives agreement content in the language associated with the browser’s configured locale.
Environment default language: If the browser’s configured language is not one of the enabled agreement language resources for this agreement, then the agreement content is presented to the end user in the environment’s default language.
The following table shows an example of how the platform presents agreement languages to users, depending on the environment default language, the configured agreement languages, and the user’s language preferences.
Environment default language | Configured agreement languages | User preference languages (ordered) | Language presented to user |
---|---|---|---|
es |
en , es |
en-US , es |
en |
es |
en-GB , es |
en-US |
es |
es |
en , en-GB , es |
en-US , es , en-GB |
en |
A user’s consents to agreements do not expire by default, but they can be configured to designate a re-consent action based on a specified length of time or the active date of an agreement revision. An environment supports up to 100 agreement resources.
Only the user’s latest consent information is kept in the API. Agreement consent history is visible through audit reporting events. For more information about audit reporting, see Audit Activities.
For example, to search for the consent history for a specific user to an agreement using the audit activities API, the query filter looks like this:
recordedat ge "2020-12-11T22:13:41.838Z" and recordedat le "2021-06-09T21:13:41.838Z" and resources.type eq "user" and resources.id eq "<user-id>" and (action.type eq "AGREEMENT_CONSENT.ACCEPTED")
To search for consent history for an agreement (showing consents for all users), the query filter looks like this:
recordedat ge "2020-12-11T22:11:54.484Z" and recordedat le "2021-06-09T21:11:54.484Z" and resources.id eq "<agreement-id>" and (action.type eq "AGREEMENT_CONSENT.ACCEPTED")
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.
The audit reporting events applicable to agreement consent history are:
Service | Event |
---|---|
agreements |
AGREEMENT.CREATED |
agreements |
AGREEMENT.UPDATED |
agreements |
AGREEMENT_LANGUAGE.CREATED |
agreements |
AGREEMENT_LANGUAGE.UPDATED |
agreements |
AGREEMENT_LANGUAGE_REVISION.CREATED |
agreements |
AGREEMENT_LANGUAGE_REVISION.DELETED |
users |
AGREEMENT_CONSENT.ACCEPTED |
users |
AGREEMENT_CONSENT.REVOKED |
users |
AGREEMENT_CONSENT.DECLINED |
agreements |
AGREEMENT_CONSENT.ACCEPTED |
agreements |
AGREEMENT_CONSENT.REVOKED |
agreements |
AGREEMENT_CONSENT.DECLINED |
agreements |
LOCALIZATION_STATUS.UPDATED |