Logbook - BloxCord V3

The logbook is BloxCord’s moderation and administration record for each user. These methods let your game read and write it in real time.

Locked & classified visibility

Two fields control who can see a logbook entry:

locked — an array of role ids allowed to unlock the entry.
classified — an array of role ids allowed to view a classified entry.

An empty array ({}) means no restriction. You provide these role ids when creating an entry, and getLogbookEntries returns them back as arrays.

Legacy entries created before role-scoped visibility stored a plain boolean. When such an entry is read, its locked / classified value is returned as the single-element array { "legacy_role" } instead of a boolean.

Lock and Classify are Enterprise items and should not be used in the lower tiers.

Entry types

The type you pass to createLogbookEntry determines the entry’s behaviour. Built-in types:

Type	Description	Supports expiry	Changes rank
`comment`	A note on the user’s record.	—	—
`shrnote`	A senior-leadership note.	—	—
`verbalwarning`	An informal verbal warning.	—	—
`warning`	A formal staff warning / strike.	✓	—
`mute`	Chat mute.	✓	—
`toolban`	Blocks the user from using tools.	✓	—
`tban`	Game ban.	✓	—
`serverban`	Ban from a specific server.	✓	—
`kick`	Kick from the user’s current server.	—	—
`modcallban`	Blocks the user from creating modcalls.	✓	—
`rlock`	Rank lock — prevents the user from being ranked.	✓	—
`suspension`	Suspends the user (moves them to the suspended rank).	✓	✓
`demotion`	Demotes the user one rank.	—	✓
`promotion`	Promotes the user.	—	✓

Your organization may also define custom log types in the dashboard. Pass their configured id as type. Rank-related and duration behaviour follows the custom type’s configuration.

createLogbookEntry

Creates a new logbook entry (warning, ban, mute, rank lock, etc.) for a user.

local result = BloxCord:Invoke("createLogbookEntry", actor, target, opts)

Parameters

Player | table | number

required

Who is issuing the entry. See the actor object.

Player | number | string

required

The user receiving the entry. Accepts a Player instance or a raw UserId.

table

required

Entry options.

Show opts fields

string

required

The entry type — one of the built-in types (e.g. "warning", "tban", "mute", "rlock") or a custom type id.

string

Human-readable reason for the entry. Optional for every type except comment and shrnote.

number

Unix timestamp (milliseconds) at which the entry expires. Omit (or use a past value) for a permanent entry. Only meaningful for duration-based types.

boolean

default:"false"

Machine ban — extends a tban to all of the user’s accounts. Only valid on a permanent tban, and requires the Machine Bans module.

string[]

Array of role ids permitted to view/unlock the entry. Omit or pass an empty array for no restriction.

string[]

Array of role ids permitted to view the entry when classified. Omit or pass an empty array for no restriction.

string[]

Optional array of rule ids to associate with the entry.

Returns

table | nil

The created entry on success, or nil if the request was rejected or the backend was unreachable.

Show result fields

boolean

true when the entry was created.

string

The new entry’s id (use it with revertLogbookEntry).

string

The stored entry type.

number | null

The user’s new rank, for rank-changing types.

string | null

The user’s new role name, for rank-changing types.

string

On failure, a human-readable reason.

Examples

local BloxCord = game:WaitForChild("BloxCord")

BloxCord:Invoke("createLogbookEntry", moderator, offender, {
    type = "mute",
    reason = "Spamming in chat",
    expiry = os.time() * 1000 + (7 * 24 * 60 * 60 * 1000), -- 7 days from now
})

local BloxCord = game:WaitForChild("BloxCord")

local result = BloxCord:Invoke("createLogbookEntry", moderator, offender, {
    type = "tban",
    reason = "Exploiting",
    mban = true, -- machine ban: applies across the user's accounts (permanent only)
})

if result and result.success then
    print("Banned, entry id:", result.id)
end

local BloxCord = game:WaitForChild("BloxCord")

BloxCord:Invoke("createLogbookEntry", moderator, offender, {
    type = "warning",
    reason = "Insubordination",
    locked = { "role_seniorstaff", "role_hr" }, -- only these roles can view/unlock
})

revertLogbookEntry

Reverts a logbook entry by id, undoing its effects: rank-changing entries (suspensions, demotions, promotions, and custom rank actions) rank the user back, machine bans are lifted, and comment / verbal warning / SHR note entries are deleted outright. Every other type is marked reverted and kept on record.

local result = BloxCord:Invoke("revertLogbookEntry", actor, target, opts)

Batchable as the logbook.revert op with args { userId, id, reason } — see apiBatch.

Parameters

Player | table | number

required

Who is reverting the entry. See the actor object. For rank-reverting entries the actor must outrank the rank being restored.

Player | number | string

required

The user the entry belongs to. Accepts a Player instance or a raw UserId.

table

required

Revert options.

Show opts fields

string

required

The id of the logbook entry to revert (the id returned by createLogbookEntry or getLogbookEntries).

string

Optional reason recorded with the revert.

Returns

table | nil

The revert result, or nil if the request was rejected (entry not found, already reverted, locked, insufficient rank, etc.) or the backend was unreachable.

Show result fields

boolean

true when the entry was reverted.

string

The reverted entry’s id.

string

The entry type that was reverted.

string

On failure, a human-readable reason.

Example

local BloxCord = game:WaitForChild("BloxCord")

local entries = BloxCord:Invoke("getLogbookEntries", offender.UserId, {
    type = "tban",
    active = true,
})

if #entries > 0 then
    BloxCord:Invoke("revertLogbookEntry", moderator, offender, {
        id = entries[1].id,
        reason = "Appeal accepted",
    })
end

getLogbookEntries

Fetches a user’s logbook entries, optionally filtered by type and active state.

local entries = BloxCord:Invoke("getLogbookEntries", userId, filters)

Batchable as the logbook.getEntries op with args { userId, type, active } — see apiBatch. The op result is { entries = {...} }.

Parameters

number | string

required

The UserId whose entries to fetch.

table

Optional filters.

Show filters fields

string

Only return entries of this type (e.g. "tban", "rlock").

boolean

When true, only return entries that are not reverted and not expired.

Returns

object[]

An array of logbook entries. Empty if none match or the request failed.

Show entry fields

string

Unique entry id.

string

Entry type.

string

Reason text.

number

Target’s rank at time of entry.

string

Target’s role at time of entry.

number

New rank (for rank changes).

string

New role (for rank changes).

number

Duration, if applicable.

number

Creation timestamp (ms).

number | null

Expiry timestamp (ms), or null if permanent.

boolean

Whether the entry was reverted.

string[]

Array of role ids allowed to view/unlock the entry. Empty if unrestricted. Legacy entries return { "legacy_role" }.

string[]

Array of role ids allowed to view the classified entry. Empty if unrestricted. Legacy entries return { "legacy_role" }.

object

The actor who created the entry.

Show moderator fields

string

The moderator’s UserId.

string | null

Their username.

number | null

Their group rank at the time.

string | null

Their role name at the time.

Example

local BloxCord = game:WaitForChild("BloxCord")

local activeBans = BloxCord:Invoke("getLogbookEntries", player.UserId, {
    type = "tban",
    active = true,
})

if #activeBans > 0 then
    local ban = activeBans[1]
    if #ban.locked > 0 then
        print("Entry is locked to roles:", table.concat(ban.locked, ", "))
    end
    player:Kick("You are banned: " .. ban.reason)
end

checkranklock

Convenience check for whether a user currently has an active rank lock (rlock) entry. Equivalent to calling getLogbookEntries with type = "rlock" and active = true and testing for results.

local locked = BloxCord:Invoke("checkranklock", userId)

Batchable as the logbook.checkRankLock op with args { userId } — see apiBatch. The op result is { locked = boolean }.

Parameters

number | string

required

The UserId to check.

Returns

boolean

true if the user has at least one active rank lock, otherwise false.

Example

local BloxCord = game:WaitForChild("BloxCord")

if BloxCord:Invoke("checkranklock", targetUserId) then
    warn("Cannot rank this user — they are rank-locked.")
    return
end

​Locked & classified visibility

​Entry types

​createLogbookEntry

​Parameters

​Returns

​Examples

​revertLogbookEntry

​Parameters

​Returns

​Example

​getLogbookEntries

​Parameters

​Returns

​Example

​checkranklock

​Parameters

​Returns

​Example

Locked & classified visibility

Entry types

createLogbookEntry

Parameters

Returns

Examples

revertLogbookEntry

Parameters

Returns

Example

getLogbookEntries

Parameters

Returns

Example

checkranklock

Parameters

Returns

Example