Promotions

Log staff promotions, apply role changes, announce rank changes, and revoke promotions.

1 - Introduction

Promotions record staff rank grants. CADLY can apply a Discord role, show who issued the promotion, send a DM, and post a log message to your promotion channel.

Promotions are separate from Infractions. Use promotions for positive rank movement and use infractions for warnings, strikes, suspensions, demotions, and terminations.

Promotions create an audit trail for rank movement. Instead of only adding a Discord role, CADLY records the reason, issuer, timestamp, and optional note so leadership can review why a rank was granted later.

Use the system even for small rank changes. Consistent records prevent confusion when staff transfer departments, return from LOA, or dispute rank history.

1.1 - Table of Contents

Section What it covers

Issuing Promotions Slash command and panel behavior

History and Revocation Filtering, details, and revoke behavior

Settings Promotions settings reference

Troubleshooting Common permission and role issues

1.2 - Links to Related Documents

2 - Issuing Promotions

Use /promotion issue with user, role, reason, and optional note. CADLY checks the issuer's promotion permission and Discord role hierarchy before applying role changes.

The panel Promotions page also supports issuing promotions for users visible to the server. Commands and panel actions create the same promotion record.

The role field is the Discord role being granted, so your rank structure should be represented by Discord roles. If your community uses multiple role layers, promote only the role that represents the rank change and leave department, certification, or specialty roles to their own process.

The optional note is best for internal context such as vote result, training class, or command approval. It should not replace the public reason.

type: record
title: Promotion record
meta: Promotions > Rank history
status: Applied
items:
- User | @RiversideUnit
- Role Granted | @Senior Moderator
- Reason | Completed field training
- Note | Approved by command staff

2.1 - Promotion Fields

Field Purpose

User Discord member receiving the promotion.

Role Discord role to add.

Reason Required reason shown in history and messages.

Note Optional internal note.

2.2 - Hierarchy Protection

CADLY refuses promotions when the target has an equal or higher role than the actor. If the bot cannot apply a role because of hierarchy, the Hierarchy Block Policy decides whether to fail or let you confirm a partial action.

3 - History and Revocation

Use /promotion list to list your own promotions or another user's promotions when you have Manage Promotions permission. The panel shows a paginated history and supports filtering by user.

Use /promotion revoke with promotion_id and optional reason to mark a promotion revoked. Depending on settings, CADLY can leave roles untouched, remove the issued role, or restore a previous rank when one is available.

Revocation is an audit action, not a delete. The original promotion stays in history and is marked revoked. This is important when a promotion was made in error or a rank change is reversed after review.

If you want demotions to appear in discipline history, use Infractions with the demotion type. Promotion revoke is mainly for undoing the promotion record itself.

4 - Settings / Configuration

4.1 - Promotions Module

Enable Promotions

Turns the promotions module on or off. Default: on | Requires: none

Promotions Channel

Channel where promotion logs are sent. Default: none | Requires: none

Revoke Behavior

Controls role changes when a promotion is revoked: do nothing, remove the issued rank, or restore the previous rank when available. Default: none | Requires: none

Use none when leadership wants to handle role corrections manually. Use remove issued rank when promotions are simple one-role grants. Use restore previous rank only if your workflow reliably tracks previous rank information.

Hierarchy Block Policy

Controls what happens when some role changes cannot be applied: fail the action or allow confirmation for partial changes. Default: confirm partial | Requires: none

4.2 - Message Templates

Customize Promotion DM

DM sent to the promoted user. Default: CADLY default promotion DM | Requires: none

Customize Promotion Message

Message sent to the promotions channel. Default: CADLY default promotion log | Requires: none

Customize Promotion Revoke DM

DM sent when a promotion is revoked. Default: CADLY default revoke DM | Requires: none

Customize Promotion Revoke Log Message

Log message sent or edited when a promotion is revoked. Default: CADLY default revoke log | Requires: none

5 - Troubleshooting Common Issues

5.1 - Promotion Cannot Apply the Role

Move the CADLY bot role above the target rank role and ensure the issuer outranks the target member.

5.2 - No Promotion Log Appears

Set Promotions Channel and confirm the bot can send messages in that channel.

5.3 - Revoke Did Not Remove a Role

Check Revoke Behavior. The default is no role change.

6 - Getting Support and Resources

If you need help, several resources are available:

Browse all CADLY documentation