UserConsentService service
This functionality is available for Creatio 8.3.4 and later.
@creatio-devkit/common includes the UserConsentService service that lets you read and record user consents in Freedom UI pages. The service works with the "Consent" (Consent code) and "User consent history" (UserConsentHistory code) objects via the Model class and respects default access permissions and business rules. Learn more about Model class: Model class.
Before using the service, make sure the following conditions are met:
- A "Consent" (
Consentcode) object record with the target Code property exists and is readable in the current context. - The current user has read and insert permissions for the "User consent history" (
UserConsentHistorycode) object. - The custom request handler runs in a runtime context where
ModelandSysValuesServiceare available. For example, in request handlers. Learn more aboutSysValuesService: Display the value of a system variable.
UserConsentService applies the following rules when reading and recording consents:
- If an unknown consent code is used or the user already has an active record, the method call has no effect. This prevents duplicate consent records from being created.
- A perpetual consent (no expiration date) takes priority over any dated records. If a perpetual record exists, all dated records are ignored. If no perpetual record exists, only unexpired dated records are considered active.
- All data access goes through the
Modelclass, so default access permissions, validation, and business rules defined in the data model apply automatically. - The current user's contact ID is resolved once per service instance and cached. Subsequent calls reuse the cached value without additional lookups.
To access the UserConsentService service, use the sdk.UserConsentService.instance shared instance for the current page or runtime scope.
Methods
getConsent(code: string): Promise<Consent | null>
Loads the consent definition by code (text, name, ID) so you can show the user what they are accepting. Returns Promise<Consent | null> — the consent object containing its text, name, and ID, or null if no matching record exists.
Parameters
Parameter | Type | Description |
|---|---|---|
code | string | The code of the consent record to load. |
getCurrentUserConsent(code: string): Promise<UserConsent | null>
Returns the active consent record for the current user. Prefers perpetual consents (no expiration date). Otherwise, returns the most recent unexpired record. Returns Promise<UserConsent | null> — the active consent record, or null if the user has not accepted the consent or the record has expired.
Parameters
Parameter | Type | Description |
|---|---|---|
code | string | The code of the consent to check. |
giveCurrentUserConsent(code: string, expirationDate?: Date): Promise<void>
Records a consent for the current user (optionally with an expiration date) only when the consent exists and no active record is already present. If the consent code does not exist or the user already has an active record, the method call has no effect. Returns Promise<void>.
Parameters
Parameter | Type | Required | Description |
|---|---|---|---|
code | string | Yes | The code of the consent to record. |
expirationDate | Date | No | The expiration date of the consent. Omit to record a perpetual consent. |
Usage examples
The following example retrieves the consent definition on page load and checks whether the current user has already accepted it using the crt.HandleViewModelInitRequest request handler.
{
request: "crt.HandleViewModelInitRequest",
handler: async (request, next) => {
const someConsentCode = 'SomeTestConsent';
/* Retrieve the instance of the "UserConsentService" from "@creatio-devkit/common." */
const userConsentService = sdk.UserConsentService.instance;
/* Load the consent definition by code. */
const consent = await userConsentService.getConsent(someConsentCode);
/* The consent object contains the following properties: id, name, text. */
console.log(consent);
/* Check whether the current user has an active consent record. */
const userConsentValue = await userConsentService.getCurrentUserConsent(someConsentCode);
/* Returns "true" if the user has an active consent record. Otherwise, "false." */
const userAcceptedConsent = Boolean(userConsentValue);
console.log(userAcceptedConsent);
/* Call the next handler if it exists and return its result. */
return next?.handle(request);
}
},
The following example records a perpetual consent for the current user, that is, one that has no expiration date and never expires.
{
request: "usr.GivePerpetualConsentRequest",
handler: async (request, next) => {
const someConsentCode = 'SomeTestConsent';
/* Retrieve the instance of the "UserConsentService" from "@creatio-devkit/common." */
const userConsentService = sdk.UserConsentService.instance;
/* Record a perpetual consent (no expiration date). */
await userConsentService.giveCurrentUserConsent(someConsentCode);
/* Call the next handler if it exists and return its result. */
return next?.handle(request);
}
},
The following example records a consent with a fixed expiration date by passing a Date object as the second argument.
{
request: "usr.GiveConsentRequest",
handler: async (request, next) => {
const someConsentCode = 'SomeTestConsent';
/* Retrieve the instance of the "UserConsentService" from "@creatio-devkit/common." */
const userConsentService = sdk.UserConsentService.instance;
/* Build the expiration date (6 months from now). */
const expirationDate = new Date();
const monthExpiration = 6;
expirationDate.setMonth(expirationDate.getMonth() + monthExpiration);
/* Record a consent with an expiration date. */
await userConsentService.giveCurrentUserConsent(someConsentCode, expirationDate);
/* Call the next handler if it exists and return its result. */
return next?.handle(request);
}
}