Automate role-based license redistribution

Level: intermediate

After new users are added to Creatio, assigning licenses is required to grant access to platform functionality. Learn more about Creatio license types: Creatio licenses overview (user documentation).

Creatio supports manual and role-based license redistribution and provides tools to automate role-based redistribution. Learn more about ways to redistribute licenses: Manage user licenses (user documentation).

Choose the appropriate tool to automate role-based license redistribution based on the business goals listed in the table below.

Business goal	Tool to use	Use cases
Embed role-based license redistribution to any Freedom UI page	Custom UI element that calls the corresponding business process	Administrator needs automation while retaining control over execution Immediate, manually triggered role-based redistribution
Provide automatic role-based license redistribution during user lifecycle events	User task element that can be used in custom business processes	New users must receive licenses automatically after they are created via a custom workflow Licenses must be updated when user roles change after they are created via a custom workflow Redistribution is part of a recurring workflow
Implement flexible or large-scale role-based license redistribution using custom logic	LicenseRedistributionService class	Large-scale redistribution (over 1 000 users) Complex custom validation or conditional logic Integration with external systems Maximum flexibility

Automate role-based license redistribution using custom UI element that calls the corresponding business process

To automate role-based license redistribution and embed it to any Freedom UI page using custom UI element, implement a custom trigger that calls the corresponding business process, for example, a button that runs the business process, to your Freedom UI page by following the instructions below:

• To configure this via Freedom UI Designer, see Set up a button that runs business processes in a section (user documentation).
• To configure this via the source code of a Freedom UI page, see Run a business process.

Learn more about business processes that redistribute licenses based on user roles: Workflow of role-based license redistribution.

Now you can redistribute licenses based on user roles. Before triggering role-based license redistribution, ensure that the preliminary setup is completed. Instructions: Manage user licenses (user documentation).

Automate role-based license redistribution using User task process element

Creatio provides the following User task process element for role-based license redistribution:

• "Redistribute licenses" user task that redistributes licenses for all active users or a specific user role. The user task is implemented in the "Redistribute licenses" (RedistributeLicensesUserTask code) schema of the "User task" type.
• "Redistribute licenses for specific user" user task that redistributes licenses for a single user. The user task is implemented in the "Redistribute licenses for specific user" (RedistributeLicensesForSpecificUserUserTask code) schema of the "User task" type.

To automate role-based license redistribution using User task element added to a business process:

1. Add the User task element to the business process schema. We recommend adding the element to the user creation process, immediately after the users are added or list of user roles is changed.

2. Select the way to redistribute licenses based on user roles.

   Redistribute licenses for all active users or a specific user role

   Choose this way when you need to:

   • redistribute licenses for multiple newly created or imported users
   • recalculate licenses when roles are reorganized or updated

   To redistribute licenses for all active users or a specific user role:

   1. Select "Redistribute licenses" in the Which user task to perform? parameter on the setup area.
   2. Fill out the Redistribute licenses for specific role parameter to redistribute licenses for a specific user role. If the parameter is empty, licenses are redistributed for all active users.
   3. Fill out the Redistribute manually assigned licenses parameter to redistribute manually assigned licenses. If the parameter is set to "true," manually assigned licenses are revoked before assigning new licenses according to user roles.
   4. Fill out the Role identifier parameter to redistribute licenses for a specific user role.
   Redistribute licenses for a single user

   Choose this way when you need to:

   • assign licenses when a new user is created
   • update licenses when a user is added to or removed from a role
   • redistribute licenses when a user is reactivated
   • limit the redistribution to a single user without affecting others
   • ensure that the user receives correct licenses based on current roles

   To redistribute licenses for a single user:

   1. Select "Redistribute licenses for specific user" in the Which user task to perform? parameter on the setup area to redistribute licenses for a single user.
   2. Fill out the User identifier parameter to redistribute licenses for a single user.

Now you can redistribute licenses based on user roles. Before triggering role-based license redistribution, ensure that the preliminary setup is completed. Instructions: Manage user licenses (user documentation).

Automate role-based license redistribution using LicenseRedistributionService class

Use the LicenseRedistributionService class to automate role-based license redistribution programmatically in advanced automation or integration scenarios. The class encapsulates the core logic of role-based license redistribution and provides the following methods:

• RedistributeLicences(bool redistributeManuallyAssignedLicences) that redistributes licenses for all active users.
• RedistributeLicencesForRole(bool redistributeManuallyAssignedLicences, Guid roleId) that redistributes licenses for users of a specific role.
• RedistributeLicencesForUser(Guid userId, bool redistributeManuallyAssignedLicences, bool hasManuallyAssignedLicense) that redistributes licenses for a single user.

Learn more about methods of the LicenseRedistributionService class: LicenseRedistributionService class.

View the examples that automate role-based license redistribution using the LicenseRedistributionService class in different scenarios below.

Create a user and redistribute their licenses

/* Create contact. */
var contact = CreateContact(employeeData);

/* Create a user for the contact. */
var userId = CreateUser(contact.Id);

/* Add the user to required user roles. */
AddUserToRoles(userId, employeeRoles);

/* Redistribute licenses for the user based on their granted roles. */
var service = ClassFactory.Get<ILicenseRedistributionService>();
service.RedistributeLicencesForUser(userId);

Redistribute licenses for multiple users

/* Create and add multiple users. */
foreach (var employeeData in data) {
    var userId = CreateUser(employeeData);
    userIds.Add(userId);
}

/* Recalculate and redistribute licenses for all active users. A single call is 
more efficient than redistributing licenses for each user individually. */
var service = ClassFactory.Get<ILicenseRedistributionService>();
service.RedistributeLicences(redistributeManuallyAssignedLicences: false);

Redistribute licenses for a user role with error handling

try {
    /* Specify the role for which licenses must be redistributed. */
    var roleId = Guid.Parse("12345678-1234-1234-1234-123456789012");

    /* Get the license redistribution service instance. */
    var service = ClassFactory.Get<ILicenseRedistributionService>();

    /* Redistribute licenses only for users of the specified role.
    Manually granted licenses remain unchanged. */
    service.RedistributeLicencesForRole(false, roleId);

    /* Log a successful operation. */
    _logger.Info($"Licenses redistributed for role {roleId}");
}
catch (Exception ex) {
    /* Log detailed error information and rethrow the exception. */
    _logger.Error($"Error during license redistribution: {ex.Message}", ex);
    throw;
}

Redistribute licenses based on business rule condition

public void ProcessEmployeeOnboarding(Guid userId, Guid departmentId) {
    /* Check the business rule condition.
    Continue only if the user is a manager in the head department. */
    if (!IsManagerInHeadDepartment(userId, departmentId)) {
        return;
    }

    /* Retrieve the list of roles required for managers in the head department. */
    var roles = GetHeadDepartmentManagerRoles();

    /* Assign the user to all required roles. */
    foreach (var roleId in roles) {
        AssignUserToRole(userId, roleId);
    }

    /* Redistribute licenses for the user based on the newly assigned roles. */
    var service = ClassFactory.Get<ILicenseRedistributionService>();
    service.RedistributeLicencesForUser(userId);
}

Now you can redistribute licenses based on user roles. Before triggering role-based license redistribution, ensure that the preliminary setup is completed. Instructions: Manage user licenses (user documentation).

Recommendations for automating role-based license redistribution

These recommendations apply to all ways of role-based license redistribution.

Recommendations for minimizing the impact of role-based license redistribution

• Run large-scale redistributions during non-business hours.
• For large user groups, split the task into batches of 500–1000 users to shorten lock times and reduce resource consumption.
• When possible, perform redistribution at the role level rather than for all users to reduce processing time and minimize the duration of transactional locks.
• Batch processing is especially effective when using the LicenseRedistributionService class.

Recommendations for redistributing licenses at scale

When redistributing licenses for large user groups (more than 1 000 users), Creatio applies the following behavior:

• Operation duration depends on database size, user count, and server workload.
• The environment might temporarily consume additional resources while recalculating licenses.
• Creatio applies short-term database-level transactional locks to license-related tables, primarily allocation tables. This is standard behavior for relational databases.
• End users remain able to work with Creatio. They can continue navigating the UI, viewing data, and performing operations.
• Manual license updates initiated during redistribution might be processed more slowly because they wait until the current transaction to the license data is completed.
• Any waiting is typically brief and depends on the volume of processed data.

In most cases, users do not notice the redistribution unless they attempt to update licenses at the same time manually.

---

See also

Creatio licenses overview (user documentation)

Manage user licenses (user documentation)

LicenseRedistributionService class

Workflow of role-based license redistribution