Transition to the New Groups Management

Learn more about the new management of groups

Last Updated

October 19th, 2020

Docebo Module

Learn

Reading Time

7 min

User Level

Introduction

As of October 27, 2020, the groups’ management area of your platform will be enhanced in order to offer a completely revamped way to manage groups of users.

The user interface of the area has been redesigned in line with the new platform layout, and a handful of important changes between the current and the new management of groups have been made.

This article lists the changes introduced by this feature enhancement, lists the APIs that have been deprecated and developed for the new management of groups, and describes how to migrate to the new groups’ management.

Manual Users Management in Auto-populated Groups

At present, after setting the conditions for the creation of auto-populated groups, the platform automatically populates them (and keeps them populated) according to those conditions, but you can still manually manage those groups by adding or removing users.

When users are manually added or removed from an auto-populated group, the platform cannot detect whether users are part of the group because they are satisfying the conditions set for the group or if they have been manually added to it, and the group is no longer auto-populated. This situation generates inconsistency.

With the new groups’ management, it will no longer be possible to manually add or remove users from automatic groups. The population of automatic groups will rely fully on the conditions set for every single group and will keep the groups’ population aligned in real-time, avoiding inconsistencies.

Conditions Recalculation for All Users

When working with the current management of auto-populated groups, if the Superadmin changes a condition on which the group population relies, he/she can decide not to apply the new condition to the users already in the group (by not enabling the Apply to existing users that satisfy the conditions above option).

Again, this scenario generates inconsistency between the users in the group and the conditions set for the population of the group.

With the new groups’ management,  every time a condition is changed, the platform repopulates the group from scratch. The recalculation will then assign users to the group only if they really match the new set of conditions, granting consistency.

New Conditions, Managed in Sets

Currently, the conditions for auto-populated groups are based on users’ additional fields only. When setting more than one condition, you can define whether all or at least one of the conditions must be met in order for users to be added to the group.

The new groups’ management introduces two new conditions for the automatic population of groups: the enrollment status and the branch of belonging. You will be able to set up to 10 conditions and group them in sets, for a maximum of 10 sets. All of the conditions included in a set must be satisfied, while the logic among sets can be defined so that all or at least one of them must be satisfied to add users to the group.

Conditions Based on the Users Role

For those integrating with the Perform module, the current management of auto-populated groups allows the definition of conditions based on the user role.

Since the Perform module is no longer available, this condition has not been ported in the new groups’ management.

Deprecated APIs

The Deprecated APIs table lists all of the APIs that are being deprecated with the new management of groups. Please note that these APIs will be operational for six months after the feature is released, up to the end of April 2021, to provide you with enough time to migrate to the new APIs. After this period, Docebo will keep granting maintenance on the old APIs, but they will no longer be aligned with future developments and improvements.

API DescriptionAPI VerbAPI URL
Create a groupPOST/manage/v1/group
Delete a groupDELETE/manage/v1/group/{id}
Update a groupPUT/manage/v1/group/{id}
Delete a group memberDELETE/manage/v1/group/{id_group}/members/{id_user}
Add a group memberPOST/manage/v1/group/{id_group}/members
Batch delete members from groupsDELETE/manage/v1/group/members/batch
Batch import members into groupsPOST/manage/v1/group/members/batch
Batch import groupsPOST/manage/v1/group/batch

New APIs

The New APIs table lists the APIs available for the new management of groups. These APIs will be fully operational starting on October 27, 2020.

API DescriptionAPI VerbAPI URL
Get all groupsGET/audiences/v1/audience
Create a new groupPOST/audiences/v1/audiences
Delete a group based on its IDDELETE/audiences/v1/audience/{uuid}
Get a specific groupGET/audiences/v1/audience/{uuid}
Update a groupPUT/audiences/v1/audience/{uuid}
Get users from a groupGET/audiences/v1/audience/{uuid}/users
Remove users from a groupDELETE/audiences/v1/audience/{uuid}/users
Add users to a specific groupPOST/audiences/v1/audience/{uuid}/users
Export CSV containing all users in a groupGET/audiences/v1/audience/{uuid}/export-users
Retrieve the history of automatic groupsGET/audiences/v1/audience/{uuid}/conditions-history
Get an old group ID from a new group IDGET/audiences/v1/audience/{uuid}/audience_to_group
Get a new group ID from an old group IDGET/audiences/v1/audience/{id}/group_to_audience

For each new API, the list of parameters is detailed in the following sections.

Get all groups

GET /audiences/v1/audience
@parameter sort_attr [string, optional] : Order the groups based on the property. Possible values: “name”, “description”, “slug”
@parameter sort_dir [string, optional] : Sort direction. Possible values: “asc”, “desc”
@parameter page [number, optional]  : Page to return. Default: 1
@parameter page_size  [number, optional] : Items to return.
@parameter search_text [string, optional] : Search groups by a key on name and description

Get a specific group

GET /audiences/v1/audience/{uuid}
@get uuid [string, required] : The id of the resource to be retrieved

Create a group

POST  /audiences/v1/audiences
@parameter name [string, required] : The name of the group
@parameter description [string, optional] : The description of the group
@parameter type [string, required] : The type of the group. Possible values: “manual”, ”automatic”
@parameter ruleset [object, optional] : The ruleset definition (required for automatic groups)
@item operator [string, required] : The operator for the ruleset. Possible values: “AND”, ”OR”
@item sets [array, required] : The sets of rules
@item rules [array, required] : The rules of the set
@item type [string, required] : The type of rule
@item payload [object, required] : The payload of the rule
@end
@end
@end

Update a group

PUT /audiences/v1/audience/{uuid}
@parameter name [string, optional] : The name of the group
@parameter description [string, optional] : The description of the group
@parameter ruleset [object, optional] : The ruleset definition (required for automatic groups)
@item operator [string, required] : The operator for the ruleset. Possible values: “AND”, ”OR”
@item sets [array, required] : The sets of rules
@item id [string, optional] : The identifier of the set
@item rules [array, required] : The rules of the set
@item id [string, optional] : The identifier of the rule
@item type [string, required] : The type of rule
@item payload [object, required] : The payload of the rule
@end
@end
@end

Delete users from a specific group

DELETE  /audiences/v1/audience/{uuid}/users
@parameter user_ids [array(integer), required] Users to remove from the group
@parameter user_all [bool, optional] Remove all users from the group
@parameter user_filters [array(string), optional] Remove the users that meets the passed criteria ( “search” => “test” ) from the group

Delete a group

DELETE  /audiences/v1/audience/{uuid}
@get uuid [string, required] : The id of the resource to be deleted

Get users from a group

GET /audiences/v1/audience/{uuid}/users
@get uuid [string, required] : The id of the group resource
@parameter sort_attr [string, optional] : Sort by this field. Possible values: “idst”, “userid”, “firstname”, “lastname”, “email”. Default value: “idst”
@parameter page [number, optional]  : Page to return. Default: 1
@parameter page_size  [number, optional] : Items to return.
@parameter search_text [string, optional] : Search users on first name, last name, email and username

Add user to a specific group

PUT /audiences/v1/audience/{uuid}/users
@parameter user_ids [array(integer), optional] : The users to add to the group (At least one of groups, branches or users must be defined)
@parameter branch_ids [array(integer), optional] : The branches to add to the group (At least one of groups, branches or users must be defined)
@parameter group_ids [array(integer), optional] : Copy current users in another group to this group (At least one of groups, branches or users must be defined)

Export users belonging to a specific group

GET /audiences/v1/audience/{uuid}/export-users
@parameter userid [boolean, optional] : If user ID must be included in export – Default: false
@parameter firstname [boolean, optional] : If user first name must be included in export – Default: false
@parameter lastname [boolean, optional] : If user last name must be included in export – Default: false
@parameter email [boolean, optional] : If user email must be included in export – Default: false
@parameter include_header [boolean, optional] : Include or NOT naming of columns in csv file – Default: false
@parameter delimiter [string, optional] : Delimiter for exported csv file – Default: “,”

Get conditions history of a specific group

GET /audiences/v1/audience/{uuid}/conditions-history
@get uuid [string, required] : The id of the resource to be retrieved

Get a group id from an audience id

GET /audiences/v1/audience/{uuid}/audience_to_group
@get id [string, required] The ID of the new group resource from which retrieve the old group ID

Get an audience id from group id

GET /audiences/v1/audience/{id}/group_to_audience
@get id [integer, required] The ID of the old group resource from which retrieve the new group ID

Upgrading to the New Groups’ Management

The upgrade to the new groups’ management is not carried out automatically, but you will have the possibility to migrate at any time, after October 27, 2020, and before November 24, 2020.

In order to upgrade to the new management, click on the Upgrade button in the banner displayed on top of the Groups Management page.

When you upgrade to the new Groups’ Management, both the manual and the automatic groups defined in your platform will be ported to the Groups Management, with their actual population. The population of automatic groups will be recalculated from scratch according to the rules you defined for the group upon saving the group for the first time. Remember that, you will no longer be able to manually add or remove users from automatic groups. The population of automatic groups will rely only on the conditions set for every single group.

The operation may take some time to be processed, and cannot be undone. After upgrading, you will not be able to roll back to the old groups’ management.

On November 24, 2020, the upgrade to the new groups’ management will be carried out on all platforms, and it will not be possible to roll back. Make sure you manually activate the new groups’ management before that date.