shopdb-flask/plugins/employees

Employees plugin - directory database contract

Read-only lookups against a separate employee/HR directory database. Powers:

• Employee search (add people to a notification, browse the directory)
• Single + batch SSO lookup
• Recognition notifications (name + photo on the shopfloor / lobby displays)

The plugin never writes to this database. Use a read-only account.

Connection

Credentials resolve settings-first, then environment, except the password which is env-only (never stored in the app database).

Field	Setting key (editable in the setup wizard)	Env var (fallback)
Host	employee_db_host	EMPLOYEE_DB_HOST
Database	employee_db_name	EMPLOYEE_DB_NAME
User	employee_db_user	EMPLOYEE_DB_USER
Password	(not stored)	EMPLOYEE_DB_PASSWORD

Set the password in .env; the setup wizard's Features step shows the exact line to paste. Engine is MySQL/MariaDB (pymysql).

Required schema

The plugin runs these queries verbatim, so a site's database must expose a table (or view - see below) named employees with these columns:

Column	Type	Notes
SSO	INT	Unique person id. Lookups require it to be numeric
First_Name	VARCHAR	Displayed as the given name
Last_Name	VARCHAR	Displayed as the surname; sort key
Team	VARCHAR	Team / group label
Role	VARCHAR	Job title / role
Picture	VARCHAR	Image filename (see Photos)

Queries actually executed:

-- search
SELECT SSO, First_Name, Last_Name, Team, Role, Picture
FROM employees
WHERE First_Name LIKE %s OR Last_Name LIKE %s OR CAST(SSO AS CHAR) LIKE %s
ORDER BY Last_Name, First_Name LIMIT %s;

-- single / batch
SELECT SSO, First_Name, Last_Name, Team, Role, Picture FROM employees WHERE SSO = %s;
SELECT SSO, First_Name, Last_Name, Team, Role, Picture FROM employees WHERE SSO IN (...);

Rows are returned to the API with these exact column names. The frontend (EmployeeSearch, NotificationForm, EmployeeDetail, ShopfloorDashboard) reads SSO, First_Name, Last_Name, Team, Role, Picture as-is - do not rename them in the response.

Photos

Picture holds an image filename (e.g. 123456.jpg), not a path or blob. The app renders it as /static/employees/<Picture>, so the image files must live in the app's static/employees/ directory. Leave Picture empty/NULL for people with no photo; the UI falls back to initials.

Adapting a different site schema (recommended: a view)

Sites whose HR/directory database uses different table or column names should not be forced to rename anything. Instead, create a read-only view named employees that maps local columns to the names above:

CREATE VIEW employees AS
SELECT
  person_id        AS SSO,
  given_name       AS First_Name,
  surname          AS Last_Name,
  department       AS Team,
  job_title        AS Role,
  photo_filename   AS Picture
FROM hr_people
WHERE active = 1;

Grant the app's read-only user SELECT on the view. No app code changes - point employee_db_* at that database and the plugin works.

Notes:

• SSO must be numeric (single/batch lookup validate isdigit()).
• Column-name case follows your database's identifier casing; match the names above exactly on case-sensitive platforms.
• If the directory is unreachable or the employees object is missing, lookups return a 500 and the rest of the app keeps working (the feature degrades, it does not crash the app).