The user is the most important entity of any web application. In most applications, it makes sense to group users based on their attributes. This page explains the most common use cases and how to realize to group users in ROQ Suite.
Restaurant use case as an example
To illustrate this concept, we’ll use the example shown below. This could be a part of the data model of a web application that manages restaurants.
There are three use cases:
A user belongs to a restaurant
A user can belong to one or many countries
A user is either a “chef” or a “waiter”. We can call this the type of the user.
Types of user groups
Basically there are two types of user groups:
A user belongs to “something”.
A user is a “something”
Tutorial: how to model user groups in your database
The belongs-to type is basically a regular relation. To be able to add users to a restaurant you need to create the
restaurant entity and to add the foreign-key to the
user like this:
In the examples above, a user can only related to a single user group. In our case, this would be the restaurant where they work. However, there may be cases where you need users to belong to multiple groups and a many-to-many relation works better. So, let’s add a
The is-a type can be modeled in a similar way, but there is an important difference: for each user who is a chef” there must be one record in the
chef table (even though there is not one entry in the
restaurant table per user). As this is a one-to-one relation, the foreign keys can be placed in the user or in the chef/waiter entity. We recommend adding them to the user, mainly because it's easier to detect the type of a specific user.
You may wonder why this is not just an ENUM directly on the user entity like this:
The reason we avoid this is because you probably want to add other relations that are exclusive to one of the user types. For instance, you may want to assign “tables” to waiters (but not to chefs) or you may want to set a buying limit for chefs (but not to waiters).
The full schema
This is how you can model your full schema. Of course, there will be many more entities in your domain model, but we want to focus on the entities here that represent user groups.
Synchronization to ROQ Platform
User groups are very important on the project-side of your web applications, but they are also relevant for multiple ROQ Platform functionalities like https://docs.roq.tech/dev/access-management . For this reason, user groups should be synced from the project side to ROQ Platform.
This sync can be conducted via the event system or via API requests. Our kickstarter application ROQ One uses entity events for this purpose. Entity events are triggered automatically when any entity is either created or updated. You can read more about this here: https://roqtech.atlassian.net/wiki/spaces/PUB/pages/563019875
Configuration of user groups in the console
⚠ This configuration requires technical knowledge about your own data model.
ROQ Platform doesn’t know your data model, which means it doesn’t know if an entity represents a user group or something else. For instance, in the schema below - without your knowledge - it’s impossible for the system to understand that a restaurant represents a user group while a country doesn't.
For this reason, each user group on ROQ Platform needs to be configured in a way that it knows which entities need to be synchronized and related to the users. You can do this in the console here: ➚console.roq.tech/settings/access-and-user-management/group-sync.
In the console you need to set these parameters:
The name of the entity, e.g. with our example schema its either “restaurant”, “chef”, “waiter” or “country”.
The type of the user group relation which is either “belongs-to” or “is-a”.
Users can be in multiple groups of the same User Group Type?
Here you can set if it’s a one-to-many or many-to-many relation between the user entity and the entity that represents the user-group.
If type is set to “Belongs to”
User group name field
The field which sets the name of a user group. In our example this is the name of a specific restaurant.
The name of the field needs to be set to “name”. You need to get this information from your own data model.
User group type
This field sets the type of the user group. So a restaurant is of type "Restaurant". A chain is of type "Chain".
If type is set to “Is-A”
The name of the user group.
User group type
This field sets the type of the user group. The entities chef and waiter are of type "UserType" because they define what kind of user someone is.
Configuration of the relation between the user-group and the user
User Relation Entity
Optional field which is used to define which entity holds the relation to the user. It’s set to null in case a user group is not directly attached to a user (e.g. chain in our example). In the case of restaurant this field would be set to "user" because the user entity holds the foreign-key
User Relation Field
Here you need to add the name of the field that holds the foreign-key. In case of restaurant you need to set the restaurantId field name.
Group Relation Field
This field is only needed in case of many-to-many relations between users and a group. Here you need to set the name of foreign-key that related to the user group in the pivot table.