Client Pipeline & Tasks

Client Pipeline & Tasks

NexusRMS includes a built-in sales pipeline and task management system tied directly to each client record. The pipeline tracks where a deal stands, whilst tasks ensure nothing falls through the cracks — from initial follow-ups to proposal deadlines and recurring check-ins.

Client Pipeline

Every client can have a pipeline entry that tracks the commercial relationship through defined stages. The pipeline record is stored as a ClientPipeline and contains the following fields:

• stage_id — Foreign key to the PipelineStage table. Determines the current position in your sales funnel (e.g. Lead, Qualified, Proposal Sent, Negotiation, Won, Lost).
• assigned_to — The user responsible for progressing this deal. Appears as the pipeline owner in list and board views.
• deal_value — Estimated monetary value of the deal, stored as a decimal with two decimal places.
• currency — Currency code for the deal value (e.g. GBP, USD, EUR).
• win_probability — A percentage from 0 to 100 representing how likely the deal is to close.
• expected_close_date — The date by which you expect the deal to convert.
• notes — Free-text notes about the current pipeline status.

Weighted value and effective probability

The system calculates a weighted value using the formula: deal_value × (win_probability / 100). For example, a £10,000 deal at 60% probability has a weighted value of £6,000. This is returned by the getWeightedValue() method.

The getEffectiveProbability() method returns the client-specific win probability if set, falling back to the pipeline stage's default probability if the client value is empty.

Stage tracking and duration

When a pipeline entry is first created, the stage_entered_at timestamp is set automatically. The days_in_stage field tracks how long the deal has been in its current stage, and calculateDaysInStage() recalculates this value on demand by comparing stage_entered_at to the current date.

Moving between stages

Use the moveToStage(stageId, userId, notes) method to advance or revert a deal. This resets stage_entered_at to the current time, clears days_in_stage to zero, and triggers a history record. You can also move stages by dragging the client card on the pipeline board view.

Pipeline history

Every stage transition is recorded in the ClientPipelineHistory table with the following fields:

• from_stage_id — The stage the deal was in before the move
• to_stage_id — The stage the deal moved to
• moved_by — The user who performed the stage change
• notes — Any notes recorded at the time of the move
• days_in_previous_stage — How many days the deal spent in the previous stage
• moved_at — Timestamp of the transition

Lost deals

When a deal is lost, call markAsLost(reason, notes, userId). This moves the pipeline entry to the designated lost stage, records the lost_reason and optional lost_notes. Lost deals remain visible for reporting and can be reopened by moving them back to an active stage.

Pipeline scopes

The following query scopes are available for filtering pipeline records:

• inStage(stageId) — Filter by a specific pipeline stage
• assignedTo(userId) — Filter by the assigned user
• withDealValue() — Only records that have a deal value greater than zero
• expectedToCloseBy(date) — Deals expected to close by a given date
• overdue() — Deals past their expected close date that are still in open stages

Client Tasks

Client tasks are follow-up items, reminders, and action points linked to a client record. Each task is stored as a ClientTask with comprehensive tracking for assignment, completion, and recurrence.

Task types

Every task has a type field set to one of the following values:

• follow_up — General follow-up action
• call — Phone call to make
• email — Email to send
• meeting — Scheduled meeting
• demo — Product demonstration
• proposal — Proposal to prepare or send
• other — Any other task type

Priority levels

The priority field accepts: low, normal, high, or urgent. High and urgent tasks are surfaced by the highPriority() scope and are visually highlighted in the task list.

Task statuses and outcomes

The status field progresses through: pending, in_progress, completed, or cancelled. When a task is completed, you may record an outcome: successful, unsuccessful, rescheduled, or no_answer.

Core task fields

Each task includes: title, description, due_date, due_time, assigned_to (the responsible user), and created_by (the user who created the task).

Reminders

Set reminder_at to schedule an automatic reminder. The reminder_sent boolean tracks whether the reminder has been dispatched. The reminder_channel field controls the notification method. The needsReminder() scope finds open tasks where the reminder time has passed but the reminder has not yet been sent.

Completing and cancelling tasks

Call complete(userId, outcome, notes) to mark a task as completed. This sets the completed_by, completed_at, completion_notes, and outcome fields. Call cancel(userId, notes) to cancel a task. Use reschedule(newDueDate, newDueTime) to move a task to a different date, which also resets the reminder.

Recurring tasks

Enable recurrence by setting is_recurring to true and choosing a recurrence_pattern: daily, weekly, monthly, or custom. Custom patterns use the recurrence_config JSON field with interval and unit keys (e.g. {"interval": 2, "unit": "week"} for fortnightly). When a recurring task is completed, the system automatically creates the next occurrence via createNextRecurrence() using calculateNextDueDate(). The new task is linked to the original through parent_task_id.

Linked records

Tasks can be linked to: a client, a contact (client_contact_id), an opportunity (opportunity_id), or a project (project_id). Tasks also support child tasks and comments (via the ClientTaskComment model) for collaboration.

Useful task scopes

• pending() — Tasks with status pending
• overdue() — Open tasks past their due date
• dueToday() — Open tasks due today
• dueThisWeek() — Open tasks due within the current week
• assignedTo(userId) — Tasks assigned to a specific user
• highPriority() — Tasks with high or urgent priority
• needsReminder() — Open tasks where the reminder is due but unsent

Helper methods

isOverdue() returns true if the task is open and past its due date. isDueToday() checks whether the due date is today. isCompleted() and isOpen() check the current status.

Tips

• Use recurring tasks for regular client check-ins such as quarterly reviews or annual contract renewals.
• Set reminders at least 24 hours before the due date to give yourself time to prepare.
• Review the overdue() and dueToday() scopes on your dashboard each morning to stay on top of follow-ups.
• Record an outcome on every completed task — this data feeds into pipeline analytics and helps identify patterns.
• Link tasks to specific contacts and projects for full traceability of who was contacted about what.
• Use the pipeline board view (drag-and-drop) for a visual overview of all deals across stages.