Staff-Goals
Set weekly messages-goals and voice-activity-goals for your staff-members.
Features
- Set a message goal for your staff members.
- Optionally, set a voice activity goal to track time spent in voice channels.
- Every week, the bot will check if the staff members met their goals.
- Check your current progress and your past achievements using commands.
- Send results every week via DMs to the users or to a configured channel.
- Optionally, ignore channels from message goals or voice channels from voice goals.
Setup
- Select (or create) a role. The activity of users with this role will get evaluated.
- Configure the module.
- Please set up permissions for slash commands to avoid unauthorized usage.
- Assign the role to members whose activity should get evaluated every week.
Usage
- The requirements get evaluated automatically once a week, on the configured "Weekly Summary Day" and "Weekly Summary Hour".
- You can always check the message progress of you or another user with
/team-goals progressand see their goal-history with/team-goals history. - If the voice goal is enabled, you can check voice activity progress with
/team-goals voice-progress.
Commands
name:<Type> is an option of a slash-command with name name and the type Type. Options that not required, are described as [name:<Type>]. If the action of a command is vastly different between required and not-required options, we might list them separately.Examples
/moderate ban user:<Member>: This command (/moderate ban) has an required option with the name "user" that only accepts one member as a value./moderate ban victim:<Member> reason:<Text>: This command (/moderate ban) has an required option with the name "victim" that only accepts one member as a value and another required option with the name "reason" that accepts any text as an value./moderate ban victim:<Member> reason:<Text> [proof:<Attachment>]: This command (/moderate ban) has an required option with the name "victim" that only accepts one member as a value, another required option with the name "reason" that accepts any text as an value and a not-required option with the name "proof" which allows one attachment as its value.
| Command | Description |
|---|---|
/team-goals progress [user:<User>] | Shows your progress towards the goal of the current evaluation period (if empty, your progress will be shown). With the voice goal disabled, this is a paragraph with the messages left to reach the goal, a progress bar, and the deadline. With the voice goal enabled, this becomes three status lines instead - messages sent/goal, voice minutes sent/goal, and the next summary date - each with its own tick or cross, with the embed title and colour reflecting the overall result according to the configured "Goal Mode". |
/team-goals voice-progress [user:<User>] | Shows the voice activity progress (minutes spent in voice channels, goal, time left) towards the voice goal of the current evaluation period. Only available if the voice goal is enabled. |
/team-goals history [user:<User>] | Shows the goal-history (amount of messages, voice minutes if the voice goal is enabled, goal reached or not according to the configured "Goal Mode", percentage of goals reached) in the last 10 weeks of the specified user (if empty, your progress will be shown). |
Definition of module-specific terms
- An evaluation is the time when a user gets evaluated. This happens once a week, on the configured Weekly Summary Day and Weekly Summary Hour, in your bot's configured timezone. In an evaluation, the bot will compare the amount messages sent in the current evaluation period to the configured goal, triggering the configured failed / archived message to be sent. Once all users got evaluated, the next evaluation period starts.
- An evaluation period is the time between the last and the next evaluation and is exactly one week long.
Configuration
This configuration file allows you to configure how this module will behave and the goal itself. Open it in your dashboard.
The weekly summary now fires on the configured "Weekly Summary Day" and "Weekly Summary Hour", in your bot's configured timezone, instead of the fixed moment the module was first enabled. On the first evaluation after upgrading, existing servers move from their previous, arbitrary slot to the new one - this makes exactly one week shorter or longer, by up to seven days.
With the voice goal enabled, staff members now get one combined weekly message by default instead of separate message-goal and voice-goal messages (see "Combined Goal Achieved Message" and "Combined Goal Failed Message" below). To keep the previous behaviour, turn off "Send one combined message per staff member" - your existing Goal-Archived-Message, Goal-Failed-Message, Voice Goal Achieved Message and Voice Goal Failed Message templates are untouched and take effect again immediately.
| Field | Description |
|---|---|
| Staff-Roles | These roles will get evaluated every week regarding their progress towards the goal. Only messages from users with these roles will get tracked. |
| Weekly Message Goal | The amount of messages staff members need to send in each evaluation period to archive the goal. |
| Goal-Archived-Message | This is the message sent (either via DM or in the configured channel) every evaluation for every user tracked (every user with a configured Staff-Role) if they reach their goals. Supports %voiceMinutes% and %voiceGoal%, populated with 0 if the voice goal is disabled. |
| Goal-Failed-Message | This is the message sent (either via DM or in the configured channel) every evaluation for every user tracked (every user with a configured Staff-Role) if they fail to reach their goals. Supports %voiceMinutes% and %voiceGoal%, populated with 0 if the voice goal is disabled. |
| Send messages in channels instead of DMs | If enabled, staff members will receive their goal evaluation in a channel instead via DMs. |
| Channel to send messages in | Only visible if "Send messages in channels instead of DMs" is enabled. Every evaluation, the goal message will get sent into this channel instead via DMs. |
| Users can see each others statistics | If enabled, users will be able to add the [user:<User>] to their command and will be able to see each others statistics. |
| Ignored channels | Messages sent by users with at least one of the Staff-Roles in these channels won't get counted towards their goals. |
| Message goal overwrites | Optionally overwrite the weekly message goal for specific roles. First field: Role ID. Second field: Custom goal for that role. Users with this role will have this goal instead of the default weekly goal. |
| Enable Voice Goal | If enabled, staff members will also be evaluated on their voice channel activity. Voice minutes are tracked whenever a user with a Staff-Role is connected to a voice channel. |
| Weekly Voice Goal (minutes) | Only visible if "Enable Voice Goal" is enabled. The number of minutes staff members need to spend in voice channels each evaluation period to reach the voice goal. Default: 60. |
| Ignored Voice Channels | Only visible if "Enable Voice Goal" is enabled. Time spent in these voice channels won't be counted towards the voice goal. |
| Voice Goal Achieved Message | Only visible if "Enable Voice Goal" is enabled. The message sent each evaluation to staff members who reached their voice goal. Leave empty to not send a separate voice goal message. Supports %voiceMinutes%, %voiceGoal%, and all message goal parameters. |
| Voice Goal Failed Message | Only visible if "Enable Voice Goal" is enabled. The message sent each evaluation to staff members who did not reach their voice goal. Leave empty to not send a separate voice goal message. Supports %voiceMinutes%, %voiceGoal%, and all message goal parameters. |
| Voice goal overwrites | Only visible if "Enable Voice Goal" is enabled. Optionally overwrite the weekly voice goal for specific roles. First field: Role ID. Second field: Custom voice goal in minutes for that role. |
| Weekly Summary Day | The weekday the weekly summary is sent and the evaluation period resets, in your bot's configured timezone. Default: Monday. |
| Weekly Summary Hour | The full hour the weekly summary is sent, in your bot's configured timezone. Default: 09:00. |
| Send one combined message per staff member | Only visible if "Enable Voice Goal" is enabled. If enabled, the message goal and the voice goal get reported in a single weekly message instead of two separate ones. Enabled by default. |
| Goal Mode | Only visible if "Enable Voice Goal" is enabled. Whether a staff member has to meet both the message goal and the voice goal, or whether meeting either one is enough to pass the evaluation. |
| Combined Goal Achieved Message | Only visible if "Send one combined message per staff member" is enabled. The message sent once a week to staff members who met their weekly goal, when combined messages are enabled. Supports %messageStatus%, %voiceStatus%, and all message- and voice-goal parameters. |
| Combined Goal Failed Message | Only visible if "Send one combined message per staff member" is enabled. The message sent once a week to staff members who did not meet their weekly goal, when combined messages are enabled. Supports %messageStatus%, %voiceStatus%, and all message- and voice-goal parameters. |
Troubleshooting
Messages sent by my staff members are not counted correctly
Please make sure that
- the bot has access to every channel that messages from staff members should be counted in and that the channel is not in the blacklist.
- the user has at least one of the Configured Staff-Roles. Only message sent while they have the rolle will get counted - messages sent before the user had the role are never counted.
How can I change the time when users get evaluated?
Open the module configuration and change "Weekly Summary Day" and/or "Weekly Summary Hour" to the weekday and hour (in your bot's configured timezone) you want evaluations to happen. The change takes effect the next time the module reloads its configuration - no need to disable the module or purge its database.
Keep in mind that the current evaluation period always ends at the next occurrence of the newly configured slot, so changing it while a period is running cuts that period short or stretches it, once - the same way moving the summary day from Monday to Tuesday on a Monday afternoon would. The same happens right after enabling the module: with the defaults (Monday, 09:00), enabling it on a Sunday at 20:00 evaluates every staff member about 13 hours later, showing a goal of 100 messages as failed with 0 sent. Set the day and hour to your desired schedule right after installing, before staff start accumulating counts, to avoid an unexpectedly short first period.
Evaluation isn't working correctly (e.g. evaluation messages aren't send)
Please make sure that
- the bot has the permissions to send message into the configured channel, if enabled.
- your staff members have at least one of the configured staff-roles.
- that the configured messages are not incorrect.
Even if no evaluation messages get sent, you can always view the goal history using the /team-goals history slash command.
Can I use this module to evaluate the message activity of my members? / SCNX is adding a "Report Abuse" button below my DM messages
Such usage would violate our Terms of Service as you are using our software to spam your users. You may only use this module to evaluate activity of your staff members and only with their consent. If you are using the DM feature of this module, SCNX might automatically add a "Report abuse" button below your message if you are messaging an unusually high amount of members of your server. You can learn more about this behavior on scootk.it/report-mass-dm (this is also the URL linked in the button). Most of our users never fit this category, and you usually do not need to worry about this if you are using this module as intended.
Stored data
The following data is being stored about every user with a configured Staff-Role once they send a message ("User Entry"):
- Their unique Discord User-ID
- The amount of messages they sent in the current evaluation period
- The amount of voice minutes in the current evaluation period (if voice goal is enabled)
- Metadata about the entry (date when created and last updated)
The following is stored at every evaluation about every user that has one of the configured Staff-Roles ("Goal History Entry"):
- A unique integer identifying the database entry
- Their unique Discord User-ID
- The amount of messages they sent in the evaluation period
- The configured message goal in the current evaluation period
- The amount of voice minutes in the evaluation period (if voice goal is enabled)
- The configured voice goal in the current evaluation period (if voice goal is enabled)
- Metadata about the entry (date when created and last updated)
There is no way to remove the user entry or the goal history entry from the database. Messages sent by users without any configured Staff-Roles will never be counted and will not create a User entry.
To remove all data, purge the module database.