--- title: Agreement Management description: Agreements define the details of an agreement to which end users provide consent. An agreement consists of these PingOne resources: component: pingone-api page_id: pingone-api:platform:agreement-management canonical_url: https://developer.pingidentity.com/pingone-api/platform/agreement-management.html section_ids: agreement-configuration: Agreement configuration how-agreement-content-is-presented-to-users: How agreement content is presented to users agreement-consent-history: Agreement consent history agreements-events-generated: Agreements events generated assigning-admin-roles-and-permissions-to-this-service: Assigning admin roles and permissions to this service --- # 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](agreement-management/agreements-resources.html). * **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](agreement-management/agreement-languages-resources.html). * **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](agreement-management/agreement-revisions-resources.html). Learn more in [Agreements](https://docs.pingidentity.com/pingone/user_experience/p1_agreements.html) 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](language-management.html). | 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](users/user-agreement-consents.html). | ## 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](https://tools.ietf.org/html/rfc4646). For selecting a language code to use in an agreement, the API follows the matching of language tags described in [RFC\_4647](https://tools.ietf.org/html/rfc4647). 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` | ## Agreement consent history 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](audit-activities.html). 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: ```none 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 "" 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: ```none recordedat ge "2020-12-11T22:11:54.484Z" and recordedat le "2021-06-09T21:11:54.484Z" and resources.id eq "" and (action.type eq "AGREEMENT_CONSENT.ACCEPTED") ``` ## Agreements events generated Refer to [Audit Reporting Events](reference/audit-reporting-events.html) 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. | ## Assigning admin roles and permissions to this service Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to [PingOne Permissions by Service](reference/roles-and-permissions-in-pingone/permissions-by-service.html) for the service-specific permissions. You can also choose to assign admin roles based on particular service resources. Refer to [PingOne Permissions by Resource](reference/roles-and-permissions-in-pingone/permissions-by-resource.html) when assigning admin roles per service resources. Admin assignments to roles are set by: * [Automatic assignment for some roles](roles/predefined-roles.html#automatic-role-assignment). * [Group Role Assignments](group-role-assignments/group-role-assignments.html). * [User Role Assignments](users/user-role-assignments.html). Refer to [Roles Management](roles.html) for more information.