Module: Cold Chain Management v1.0.0
What is Cold Chain Management?
Temperature-controlled supply chain monitoring, equipment tracking, and excursion alerts for Perfex CRM
This module installs into modules/cold_chain/ and adds its own admin menus, permissions, and database tables — without editing Perfex CRM core files.
Who should use this module?
- Admins — activate the module, configure Settings, assign roles, and manage integrations.
- Operators / day-to-day staff — create and update records (orders, attendance, shipments, messages, etc.).
- Managers / approvers — review queues, approve workflows, and monitor dashboards/KPIs.
- Finance / compliance / ops leads — run reports, exports, and audit trails when the module supports them.
What you can achieve
- Keep all related work in one place inside Perfex CRM instead of spreadsheets.
- Control who can view, create, edit, approve, or export with role permissions.
- Use dashboards and reports to see status, bottlenecks, and history.
- Connect to other CRM data (customers, invoices, items, staff) where the module integrates.
Recommended learning path
- Read How to Install and activate the module.
- Skim Features so you know what screens exist.
- Complete the Quick Start checklist on this page (Settings → masters → first sample record).
- Open each screen guide under Screen-by-screen guides when you need step-by-step help.
- Check Version & Changelog after upgrades for new options.
Tip: Train one admin first, then create a limited role for operators so they only see the screens they need.
5-minute Quick Start
Follow this short path the first time you use Cold Chain Management:
- Activate — Setup → Modules → activate Cold Chain Management (run Upgrade if prompted).
- Permissions — Setup → Staff → Roles → enable view/create/edit (and approve/settings if needed) for this module.
- Settings — Open Cold Chain Management → Settings and save company defaults, prefixes, and integrations.
- Master data — Create the first required masters (products, warehouses, templates, channels, accounts, routes, etc.).
- First transaction — Create one sample record end-to-end (save → submit/approve → complete) and confirm it appears in lists/reports.
- Cron — If the module uses alerts, sync, queues, or AI, confirm Perfex CRM cron is scheduled on the server.
Module documentation index
Start here — full guides for Cold Chain Management:
- Overview & How to Use — what it is, who uses it, daily workflow
- Quick Start Guide — first 5 minutes + printable how-to
- How to Install — upload, activate, permissions, verify
- Features (Full Detail) — every capability explained
- FAQ & Tips — common questions and best practices
- Version & Changelog — version history
Screen-by-screen guides (each tab explained)
Click a menu item below for step-by-step instructions on that Cold Chain Management screen:
- Cold Chain Dashboard
- Temperature Zones
- Equipment
- Monitoring Devices
- Temperature Readings
- Excursion Alerts
- Shipments
- Calibration Records
- Maintenance Schedules
- API Keys
- Webhooks
- Bulk Import
- Compliance Reports
- Chain of Custody
- Batch Traces
- Settings
How to use in Perfex CRM (daily operations)
- Sign in to the admin area with a role that includes Cold Chain Management permissions.
- Open Cold Chain (sidebar) or search for Cold Chain Management in the admin menu.
- Start on the Dashboard (if available) to see open tasks, pending approvals, and KPIs.
- Review Settings after upgrades — new options may need defaults for your company.
- Create or import master data first; most modules block transactions until masters exist.
- Run the main business flow (create → submit → approve → post/complete) using the screens listed in Admin menu below.
- Use Reports / Analytics screens to reconcile stock, finance, compliance, or SLA metrics.
- For integrations (API, EDI, gateways, tax), confirm credentials in Settings and monitor logs or webhook delivery screens.
- Train staff with role-based access — give approvers approve permissions only, operators create/edit on their area.
- If something fails overnight, check Perfex CRM cron ran and open the module log / failed queue screen if present.
Admin menu — where to work
Open the Cold Chain Management section in the admin sidebar. Screens your staff may use (depending on role):
- API Keys
- Batch Traces
- Bulk Import
- Calibration Records
- Chain of Custody
- Cold Chain
- Cold Chain Dashboard
- Compliance Reports
- Equipment
- Excursion Alerts
- IoT API & Webhooks
- IoT Bulk Import
- Maintenance Schedules
- Monitoring Devices
- Settings
- Shipments
- Temperature Readings
- Temperature Zones
- Webhooks
Screens map — what each menu is for
These are the admin screens registered by Cold Chain Management. Click a name in the Knowledge Base for a full how-to, or open the path in admin.
| # | Screen | Admin path | Guide |
|---|---|---|---|
| 1 | Cold Chain Dashboard | admin/cold_chain | How to use |
| 2 | Temperature Zones | admin/cold_chain/cold_chain_temperature_zones | How to use |
| 3 | Equipment | admin/cold_chain/cold_chain_equipment | How to use |
| 4 | Monitoring Devices | admin/cold_chain/cold_chain_monitoring_devices | How to use |
| 5 | Temperature Readings | admin/cold_chain/cold_chain_temperature_readings | How to use |
| 6 | Excursion Alerts | admin/cold_chain/cold_chain_excursion_alerts | How to use |
| 7 | Shipments | admin/cold_chain/cold_chain_shipments | How to use |
| 8 | Calibration Records | admin/cold_chain/cold_chain_calibration_records | How to use |
| 9 | Maintenance Schedules | admin/cold_chain/cold_chain_maintenance_schedules | How to use |
| 10 | API Keys | admin/cold_chain/cold_chain_api_keys | How to use |
| 11 | Webhooks | admin/cold_chain/cold_chain_webhooks | How to use |
| 12 | Bulk Import | admin/cold_chain/cold_chain_iot_import | How to use |
| 13 | Compliance Reports | admin/cold_chain/cold_chain_compliance_reports | How to use |
| 14 | Chain of Custody | admin/cold_chain/cold_chain_chain_of_custody | How to use |
| 15 | Batch Traces | admin/cold_chain/cold_chain_batch_traces | How to use |
| 16 | Settings | admin/cold_chain/cold_chain_settings | How to use |
Detailed guide — features, workflows, API & FAQ
Features
- Temperature zones, equipment, monitoring devices, and readings
- Excursion alerts with optional QMS NCR integration
- Shipments with in-transit temperature logging
- Calibration records and maintenance schedules
- REST API, webhooks, and bulk IoT import
- Compliance PDF reports, chain of custody, and batch/lot tracing
- Multi-plant scoping and warehouse linking (optional companion modules)
2. Quick Start (5 minutes)
- Settings — set default temperature unit (Celsius/Fahrenheit), alert prefixes, and enable auto excursion alerts.
- Temperature Zones — create zones (e.g. 2–8°C vaccine, −20°C freezer).
- Equipment — register cold rooms / refrigerators and assign a zone.
- Monitoring Devices — add sensors/loggers and link them to equipment.
- Temperature Readings — add a reading outside the zone range to verify excursion alerts.
- Open the Dashboard to see live status and open alerts.
3. How to Use Each Feature
Dashboard
Menu: Cold Chain Management → Dashboard
- See totals for zones, equipment, devices, readings, and open alerts.
- Live monitoring table refreshes automatically (interval set in Settings).
- Quick links to create readings, shipments, or open alerts.
Temperature Zones
Define allowed min/max temperature for a storage or transport condition. Equipment and readings use these thresholds to detect excursions.
Equipment
Track cold assets (cold room, refrigerator, freezer, refrigerated vehicle, cooler box). Set calibration dates and optional plant/warehouse links if companion modules are installed.
Monitoring Devices
Represent physical sensors. Devices can receive readings via UI, CSV import, or REST API. Offline status uses heartbeat + Settings “device offline minutes”.
Temperature Readings
Log temperature (and optional humidity, batch/lot). If the value is outside the zone range and auto-alerts are enabled, an Excursion Alert is created.
Excursion Alerts
Investigate open alerts, change status (open → investigating → resolved/closed), and add resolution notes. Optionally auto-create a QMS NCR when the QMS module is available and the setting is enabled.
Shipments
Create a cold shipment, attach zone/equipment/device, update status through planned → in transit → delivered. Add in-trip readings and export a PDF trip report.
Calibration Records
Record calibration date, next due date, result (pass/fail/conditional), vendor, and upload a certificate file. Cron can email staff when due.
Maintenance Schedules
Plan preventive/corrective/inspection work on equipment or devices, including downtime flags.
Compliance Reports
Generate GDP/GMP-style PDF temperature history for audits for a selected date range / equipment.
Chain of Custody
Log custody events (storage, pickup, transit, delivery, handoff, inspection) with parties, location, temperature, and batch/lot. Export PDF.
Batch / Lot Traces
Link temperature evidence to a manufacturing batch or lot for full product traceability.
API Keys, Webhooks & IoT Import
Create API keys for device integrations, configure webhooks for events such as calibration due / shipment excursion, and bulk-import readings from CSV.
Settings
Enable/disable module features, prefixes, API/webhooks, plant scoping, warehouse linking, batch tracing, live refresh interval, and QMS NCR auto-create.
4. Feature Summary
- Live dashboard & temperature monitoring
- Zones, equipment, devices, readings, excursion alerts
- Shipments with trip PDF reports
- Calibration certificates & maintenance schedules
- Compliance PDF, chain of custody, batch tracing
- REST API, webhooks, CSV IoT import
- Optional Multi-Plant / Inventory / QMS integrations
- Clean uninstall (tables + options + uploads)
5. Permissions
Assign under Setup → Staff → Roles. Main capability groups:
| Feature | Typical capabilities |
|---|---|
| Dashboard | view |
| Temperature Zones / Equipment / Devices / Readings | view, create, edit, delete |
| Excursion Alerts | view, create, edit, delete, resolve |
| Shipments / Calibration / Maintenance / Custody | view, create, edit, delete |
| Batch Traces | view, create, delete |
| Compliance Reports | view |
| IoT API / Import | view, create, edit, delete (as applicable) |
| Settings | view, edit |
6. REST API & Webhooks
- Enable REST API / Webhooks in Settings.
- Create an API key under API Keys.
- Send requests with the key header/token as documented in your admin UI.
- Create webhooks for outbound events and review delivery logs.
Typical endpoints cover health/status, zones, equipment, alerts, shipments, and device readings.
7. Cron Jobs
Calibration reminders and related background tasks use the main Perfex cron:
* * * * * php /path/to/perfex_crm/index.php cron/index > /dev/null 2>&1
Enable calibration alerts in Settings and ensure cron is running on the server.
8. Uninstall (removes all module data)
- Setup → Modules → Deactivate Cold Chain Management.
- Click Uninstall.
This permanently deletes:
- All
ccm_*database tables - All module options / settings
- Module email templates
- Uploaded files under
uploads/cold_chain/
After activation — configuration checklist
- Extract the download ZIP. You should see a folder named cold_chain.
- Log in as administrator → Setup → Modules.
- Find Cold Chain Management and click Activate.
- If Perfex shows Upgrade Database, click it once.
- Go to Setup → Staff → Roles and grant Cold Chain permissions to the roles that need access.
- Open the left sidebar menu Cold Chain Management.
- Perfex CRM 2.3+ (3.x recommended)
- PHP 7.4+ (8.1+ recommended)
- MySQL 5.7+ / MariaDB 10.3+ (InnoDB)
- Extensions: mysqli, json, mbstring, curl, fileinfo
One-time setup (first time only)
- Setup → Modules → activate Cold Chain Management.
- Setup → Staff → Roles → assign Cold Chain Management permissions (view, create, edit, delete, approve, export, settings as needed).
- Open Cold Chain Management → Settings and complete company defaults, prefixes, integrations, and notification options.
- Create master data (warehouses, products, templates, accounts, routes, etc.) before processing live transactions.
- Enable Perfex CRM cron (
php /path/to/perfex/index.php cron/index) for sync, retries, alerts, and scheduled jobs. - Optionally enable REST API / webhooks in module settings if you integrate external systems.
Tips for success
- Always configure Settings before creating live transactions.
- Create master data (items, warehouses, templates, channels, accounts) first — most modules block incomplete records.
- Use a test/sample record before going live with real customers or production stock.
- Separate roles: operators create/edit; managers approve; finance/reporting get view/export only.
- After any module upgrade, reopen Settings and confirm new options have sensible defaults.
- If overnight jobs fail, verify Perfex CRM cron and check the module log / failed queue screen.
Common questions (FAQ)
Where do I find the module after activation?
In the admin sidebar look for Cold Chain Management. If missing, your role may lack view permission — fix under Setup → Staff → Roles.
Do I need to edit core Perfex CRM files?
No. Keep all custom code under modules/cold_chain/. Activate/deactivate from Setup → Modules.
What happens if I uninstall?
Deactivate keeps data. Uninstall usually removes module tables/options (see the Install article). Core customers, invoices, and items are not deleted by well-built modules.
Why can't my staff see a screen?
Almost always a permissions issue. Give the role at least view on that feature, then ask the user to log out and back in.
Reports/export buttons do nothing
Confirm the role has export (or view reports) permission, and that filters return at least one row. Try PDF/CSV from a wider date range.
FAQ from module documentation
Support
See documentation/index.html and CODECANYON.md for marketplace listing copy.
Perfex CRM Knowledge Base — detailed usage guide generated from module README, HOW_TO_USE, and documentation.