Introduction

As of October 27, 2020, the groups’ management area of your platform has been 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.

Conditions Recalculation for All Users

When working with the old 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

In the old groups' management, 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 old 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.

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 February 2, 2021.

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. 

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 February 2, 2021, 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.

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.

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.

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