User Groups

Introduction

In addition to the classification of users into domains, Quobis WAC allows the creation of group of users that have something in common or share some characteristics. This is a quite common practice for example in business environments, where users are classified into departments or teams, but it also applies to a lot of other use cases where we need to combine users into different sets. Quobis WAC provides a number of functionalities to ease the management of these groups and to automatically include group calling and group chatting features.

In Quobis WAC, an “user group” is a set of system users (also referred to as “users group participants”) that has the following characteristics:

  • It is given a name (a string)

  • It has an associated chat group

  • It is a “callable” entity

  • It has one or more associated phonebooks

The associated chat group, which has the same name as its associated user group, is automatically synchronized with the group participants. That means that if the owner adds/changes/removes an user from the userGroup, the system will automatically add/change/remove that user from the ChatGroup. On the other hand, when a user is added to a user group by someone else, the system will include that chat group in the list of groups that this user belongs to.

Calling to an user group

The fact that groups are “callable” means that a audio or video call be placed to them. A user group can also be a destination of a call transfer (attended or direct). In order to do that, the ID that needs to be called when making the call is the user group ID.

Please note that this behaviour means that the callee does not make a call to each group participant, it’s the signaling server which makes that on its behalf. That also means that the caller does not know the actual users that he/she is calling when dialing into the user group. This call is registered in the call details records as a regular call, being the callee the user group ID.

This behaviour is also referred by some PBX vendors as a “ringing group”, which in our case is just a feature of the user groups.

Calling strategies for ringing groups

The user groups can be configured so the incoming calls are routed to the participants by following different calling strategies. It is important to clarify that the participants of an user group follow an order, according to its position in the database (as stored in JSON format in the “participants” field in the /usersGroup/{groupId} endpoint). This order is taken into account when calling to an user group in some calling strategies, as will be explained below.

_images/ug_strategies.png

Simultaneous

When this strategy is selected for a user group, incoming calls to this user groups will be routed automatically to every user group participants. That means that the call will ring for every participant at the same time. The first participant who takes call will be connected to the caller and the call will stop ringig for the rest of participants.

Simultaneous reduced

When this ringing strategy is selected, only the first “maxSteps” participants will be called, all of them at the same time. The rest of the participants won’t receive incoming calls at all. This is useful when a user group is large and we don’t want to call every participant.

Sequential

When this ringing strategy is selected, the system will start calling the participants of the user group, one after another, following the order in the group unntil the participant “maxSteps” is reached. In addition, the delay between calling a participant and calling the next one can be configured (parameter “stepDelay”). This behaviour is set according to these two parameters of the QSS:

"ringingGroup": {
            "stepDelay": 0,
            "maxSteps": 5
     },

This is the effect of these two parameters:

  • Parameter stepDelay: defines the number of seconds to wait before calling the next participant in the list. Defaults to 0 seconds, maximum value 60 seconds.

  • Parameter maxSteps: defines the maximum number of participants that will be called. For example, if we have a usergroup with 10 participants and the value of maxSteps is 5, then only the fist 5 participants will be called. This parameter is only taken into account when te value of stepDelays is different from zero. Its default value is five participants.

This functionality has been implemented as follows:

  • If “stepDelay” is set to zero, the calling strategy is like a simultaneous ringing.

  • If a user answers the call, it will be connected to the caller party. The remaining calls will stop ringing inmediately.

  • If an user rejects the call, that action won’t be notified to the caller party and the call will keep ringing for the rest of participants.

  • If no one accepts the call (not answering or rejecting) the caller will receive a “No answer” message or “Busy” messages (depending on the answer of the last called participant)

_images/usergroups_ringing.png

Known issues

Other characteristics of the user groups are:

  • User groups have a owner, which is a participant who can add, change or remove users from the usersGroup that he/she has created.

  • A user group can only have one owner and it cannot be changed after it’s created.

  • A participant can be owner of one of more user groups.

  • A participant can belong to one of more user groups.

  • There is no limit in the number of users in a UserGroup

  • The associated chat group is not a standard one so no actions can be done via the REST API with these chats. The system will remove it automatically only after the user group is removed. Attempting to interact with these type of chat groups via the REST API will thrown an error.

  • In the event that a user is transferring or calling to a group to which he/she belongs to, he/she won’t be included in the callee list. For example, if Alice belongs to a user group with Bob, Carol and David, and Alice calls into that user group, only Bob, Carol and David will get an incoming call.

  • An incoming call to a user group will end when the global call timeout is reached (as set in the configuration variable “watchdog.invites.expiration” of the QSS.watchdog-invites service) even if the “maxSteps” number of participants has not been reached.

  • Multi-device environments: please note that, in case that a user has active sessions in several devices, each device will be considered as a participant. That means that, in the case of sequential ringing, the call will ring first on one device, then on his second device, etc… instead of jumping to the next participant. This behaviour may be fixed in future versions”.

Configuration

The service needs to be enabled in the wac.ini file in order to work, with the following configuration (it is activated by default after a standard deployment). There is no specific configuration rather than activating the service as shown below.

[usersgroup]
backend[] = UsersGroup

[backend.UsersGroup]
module = UsersGroup

This service can be reached via the Quobis WAC REST APIs where a number of methods are available to create a group, get a list of groups and other CRUD operations.

Log messages

These are the log messages associated with the user groups management:

  • error: Specified participant does not exist: an error occurred when trying to add a participant that doesn’t exist yet

  • error: User ${user.id} is not the owner of the group: an error occurred when a user tries to manage a group in which he is not the owner.