PingOne Platform APIs

Agreement Management

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, refer to 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, refer to 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, refer to Agreement Revisions Resources.

Learn more in Agreements in the PingOne admin guide.

Agreement configuration

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.

For information about the environment’s default language, refer to Language Management.

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.

For more information about the agreement resources described above and how these resources contribute to a user’s agreement consent state, refer to User Agreement Consents.

How agreement content is presented to users

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:

  1. User preference: The end user receives agreement content in the language that matches the user’s preferredLanguage property value.

  2. 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.

  3. 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, refer to 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")

Agreements events generated

Refer to Audit Reporting Events for the events generated.

The LOCALIZATION_STATUS.UPDATED events are consumed by the language management service and are used to verify whether localization is complete for a language for a specific service, which, in this case, is the agreements management service.

Use Cases