Evidence BotImports & Appeals

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.

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=false it skips rows already present; with true it starts at ID zero.
  • Polling: after that, it reads up to 100 new rows per stream every PUNISHMENT_POLL_SECONDS seconds.
  • 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:

  1. Stop the bot and back up both files.
  2. Set PUNISHMENT_IMPORT_EXISTING=true.
  3. Remove only the desired provider's cursor entries from punishment-sync.json.
  4. 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 nameRequired?Notes
MinecraftYesPlayer's Minecraft username. Max 32 characters.
DiscordYesDiscord identity, preferably a mention or user ID.
Ticket IDYesMust be unique. Max 100 characters.
TypeYesPunishment or appeal type.
Punishment ReasonYesOriginal reason for the punishment.
Appeal ReasonYesAppellant's explanation.
EmailNoContact email shown in the appeal post.
Punishment DateNoDate of the punishment.
EvidenceNoSupporting links or notes.
Original CaseNoAn 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.