Skip to main content

Role automation

The Role Automation plugin allows server administrators to dynamically assign and manage Discord roles based on user data from the Forge platform.

General Settings​

Rename with Login​

When enabled, this setting allows the bot to rename users on Discord to match their Forge login, maintaining consistency and identifiable across platforms. Each role mapping configuration provides an option to override this setting.

info

This settings ensure that the user's login is contained in the username, for example the bot will not rename the user if their name is login [PRS], as the login is already included in the username.

Role Mapping​

Role mapping is the core feature of the Role Automation plugin. It enables you to define which Discord roles correspond to which Forge logins or groups. You can create a mapping by clicking the + button and filling out the form.

Role Mapping Configuration​

  • Discord Role to Assign: Select the Discord role that you want to map to a Forge group or login.
  • Forge Group to Map: Select the Forge groups whose members should receive the Discord role.
  • Forge Group Mapping Strategy: Choose the strategy for assigning the role based on group membership:
    • ALL: Users must be in all listed groups to receive the role.
    • ANY: Users must be in one or more of the listed groups to receive the role.
  • Forge Login to Map: Enter specific Forge logins to map to the Discord role.
  • Rename with Login Override: Decide whether to override the user's Discord name with their Forge login when this role is assigned, regardless of the general "Rename with Login" setting.
    • NONE: Do not override the user's Discord name, follows the general "Rename with Login" setting.
    • FORCE_RENAME: Override the user's Discord name with their Forge login, regardless of the general "Rename with Login" setting.
    • FORCE_NO_RENAME: Do not override the user's Discord name, regardless of the general "Rename with Login" setting.

Managing Role Mappings​

You can manage existing role mappings by clicking on the specific category box. To edit, simply modify the settings and click Save to update, or click Delete to remove the mapping.

Role synchronisation​

The Role Automation plugin synchronizes roles based on the following triggers:

  • User Consent: Roles are synchronized when a user consents to the server. This initial synchronization ensures that new members are assigned the correct roles as soon as they join.
  • Daily Schedule: A scheduled synchronization occurs daily at 1 AM UTC. This routine check updates roles for all users, ensuring that any changes in Forge group membership or logins are reflected in Discord roles.
  • Manual Server Trigger: Administrators can use the Force Synchronisation button to manually initiate a role update at any time. This is useful for immediate synchronization after making changes to role mappings or when needing to correct role assignments outside of the daily schedule.
  • Manual User Trigger: Administrators can synchronize a specific user's roles by clicking on their Discord profile, selecting Apps and then Force User Synchronisation.
Consent Revocation

When a user revokes their consent, the Role Automation plugin will remove all roles that have been assigned through its mapping.

Discord Commands for Role Automation​

The Role Automation plugin offers specific Discord commands to manage and view the consent status and synchronization of users.

  • Check Consent Status: To check whether a user has consented to the server's terms and is synced, you can use the command /auth status <user>. This can also be accessed by right-clicking on the user, selecting "Apps", and then choosing "Get User Sync Status".

  • Force User Synchronization: If you need to manually refresh a user's role status, you can right-click on the user, navigate to "Apps", and select "Force User Synchronisation". This action will update the user's roles based on the latest available data from Forge.

Discord Limitations​

Understanding the Bot's Role Hierarchy Constraints​

When configuring your server with the Forge Bot, it's important to be aware of certain Discord limitations that affect how the bot operates in relation to user roles and permissions.

Rename with Login Limitation​

  • Role Hierarchy Impact on Renaming: The Rename with Login feature is subject to Discord's role hierarchy. The bot cannot rename any user who has a role higher than the bot's highest role. This ensures that users with administrative or higher privileged roles maintain control over their display names.

Role Mapping Limitation​

  • Role Assignment Boundaries: Similarly, the bot's ability to assign roles through the Role Mapping feature is limited by its position in the role hierarchy. The bot cannot assign any roles that are ranked above its own highest role. This is a security measure by Discord to prevent lower-ranked members (or bots) from escalating their privileges without proper authorization.
danger

Ensure that the bot is appropriately positioned within your server's role hierarchy to maximize its functionality. The bot should have a higher role than the members it is expected to manage but should not exceed the roles designated for server administrators or moderators to prevent any unintended permission escalations.

Tips​

Restricting Server Access to EPITA Users​

Overview​

To create an exclusive environment for EPITA users on your Discord server, you can use the role mapping features of the Forge Bot to restrict access to new members until they have linked their Forge account to their Discord account.

Implementation Steps​

  1. Initial Discord Setup: Create a default state for new members where they have no roles assigned. In this default state, they should only be able to see two channels:

    • A verification channel with instructions on how to verify their identity (i.e., login via https://discord.forge.epita.fr).
    • A FAQ channel for any assistance they might require during the verification process.

  2. Role Verification: Once a user follows the verification process and logs in through https://discord.forge.epita.fr, the bot can automatically assign them the 'Verified' role by mapping the Forge group users.

  3. Channel Visibility Adjustment: Upon obtaining the 'Verified' role, the initial verification and FAQ channels should be hidden from the user's view. They will gain access to channels and features that are appropriate for their specific roles and permissions.

Note

It is advisable to communicate this process clearly in your server's welcome message or verification channel to ensure a smooth user experience.