Easily plan, manage, and track client commissions.
- Must be using
expresson Node.js - Must be using
express-sessionfor session management - Must be using a valid session store (e.g.,
express-mysql-sessionfor MySQL)
Include the commtrackr package in your Express.js application:
const express = require('express'); const session = require("express-session"); const MySQLStore = require('express-mysql-session')(session); // Use a MySQL session store const sessionStore = new MySQLStore({ host: '', port: 3306, user: '', password: '', database: '' }); app.use(session({ name: '', key: '', secret: '', store: sessionStore, resave: false, saveUninitialized: false })); const app = express(); const commtrackr = require('commtrackr'); // Import the commtrackr package app.use('/commtrackr', commtrackr.routes); // Mount routes to /commtrackr path commtrackr.init({ // Initialize CommTracker with configurations tenant: { slug: 'commtrackr', // Unique identifier for the tenant name: 'CommTrackr', // Name of the tenant metaTitle: 'CommTrackr', // Name of the tenant for meta title tags description: 'Easily plan, manage, and track client commissions.', // Description of the tenant logo: 'http://localhost:3000/commtrackr/logo.png', // Tenant logo image themeColor: '#ffffff', // Tenant theme color (optional) forceDarkMode: false, // Force dark mode for the tenant (optional) banner: 'http://localhost:3000/commtrackr/banner_public.png', // Tenant banner image domain: 'http://localhost:3000', // Domain for the tenant, including protocol path: '/commtrackr', // Path that CommTracker is mounted on auth: { enabled: false, // Enable or disable authentication provider: '', // Recognizable name of authentication provider url: '', // URL to redirect to for authentication }, stylesheets: [], // Additional stylesheets to include scripts: [], // Additional scripts to include customText: {} // Custom text overrides for the tenant; see "Custom Text" section below }, vars: { userId: 'username', // req.session object variable for unique user identification userName: 'Name', // req.session object variable for user name role: 'role', // req.session object variable for user role roleAliases: { // Use if your role names differ from 'admin', 'dev', or 'user' user: ['user', 'standard', 'basic'], // Aliases for user roles dev: ['dev', 'developer'], // Aliases for developer roles admin: ['admin', 'administrator', 'superuser'] // Aliases for admin roles }, access: { // Alternative access control using numeric levels var: 'access', // req.session object variable for access level user: [0], // Access levels for standard users dev: [1], // Access levels for developers admin: [2] // Access levels for admins }, commissions: 'commissions', // req.session object variable for user commissions array possibleStatuses: [ // Possible commission status strings { label: 'Completed', // Status label value: 'Completed' // Status value }, { label: 'In Progress', value: 'In Progress' }, { label: 'On Hold', value: 'On Hold' }, { label: 'Cancelled', value: 'Cancelled' } ], disableFieldEditing: ['amount', 'currency'], // Array of field IDs that admins cannot edit users: 'users' // req.session object variable for all users array }, fields: [ { id: 'name', // Unique identifier for the field. ID 'user' is reserved by the system and may not be used here type: 'text', // Field type ('text', 'number', 'date', 'textarea', 'checkbox', 'radio', 'select', 'multiselect') label: 'Website Name', // Field label description: 'The name of the website or project.', // Field description placeholder: 'e.g. My Website', // Placeholder text for the field required: true, // Whether the field is required options: [ // Options for select, radio, and multiselect fields { label: 'Option 1', // Option label value: 'option1' // Option value } ], }, ], handlers: { create: (req, data) => { // Custom handler function for processing commission data // This function is called when a commission is created // You can implement your own logic here, such as saving to a database // data contains the commission fields data array // Action metadata can be accessed via data.createdAt and data.createdBy }, update: (req, data) => { // Custom handler function for updating commission data // This function is called when a commission is updated // You can implement your own logic here, such as saving to a database // data contains the updated commission object // The constant data.id contains the unique commission ID // Action metadata can be accessed via data.updatedAt, data.updatedBy, and data.sendEmail // Updated metadata can be accessed via data.user, data.amount, data.currency, data.date, data.status, data.locked, and data.assignedTo // Updated fields can be accessed via data.fields // Updated tasks can be accessed via data.tasks }, sync: (req) => { // Custom handler function for syncing user's commissions // This function is called when the user manually triggers a sync // You can implement your own logic here, such as syncing your commissions session variable }, }, }); app.listen(3000, () => { console.log('Server is running on http://localhost:3000'); });
These variables must be set in your req.session object to enable CommTrackr functionality. Alternatively, you can modify the variable names to match your custom session configuration using the vars configuration during initialization.
userId must contain a unique identifier for the user, such as a username or user ID. This is used to track user-specific data. This must be present for CommTrackr to detect a logged-in user.
Type: String
Default: 'username'
Fallback: None
Session Example: 'id'
userName should contain the name of the user. This is used for display purposes in the CommTrackr interface. Fallback to userId if not set.
Type: String
Default: 'name'
Fallback: userId
Session Example: 'John Doe'
role should contain the role of the user: 'admin', 'dev', or 'user'. This is used to control access to certain features and functionalities within CommTrackr.
Type: String
Default: 'role'
Fallback: 'user'
Session Example: 'user', 'dev', 'admin'
role can also be set to custom role names. Use roleAliases to map your custom role names to the standard roles used by CommTrackr.
Type: Object
Default:
{}
access can be used as an alternative to role for access control. It should contain numeric access levels. Use the access configuration to define which levels correspond to 'user', 'dev', and 'admin'.
Type: Array
Default:
{}
commissions should be an array of commission objects associated with the user. Each commission object should have the following structure:
Type: Array
Default: 'commissions'
Session Example:
[ { id: 'unique-commission-id', // Unique identifier for the commission user: 'userId', // Commission creator's unique userId. Should match the userId variable, otherwise the commission will only be accessible in admin/dev views amount: 1000, // Commission amount as a number, or null if not applicable. Defaults to null currency: 'USD', // Currency code for the commission amount as a string. Defaults to 'USD' date: '2023-10-01', // Date of the commission in any valid date/datetime format. Defaults to null status: 'On Hold', // Status of the commission as a string (e.g., 'Completed', 'In Progress', 'On Hold', 'Cancelled') fields: { // Custom fields associated with the commission 'id': 'value' // Key-value pairs for custom fields }, tasks: [ // Array of tasks associated with the commission { done: false, // Task completion status. Defaults to false content: '' // Task description. Defaults to '' } ], locked: false, // Whether commission is locked from being edited by user. Defaults to false links: [ // Array of links associated with the commission { label: 'Link Label', // Link label url: 'http://example.com' // Link URL } ], assignedTo: ['dev1UserId', 'dev2UserId'] // Array of userIds of the developers assigned to this commission } ]
possibleStatuses should be an array of possible commission status objects. Each status object should have a label and value property.
Type: Array
Default:
[]
disableFieldEditing should be an array of field IDs that admins cannot edit. This is useful for restricting access to certain fields even for admin users.
Type: Array
Default:
[]
users should contain an array of all users and developers in the system. Each user object should have at least userId and defined matching role or access.var properties. userName property is recommended, but not required. This is used for assigning commissions to owners and developers.
Type: Array
Default: 'users'
The tenant customText configuration allows you to override default text strings used throughout the CommTrackr interface. This is useful for localization or customizing the user experience. The available text strings are as follows:
{
"userWelcomeBefore": "Welcome, ",
"userWelcomeAfter": "!",
"activationTitle": "Activation",
"sessionTitle": "Enable Cookies",
"tenantTitle": "Configuration",
"authTitle": "Authentication Required",
"authDescriptionBefore": "You'll need to log into your ",
"authDescriptionAfter": " account before managing your commissions.",
"authContinueLabel": "Continue",
"adminTitle": "Commission Management",
"adminDescription": "Manage commissions created on your platform.",
"devTitle": "Commission Management",
"devDescription": "Manage commissions assigned to you.",
"userTitle": "Commissions",
"userDescription": "View and manage your past commissions.",
"newCommissionTitle": "New Commission",
"newTaskLabel": "New Task",
"notFoundTitle": "Not Found",
"forbiddenTitle": "Forbidden",
"forbiddenMessage": "You do not have permission to edit this commission.",
"errorTitle": "Error",
"errorMessage": "An unexpected error occurred. Please try again later.",
"labelStatus": "Status",
"labelStatusDescription": "Required: Commission status.",
"labelOwner": "Owner",
"labelOwnerDescription": "Required: Commission owner.",
"labelAmount": "Amount",
"labelAmountDescription": "Optional: Commission amount.",
"labelDate": "Date",
"labelDateDescription": "Optional: Commission creation date.",
"labelAssignedTo": "Assigned To",
"labelAssignedToDescription": "Optional: The developer to assign this commission to.",
"labelCurrency": "Currency",
"labelCurrencyDescription": "Optional: Commission currency.",
"labelLocked": "Locked",
"labelLockedDescription": "Optional: Whether or not the commission is locked from user editing.",
"labelTasks": "Tasks",
"labelSendEmail": "Send Email",
"labelSendEmailDescription": "Optional: Send an email to the user regarding this update.",
"labelRequired": "Required",
"labelOptional": "Optional",
"youLabel": "(you)",
"noneLabel": "None",
"backLabel": "Back",
"backLabelWithArrow": "← Back",
"nextLabel": "Next",
"startLabel": "Start",
"createLabel": "Create",
"returnLabel": "Return",
"restartLabel": "Restart",
"saveLabel": "Save",
"syncLabel": "Sync",
"backToLabel": "Back to ",
"changesSaved": "Changes saved",
"changesRestored": "Changes restored",
"clearChanges": "Clear changes",
"brandName": "CommTrackr",
"createEstimatedTime": "Estimated time to complete: 2 minutes",
"commissionNotFound": "The requested commission was not found.",
"commissionLocked": "This commission is locked from user editing.",
"resourceNotFound": "The requested resource was not found.",
"offTitle": "CommTrackr Disabled",
"offDescription": "Enable CommTrackr for your app using <code>commtrackr.on();</code>",
"tenantMisconfiguredTitle": "Tenant Misconfigured",
"tenantMisconfiguredDescription": "Configure your CommTrackr tenant using <code>commtrackr.init({ tenant: { ... } });</code>",
"serviceOffline": "Service is currently offline.",
"noSession": "No session found. Please enable cookies and try again.",
"userNotAuthenticated": "User not authenticated. Please log in and try again.",
"serviceNotConfigured": "Service is not properly configured. Please contact the administrator.",
"noFieldsConfigured": "No fields configured for commission creation. Please contact the administrator.",
"createSuccess": "Your commission was created successfully.",
"syncSuccess": "Your commissions were synchronized successfully.",
"updateSuccess": "Your commission was updated successfully.",
"commissionNotFoundJson": "The requested commission was not found."
}For more detailed documentation, including advanced configuration options and examples, please visit the CommTrackr Documentation.