Module: Serialization & Track-and-Trace v1.0.0
What is Serialization & Track-and-Trace?
Serial number registry, generation rules, and chain-of-custody traceability for Perfex CRM
This module installs into modules/serialization_track_trace/ 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 Serialization & Track-and-Trace:
- Activate — Setup → Modules → activate Serialization & Track-and-Trace (run Upgrade if prompted).
- Permissions — Setup → Staff → Roles → enable view/create/edit (and approve/settings if needed) for this module.
- Settings — Open Serialization & Track-and-Trace → 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.
Full how-to guide (from module package)
The steps below come from the module author's printable guide — follow them in order for best results.
HOW TO USE — Serialization & Track-and-Trace for Perfex CRM (v1.0.0)
Author: Nasbix Technologies
1) INSTALLATION
- Extract the purchased ZIP.
2. Upload the "serialization_track_trace" folder to:
/modules/serialization_track_trace
- Login to Perfex CRM Admin.
4. Go to: Setup → Modules
- Find "Serialization & Track-and-Trace" and click Activate.
6. Database tables and options are created automatically
(stt_db_version = 100).
7. Assign permissions:
Setup → Staff → Roles / Permissions → STT capabilities
2) FIRST-TIME SETUP
1. Open: Track & Trace → Settings
2. Set:
- Enable STT Module
- Default serial prefix (e.g. SN-)
- Auto-generate serials
- Sequence padding
- Unique serial per item
- Recall / quarantine code prefixes
- Email notifications for recalls
- GS1 company prefix / GTIN options (optional)
- REST API enable + rate limit (optional)
- Customer portal enable / public verify (optional)
- Inventory / WMS / Manufacturing hooks (optional)
- Save settings.
3) DAILY WORKFLOW
A. Serial Generation Rules
- Track & Trace → Serial Generation Rules → New
- Set rule code, name, prefix/suffix, padding, format template
- Placeholders: {prefix}, {suffix}, {sequence}, {date}
- Optionally bind a rule to an item/product
B. Serial Numbers
- Track & Trace → Serial Numbers → New
- Enter serial manually OR auto-generate from a rule
- Set item, batch/lot, location, manufacture/expiry dates
- Optional GS1 fields: GTIN, SSCC, EPC
C. Trace Lookup (chain of custody)
- Track & Trace → Trace Lookup
- Search a serial number
- Review full event history
- Add new trace events (received, shipped, sold, etc.)
D. Recalls
- Track & Trace → Recalls → New
- Choose scope: batch/lot, item, serial range, or manual
- Initiate recall → notify staff (email template)
- Track affected serials until completed/cancelled
E. Quarantine Holds
- Track & Trace → Quarantine Holds → New
- Hold serials for quality / regulatory / investigation
- Release with notes when cleared
F. GS1 / EPCIS & Labels
- Track & Trace → EPCIS Export → search serial → download JSON/XML
- Open a serial → print barcode/QR label
G. REST API (optional)
- Settings → enable REST API
- Track & Trace → REST API → create API key (copy token once)
- Call: GET /serialization_track_trace/api/serial/{number}
- Header: Authorization: Bearer {token}
H. Customer Portal (optional)
- Settings → enable Customer Portal
- Public verify: /stt/verify
- Logged-in clients: Product Trace Lookup
4) UNINSTALL (CLEAN REMOVAL)
1. Setup → Modules → Deactivate Serialization & Track-and-Trace
2. Click Uninstall
3. Module removes:
- All stt_* database tables
- All stt_* options/settings
- STT email templates
- uploads/serialization_track_trace/ (if present)
- No Perfex CRM core files are modified.
5) SUPPORT
- Open documentation/index.html from the package
- Include Perfex version, PHP version, and stt_db_version when contacting support
- Author: Nasbix Technologies — https://nasbix.com
Module documentation index
Start here — full guides for Serialization & Track-and-Trace:
- 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 Serialization & Track-and-Trace screen:
- STT Dashboard
- Serial Numbers
- Serial Generation Rules
- Trace Lookup
- Product Recalls
- Quarantine Holds
- EPCIS Export
- REST API
- Settings
How to use in Perfex CRM (daily operations)
- Sign in to the admin area with a role that includes Serialization & Track-and-Trace permissions.
- Open Serialization Track Trace (sidebar) or search for Serialization & Track-and-Trace 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 Serialization & Track-and-Trace section in the admin sidebar. Screens your staff may use (depending on role):
- EPCIS Export
- Product Recalls
- Product Trace Lookup
- Quarantine Holds
- REST API
- Serial Generation Rules
- Serial Labels
- Serial Numbers
- Settings
- STT Dashboard
- Trace Lookup
- Track & Trace
Screens map — what each menu is for
These are the admin screens registered by Serialization & Track-and-Trace. Click a name in the Knowledge Base for a full how-to, or open the path in admin.
| # | Screen | Admin path | Guide |
|---|---|---|---|
| 1 | STT Dashboard | admin/serialization_track_trace | How to use |
| 2 | Serial Numbers | admin/serialization_track_trace/stt_serial_numbers | How to use |
| 3 | Serial Generation Rules | admin/serialization_track_trace/stt_serial_rules | How to use |
| 4 | Trace Lookup | admin/serialization_track_trace/stt_trace_lookup | How to use |
| 5 | Product Recalls | admin/serialization_track_trace/stt_recalls | How to use |
| 6 | Quarantine Holds | admin/serialization_track_trace/stt_quarantine_holds | How to use |
| 7 | EPCIS Export | admin/serialization_track_trace/stt_epcis | How to use |
| 8 | REST API | admin/serialization_track_trace/stt_api_keys | How to use |
| 9 | Settings | admin/serialization_track_trace/stt_settings | How to use |
Detailed guide — features, workflows, API & FAQ
Features
- Serial number registry with generation rules and sequence templates
- Chain-of-custody trace events and activity audit log
- Product recalls and quarantine holds with email notifications
- GS1 GTIN / SSCC / EPC identifiers and EPCIS JSON/XML export
- Barcode / QR label printing
- REST API, API keys, rate limiting, and customer portal verification
- Optional Inventory / GRN / WMS / Manufacturing / EDI integration hooks
- Role-based permissions and dashboard widget
Permissions
Assign capabilities under Setup → Staff → Roles for dashboard, serial numbers, rules, trace lookup, recalls, quarantine, EPCIS, API, and settings.
REST API Quick Start
- Settings → enable REST API
- REST API menu → create API key (save token immediately)
GET /serialization_track_trace/api/serial/{number}with headerAuthorization: Bearer {token}
Customer Portal
- Settings → enable Customer Portal
- Public page:
/stt/verify - Clients area: Product Trace Lookup (when logged in)
How to Use
1. Settings
Open Track & Trace → Settings. Enable the module, set serial prefix / padding, recall & quarantine prefixes, GS1 options, REST API, customer portal, and optional Inventory / WMS / Manufacturing hooks.
2. Serial Generation Rules
Create rules with prefix, suffix, sequence padding, and format template placeholders: {prefix}, {suffix}, {sequence}, {date}.
3. Serial Numbers
Register serials manually or auto-generate from a rule. Attach item, batch/lot, location, dates, and optional GTIN / SSCC / EPC.
4. Trace Lookup
Search any serial to view the chain-of-custody timeline and add events (received, shipped, sold, transferred, quarantined, recalled, etc.).
5. Recalls & Quarantine
Initiate product recalls by batch, item, serial range, or manual selection. Place quarantine holds and release them when cleared. Staff can receive recall email notifications.
6. EPCIS & Labels
Export GS1 EPCIS 2.0 JSON/XML documents and print barcode/QR labels from a serial record.
7. REST API & Portal (optional)
Enable REST API in Settings, create an API key, and call endpoints with Authorization: Bearer {token}. Enable Customer Portal for public /stt/verify and client-area trace lookup.
Also see HOW_TO_USE.txt in the package root.
Features
- STT Dashboard with KPIs and quick actions
- Serial registry + generation rules
- Chain-of-custody trace events
- Product recalls and quarantine holds
- GS1 identifiers and EPCIS export
- Barcode / QR label printing
- REST API keys with rate limiting
- Customer portal verification
- Optional Inventory / WMS / Manufacturing / EDI hooks
- Granular permissions and dashboard widget
- Clean install and uninstall
Permissions
Assign under Setup → Staff → Roles:
| Feature | Typical capabilities |
|---|---|
| Dashboard | view |
| Serial Numbers | view, create, edit, delete |
| Serial Rules | view, create, edit, delete |
| Trace Lookup | view, create |
| Recalls | view, create, edit, delete |
| Quarantine Holds | view, create, edit, delete |
| EPCIS Export | view, export |
| REST API | view, create, delete |
| Settings | view, edit |
REST API Quick Start
- Settings → enable REST API
- Track & Trace → REST API → create key (save token immediately)
GET /serialization_track_trace/api/serial/{number}- Header:
Authorization: Bearer {token}orX-STT-API-Key: {token}
Uninstall
- Deactivate the module in Setup → Modules.
- Click Uninstall.
Removes all stt_* tables, options, email templates, and uploads/serialization_track_trace/. Core Perfex CRM files are not modified.
After activation — configuration checklist
- Go to Setup → Modules and activate Serialization & Track-and-Trace.
- Tables and options are created automatically (stt_db_version = 100).
- Assign permissions under Setup → Staff → Roles.
- Open Track & Trace → Settings and configure the module.
- Perfex CRM 2.3+ (3.x recommended)
- PHP 7.4+ (8.1+ recommended)
- MySQL 5.7+ / MariaDB 10.3+ (InnoDB)
- PHP extensions: mysqli, json, mbstring, curl, fileinfo
One-time setup (first time only)
- Setup → Modules → activate Serialization & Track-and-Trace.
- Setup → Staff → Roles → assign Serialization & Track-and-Trace permissions (view, create, edit, delete, approve, export, settings as needed).
- Open Serialization & Track-and-Trace → 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 Serialization & Track-and-Trace. 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/serialization_track_trace/. 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.
Perfex CRM Knowledge Base — detailed usage guide generated from module README, HOW_TO_USE, and documentation.