Jobs & Responder Groups

This guide explains how oxide-dispatch resolves jobs to alert recipients, how to add or rename jobs, and how to add a brand-new responder group (e.g. coastguard).

Mental model

Every alert ultimately resolves to a flat list of framework job names ('police', 'lspd', 'ambulance', etc.) — those are the strings the bridge compares against olink.job.Get(src).name to decide who receives the popup, panic, civilian call, or detection alert.

Producers (civilian 911 menu, detection module, panic, your own exports) don't pass job lists directly. They pass either:

• a responder-group key ('police', 'ems', 'fire'), or
• a raw job name ('sheriff'), or
• an array of any combination.

Those inputs are normalized by Config.ResolveJobs(input) (defined in shared/config/jobs.lua). The normalized array is what the broadcast layer fans out. The keystone of the whole system is therefore Config.ResponderGroups — every other config refers back to it.

Config.GetGroupForJob(jobName) is the reverse lookup: it tells the client which group the local player belongs to so the responder entries in the Dispatch radial menu, the status list, and the panic title can be rendered correctly. If a job is not listed in any group's jobs array, the player sees only the civilian 911/311 entries in the Dispatch menu, cannot panic, and cannot receive same-group status toasts.

Case sensitivity

Job-name matching is case-sensitive. Frameworks store the job name verbatim — 'police' and 'LSPD' are different jobs. If your departments use mixed casing (common on QBCore servers with custom departments), list every casing your server actually uses:

jobs = { 'police', 'lspd', 'LSPD', 'bcso', 'BCSO', 'sasp', 'SASP' },

If you're not sure what casing your framework uses, log in on a test character with the job assigned and run /job (QBCore/QBX), or check the job name in your admin panel or database — copy the exact string.

Config.ResolveJobs input contract

If you want missing-jobs producers to default silently to police (legacy behavior), set:

Config.ResolveJobsDefault = 'police'

Where jobs must be configured

All files live in shared/config/. Every one of these is in escrow_ignore, so they are safe to edit on a live server.

A few details that aren't obvious from skimming the files:

• compat.lua .jobs / .emsJobs accept the same ResolveJobs input — pass a group key, raw job, or array. Used by police:server:policeAlert, hospital:server:ambulanceAlert, ESX esx_policejob:alert, etc.
• ai_dispatch.lua .job must be a single framework job string, not an array — one channel = one department. The MDT-flavored AI tools (plate / person / BOLO) only appear on channels whose job is also listed in Config.ResponderGroups.police.jobs.
• statuses.lua _default fallback list is used by any group that doesn't define its own statuses. Custom groups can rely on it instead of duplicating the police/EMS/fire status arrays.

Recipe: add a job to an existing group

Example: your server adds a Park Ranger department whose framework job name is 'parkranger', and you want them treated as police.

Config.ResponderGroups = {
    police = {
        jobs = { 'police', 'lspd', 'bcso', 'sasp', 'sheriff', 'statetrooper',
                 'LSPD', 'BCSO', 'SASP', 'parkranger' },   -- added
        label = 'Officer',
        ...
    },
    ...
}

Config.Compatibility['qb-core'].jobs = { 'police', 'lspd', 'bcso', 'sasp', 'parkranger' }

Config.Compatibility['qb-core'].jobs = 'police'

That's it. The new job will receive police-flavored alerts, panic broadcasts, civilian 911 calls routed to police, and the responder entries in the Dispatch radial menu.

QBX note: all top-level keys in qbx_core/shared/jobs.lua must be lowercase. qbx_core only warns about capitalized keys, it doesn't reject them — but AddPlayerToJob lowercases the name before writing to player_groups, so the stored record never matches an entry like 'ParkRanger' in Config.ResponderGroups. Register ['parkranger'], not ['ParkRanger']. QBCore and ESX tolerate mixed casing.

oxide-police users — important: if you have oxide-police running, the police group's jobs array is overwritten every 60 seconds (and on every player job change) by the live list from oxide-police's police_departments table. Editing Config.ResponderGroups.police.jobs directly will be wiped on the next refresh. See Running alongside oxide-police below.

Recipe: rename a job

The same procedure as adding — replace the old string. Make sure to also update any file that referenced the old name explicitly:

• jobs.lua — Config.ResponderGroups.<group>.jobs
• compat.lua — jobs / emsJobs if you used explicit job names there
• ai_dispatch.lua — Channels[*].job if you have an AI radio channel for that department

Restart oxide-dispatch after the change. Online players keep their old job string in memory until the next olink:server:jobChanged event for them.

Recipe: add a new responder group

Example: you want a Coast Guard responder group with framework job 'coastguard'. Police-style statuses, custom panic title, and the responder entries in the Dispatch radial menu.

Config.ResponderGroups = {
    -- ... existing police / ems / fire ...
    coastguard = {
        jobs  = { 'coastguard' },
        label = 'Coast Guard',
        icon  = 'anchor',                          -- Font Awesome name, no 'fas fa-' prefix
    },
}

Config.ResponderStatuses.coastguard = {
    { id = 'available', label = 'Available',      color = '#22c55e', icon = 'check' },
    { id = 'enroute',   label = 'En Route',       color = '#3b82f6', icon = 'route' },
    { id = 'onwater',   label = 'On the Water',   color = '#a855f7', icon = 'water' },
    { id = '10-7',      label = '10-7',           color = '#6b7280', icon = 'moon' },
}

Config.Panic.titles.coastguard   = 'COAST GUARD NEEDS BACKUP'
Config.Panic.messages.coastguard = 'Coast guard panic alert'

Config.Civilian.Categories911 = {
    -- ... existing entries ...
    { id = 'boatdistress', label = 'Boat in Distress', code = '911', jobs = 'coastguard' },
}

Config.Detection.Explosion = { enabled = true, code = '10-77', jobs = { 'police', 'ems', 'fire', 'coastguard' } }

There is no SQL migration, no client UI rebuild, and no oxide-police change required. Responder groups are entirely shared-config driven.

Running alongside oxide-police

When oxide-police is installed and started, server/modules/police_lookup.lua takes over the police group's job list:

• On dispatch boot, when oxide-police (re)starts, and every 60 seconds, the module queries SELECT name FROM police_departments WHERE is_enabled = 1 from oxide-police's table. (A player changing job only refreshes that one player's per-player flags — it does not re-run the full department query.)
• The result replaces Config.ResponderGroups.police.jobs in memory.
• If the query fails (or oxide-police isn't installed), it falls back to the static seed defined in jobs.lua.

Practical consequences:

Editing Config.ResponderGroups.police.jobs directly while oxide-police is running is not harmful — it's just pointless. The next refresh wipes it.

Other side effects when oxide-police is running:

• Duty checks (Config.Broadcast.onDutyOnly) defer to exports['oxide-police']:IsPlayerOnDuty(src) for LEOs.
• AI radio police-MDT tools (lookup_plate, lookup_person, BOLOs, etc.) auto-attach to channels whose job ends up in the live police job list.

The per-player statebags oxide-dispatch:isLEO (boolean) and oxide-dispatch:responderGroup (string|nil) are published for every player whether or not oxide-police is running — without it, they're computed from the static lists in jobs.lua instead of the live department table.

Verification

After making changes:

/testdispatch 10-71 police
/testdispatch 10-52 ems
/testdispatch 10-70 fire
/testdispatch 911 coastguard      # your new group

print(Player(source).state['oxide-dispatch:responderGroup'])

If an on-duty player isn't receiving alerts, the Troubleshooting doc walks through the duty filter, rate limiter, and oxide-police integration checks.

Next Steps