Skip to content

Deals and Delivery

Last updated: 2026-10-28. Category routing describes the repository implementation; see the release status for deployment.

This page documents the implemented rules that connect CRM Deals, Zoho Projects, and CRM Delivery Models.

Project From Deal

When the deal-created workflow calls middleware, the automation ensures the Deal has a linked Zoho Project unless the Deal is in a skipped business category.

Rules currently implemented:

  • Only MSP - New Client, Tech Project and Tech Retainer create Scoping projects. MSP - Additional Product / Service, Hardware, Home, blank and unsupported values are skipped. Legacy MSP and Tech Projects retain their previous paths.
  • If the Deal already has a project_id, that project is reused.
  • If the Deal has no project_id, a Zoho Project is created using the Deal name and linked back to the Deal with project_id and project_link.
  • The automation tries to match the CRM Deal owner to a Zoho Projects user by email. If matched, it assigns that Projects user as project owner.
  • The project must have a Scoping tasklist.
  • The project must have a Scoping task in the Scoping tasklist.
  • If an owner was resolved, the Scoping task is assigned to that owner.
  • The automation ensures a CRM Delivery Model named Scoping exists for the project and Deal:
    • Revenue_Model: One-Time;
    • Scope_Type: Tasklist;
    • Valid_From: today;
    • Amount: 0;
    • Labour_Unit: Hour;
    • Labour_Amount: 5.0;
    • linked to the Scoping tasklist.

Business reasoning:

  • The sales-to-delivery handoff starts with a predictable Projects workspace and a scoped Delivery Model, but low-touch Hardware/Home work is excluded.
  • Reusing the existing linked project keeps the workflow idempotent and avoids duplicate Projects records.

Reserved Deal Setup

When a Deal reaches Reserved, the automation runs only for MSP - New Client and Tech Project, including the legacy MSP and Tech Projects aliases. Tech Retainer has a Scoping project but requires manual recurring delivery setup; it must not inherit the one-time project model. MSP additions use the existing service and do not create onboarding projects.

Rules currently implemented:

  • If the Deal is not at the target stage, it is skipped.
  • If the Deal category does not resolve to new-client MSP or Tech Project, it is skipped.
  • If the Deal does not have a linked project, the automation fails instead of creating one at this stage.
  • The linked project must have a Scoping tasklist.
  • The Scoping tasklist is closed if it is not already completed.
  • The automation attempts to set the existing Scoping Delivery Model Valid_Until to today. If that Delivery Model is missing or cannot be updated, the result includes a warning and the rest of the reserved setup continues.
  • The Deal Closing_Date is set to today.

For MSP - New Client Deals (and legacy MSP):

  • The project must have Audit/Onboarding and Tech support tasklists.
  • The automation ensures these Delivery Models:
    • Audit/Onboarding, scoped to the Audit/Onboarding tasklist;
    • Tech Support, scoped to the project.
  • Both are created with Revenue_Model One-Time, Valid_From today, and zero amount/labour values.

For Tech Project Deals:

  • The automation ensures one project-scoped Delivery Model named WIP Update from Signed QWILR.
  • Its Amount comes from the Deal amount.
  • Its Labour_Unit is Day.
  • Its Labour_Amount is calculated from the Deal amount divided by the implemented daily rate of 1400.

Business reasoning:

  • Moving to the reserved stage closes scoping and opens the delivery tracking structures that match the Deal type.
  • MSP and Tech Project delivery models differ because MSP onboarding and support are structured differently from one-off project delivery.

Delivery Model Progress and Alerts

MSP monthly labour expectations use L1: 15 minutes (0.25 hours), L2: 30 minutes (0.5 hours), L3: 1.5 hours per seat per month, multiplied by the seat count. L3 support is unlimited; 1.5 hours is an indicative expectation for planning and reporting, not a support limit. Record all work even when it exceeds the expectation. Generated MSP Delivery Models still require manual entry and review of these budgets. See the MSP setup procedure and Commercial Margin labour rules.

Delivery Model progress can be evaluated through two implemented paths:

  • alert evaluation, which can update CRM and optionally send milestone emails;
  • state sync, which can update CRM without sending milestone emails.

Both paths work from active Delivery Models only, unless a specific Delivery Model is requested through the state-sync path.

A Delivery Model is considered active for these calculations when:

  • it has a project ID;
  • it has valid expected labour information;
  • Valid_Until is blank or not in the past.

In Power BI reporting, Valid_Until also provides the Delivery Model status: models with Valid_Until before the report refresh date are shown as completed; models with Valid_Until blank, today, or in the future are shown as active.

One-time Delivery Model rules currently implemented:

  • Progress is based on total logged minutes divided by expected minutes.
  • Completion percentage is normalized before being compared with the stored CRM value.
  • When completion changes, CRM update data is prepared for Last_Completion_Pct and Last_Completion_Updated_At.
  • In alert evaluation, Cumulated_Amount is prepared when completion changes and the calculated amount differs from the stored amount.
  • In state sync, Cumulated_Amount is also prepared whenever the calculated amount differs from the stored amount.
  • Alert milestones are detected when progress crosses 30%, 50%, 90%, or 100% since the last stored completion value.

Recurring Delivery Model rules currently implemented:

  • Sequential models may share the same project and scope. Each timelog is assigned only to a model whose inclusive Valid_From / Valid_Until period contains the log date.
  • When sequential validity periods are adjacent, historical months remain on the expired model and later months continue on the replacement model.
  • If valid models overlap at the same scope, the model with the latest Valid_From wins for the overlapping dates.
  • Current-month progress is calculated from current-month logged minutes divided by current-month expected minutes.
  • If the stored tracking month is not the current month, current-month fields are reset for the new month.
  • Overall progress is calculated across active months to date.
  • Cumulated_Amount is calculated from the monthly amount multiplied by active months to date. Alert evaluation prepares that update when other recurring CRM updates are needed; state sync prepares it whenever the calculated amount differs from the stored amount.
  • Alert milestones are detected from current-month completion crossing 30%, 50%, 90%, or 100%.

Alert email rules currently implemented:

  • Alert emails are sent only when send_alerts is requested and CRM updates are also being applied.
  • If CRM updates fail, alert email is skipped.
  • If no new milestone was crossed, alert email is skipped.
  • Recipients are the configured alert recipients plus deduplicated project timelog user emails for projects with alert candidates.
  • If no recipients can be found, the email is skipped.
  • The email is attached to the first candidate Delivery Model record.

Business reasoning:

  • Completion alerts are based on threshold crossings, not every recalculation.
  • Recurring models need a separate current-month state so monthly progress can reset while overall completion still remains available.
  • Date-aware timelog assignment preserves historical expectations when a recurring model is replaced without changing the Zoho Project.
  • Alert emails are tied to successful CRM updates so people are not notified about milestones that were not written back.

Deliberate Limits

  • The project-from-deal workflow does not create projects for MSP additions, Hardware, Home or unrecognised business categories.
  • Reserved setup does not create a missing linked project.
  • Delivery Model alert evaluation does not send email unless CRM updates are applied in the same run.
  • Delivery Model calculations do not include inactive or invalid-scope models in normal runs.

References

  • Code: app/automations/projects_from_deal/project_bootstrap.py
  • Code: app/automations/projects_from_deal/reserved_pending.py
  • Code: app/automations/projects_from_deal/delivery_models.py
  • Code: app/automations/delivery_model_completion.py
  • Code: app/automations/delivery_model_completion_calculations.py
  • Code: app/delivery_models/alerts.py
  • Routes: POST /zoho/projects/from-deal, POST /zoho/projects/on-deal-reserved-approval-payment-pending, POST /zoho/delivery-models/alert-evaluation, POST /zoho/delivery-models/state-sync