Evidence Bot Punishment Imports & Appeals
Connect Evidence Bot to LiteBans or AdvancedBan using read-only MySQL access, and configure external appeal webhook intake.
Evidence Bot Punishment Imports & Appeals
The bot can create cases automatically from LiteBans and AdvancedBan punishment records. Each provider has its own connection, so both can be enabled together. Configure your Minecraft plugin to use MySQL/MariaDB and give the bot a database user with SELECT access only. The bot only reads those tables and never modifies punishment data.
Configure a punishment import
LITEBANS_ENABLED=true
LITEBANS_MYSQL_HOST=127.0.0.1
LITEBANS_MYSQL_PORT=3306
LITEBANS_MYSQL_USER=evidence_reader
LITEBANS_MYSQL_PASSWORD=your_password
LITEBANS_MYSQL_DATABASE=minecraft
LITEBANS_MYSQL_SSL=false
LITEBANS_TABLE_PREFIX=litebans_
Reads bans, mutes, kicks, and warnings under the configured prefix, with player names looked up from the history table.
ADVANCEDBAN_ENABLED=true
ADVANCEDBAN_MYSQL_HOST=127.0.0.1
ADVANCEDBAN_MYSQL_PORT=3306
ADVANCEDBAN_MYSQL_USER=evidence_reader
ADVANCEDBAN_MYSQL_PASSWORD=your_password
ADVANCEDBAN_MYSQL_DATABASE=minecraft
ADVANCEDBAN_MYSQL_SSL=false
ADVANCEDBAN_TABLE_PREFIX=
ADVANCEDBAN_HISTORY_TABLE=PunishmentHistory
Reads PunishmentHistory, which retains kicks and previous punishments after they leave the active Punishments table.
Set the provider's MYSQL_SSL=true when the database supports TLS with a trusted certificate. Table names and prefixes are case-sensitive on some MySQL hosts.
How imports behave
- Mapping: temporary and IP bans map to Banned, temporary mutes to Muted, kicks to Kicked, and warnings to Pending Review.
- Case contents: the recorded player, UUID when available, reason, operator, punishment type, start date, and expiry. Discord identities are not available from these tables.
- First connection: the bot sets a cursor per provider and table. With
PUNISHMENT_IMPORT_EXISTING=falseit skips rows already present; withtrueit starts at ID zero. - Polling: after that, it reads up to 100 new rows per stream every
PUNISHMENT_POLL_SECONDSseconds. - Reliability: successful cases and cursors are saved locally, failed rows are retried before advancing past them, and stored import IDs prevent duplicates after a normal restart.
- Scope: imports create cases for new punishment rows only. Later revocations, reason edits, and expirations are not synchronized into case statuses.
The adapters follow the published LiteBans database structure and AdvancedBan SQL definitions. Forks that use different columns need an adapter change; ADVANCEDBAN_HISTORY_TABLE only changes the table name.
Backfilling old punishments
Keep data/punishment-sync.json and data/cases.json together when moving the bot. Changing PUNISHMENT_IMPORT_EXISTING does not reset an existing cursor. To deliberately backfill old rows:
- Stop the bot and back up both files.
- Set
PUNISHMENT_IMPORT_EXISTING=true. - Remove only the desired provider's cursor entries from
punishment-sync.json. - Start the bot. Stored import IDs skip cases that were already imported.
Reusing or resetting punishment table IDs is outside the cursor model.
Website appeal intake
This is for appeals submitted by an external website that posts a webhook embed into your appeal channel. The bot only listens for a matching embed, so nothing arrives here unless you have a site posting one. The Player Appeals addon does not use this webhook route. It is its own website that submits through the bot's built-in appeal service, so you don't need APPEAL_CHANNEL_ID or APPEAL_WEBHOOK_IDS for it. See Player Appeals addon below.
Set APPEAL_CHANNEL_ID and allow the submitting website's exact webhook ID in APPEAL_WEBHOOK_IDS. Staff-authored embeds are also accepted; arbitrary member messages and other bot or webhook authors are ignored. Intake processes new messages one at a time and skips tickets already in the store. It does not scan history or react to edits.
The first embed must have the title ⛔ Ban Appeal and the author name ZCraft Network.
| Field name | Required? | Notes |
|---|---|---|
Minecraft | Yes | Player's Minecraft username. Max 32 characters. |
Discord | Yes | Discord identity, preferably a mention or user ID. |
Ticket ID | Yes | Must be unique. Max 100 characters. |
Type | Yes | Punishment or appeal type. |
Punishment Reason | Yes | Original reason for the punishment. |
Appeal Reason | Yes | Appellant's explanation. |
Email | No | Contact email shown in the appeal post. |
Punishment Date | No | Date of the punishment. |
Evidence | No | Supporting links or notes. |
Original Case | No | An original bot case ID, optionally wrapped in backticks. |
Field values must be at most 1,000 characters. A valid Original Case ID links the appeal automatically; otherwise staff can use /linkappeal. Case IDs and ticket IDs are distinct.
A matching message creates an [APPEAL] forum post, applies the Appeal tag if found, assigns a new ZC-... case ID, and stores the ticket link.
Optional website addons
The Staff Dashboard and Player Appeals websites are separate purchases. See Optional Website Addons for installation, configuration, security and domain guidance.