Introduction

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:

Type

Description

Example

Belongs-to

A user belongs to “something”.

  • A user belongs to a restaurant

  • A user belongs to one or many countries

Is-a

A user is a “something”

  • A user is a chef

  • A user is a waiter

Tutorial: how to model user groups in your database

User groups need to be considered when the data model is drafted. We recommend that you do this visually using an entity-relationship diagram and a drawing tool like ➚diagrams.net or ➚moqups.

Belongs-to

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 country entity:

Is-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.



Document image

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.



Document image

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:

Entity

The name of the entity, e.g. with our example schema its either “restaurant”, “chef”, “waiter” or “country”.

Relationship type

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”

Name

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.

Example configurations

Configuration

Use case

  • Entity: restaurant

  • Relationship type: belongs-to

  • User Group Type: Restaurant (same as entity because of “belong to” type)

  • User Group Name field: name

  • Users can be in multiple groups = false

  • User Relation Entity = on user

  • User Relation Field = restaurantId

  • Entity: chef

  • Relationship type: is-a

  • User Group Type: UserType (pre-filled static value, editable)

  • Name: Chef (pre-fill with name of entity)

  • Users can be in multiple groups = false

  • User Relation Entity = on user (pre-filled selection)

  • User Relation Field = chefId (pre-filled by convention)

  • Entity: waiter

  • Relationship type: is-a

  • User Group Type: UserType (pre-filled static value)

  • Name: Waiter (pre-fill with name of entity)

  • Users can be in multiple groups = false

  • User Relation Entity = on entity (pre-filled selection)

  • User Relation Field = userId (pre-filled by convention)

  • Entity: country

  • Relationship type: belongs-to

  • User Group Type: Country (pre-filled static value)

  • User Group Name field: name

  • Users can be in multiple groups = true

  • User Relation Entity = There is a pivot (form field is not needed)

  • Pivot Table Name = user-country

  • User Relation Entity = countryId (auto-pre-filled)

  • User Relation Field = userId (auto-pre-filled)