Quoting a PPM Contract and Creating Routines

When to use this flow

Use a PPM contract quote when the customer is approving a planned preventative maintenance agreement. The quote can cover one site or the whole account.

Do not use this flow for normal remedial follow-up from an inspection defect. Use a Remedial work quote for that. Accepted remedial quotes continue to create or link to work orders.

Use an Ad hoc quote only when the quote should be accepted without creating a work order or service contract automatically.

What the flow creates

When a customer accepts a PPM contract quote, Deucalion creates or reuses one active service contract for that quote and creates the expected routines under that contract.

Acceptance does not create a remedial work order. Routine visits are generated later from the routine planning workflow, then reviewed in Scheduler before dispatch.

Create the PPM contract quote

1. Open Quotes.
2. Select New Quote.
3. Set Purpose to PPM contract.
4. Choose the CRM account.
5. Leave Site blank when the contract covers the account rather than one named site.
6. Add the customer name and email used for quote delivery.
7. Save the quote.

The CRM account is required before a PPM quote can be sent for approval. A site is optional because some maintenance agreements cover the customer account rather than a single location.

Add the commercial line items

1. Open the quote detail.
2. Add the contract charge or first-period charge as quote line items.
3. Check subtotal, VAT, total, currency, PO number, and valid-until date.
4. Confirm the customer email is correct before sending or resending.

The quote must contain billable content before it can be sent. A PPM quote with no amount or no line items is blocked in the same way as other billable quote sends.

Open PPM Setup

1. Open the PPM quote detail.
2. Select PPM Setup.
3. Review the account warning if the quote is not linked to a CRM account.
4. Fill in contract terms and expected routines.
5. Select Save Terms.

PPM Setup is a route-backed setup surface, not a large quote modal. Use it for the contract and routine preparation, then return to the quote detail to send the quote or manage approval.

Fill in customer-safe contract terms

Complete the customer-facing terms before sending the quote:

Only customer-safe PPM fields are shown to the customer in the public approval page and quote PDF. Internal notes, margins, and private admin context must stay out of customer-facing text fields.

Add expected routines

Add at least one expected routine before sending the quote.

1. In Expected Routines, enter a routine name.
2. Choose the frequency.
3. Choose the scope: Account, Site, System, or Asset.
4. Set the inspection type for inspection routines.
5. Set an anchor date or next due date.
6. Add the customer description that should appear in customer-safe output.
7. Add more routines when the agreement has multiple recurring commitments.
8. Save the terms.

Use account-scoped routines for account-level contracts. Use site, system, or asset scope only when the recurring work must point at a specific site, system, or asset.

Send for approval

1. Return to the quote detail.
2. Select Send for Approval.
3. Enter or confirm the invite email.
4. Choose the expiry window.
5. Create the approval link.

Deucalion blocks approval-link generation until the PPM quote has the required account, contract terms, and at least one valid expected routine. Fix the readiness message in PPM Setup, save, then send again.

The approval link is stored so admins can retrieve and copy the active link later. Raw approval tokens are not displayed separately from the copyable approval URL.

Copy the active approval link

1. Open the quote detail.
2. Find the Approval Workflow panel.
3. Use Copy when the latest active grant shows a copyable link.
4. Paste the link into the customer email thread or CRM note only when that is part of your process.

Copying the link does not create a second active approval link. It uses the currently active grant when the grant is still usable.

Resend the quote

1. Open the quote detail.
2. Confirm the customer email, line items, and PPM setup are still correct.
3. Select Resend Quote.
4. Check the approval events after the action completes.

Resend sends the current quote PDF and the approval link together. If there is already a usable active approval link, Deucalion reuses it and revokes duplicate active grants. If no usable active link exists, it creates a replacement link.

If email delivery fails, the failure is recorded in approval events and the active approval link remains available for copy or another resend. The link is not lost because an email provider rejected or skipped the message.

What the customer sees

The customer-facing approval output includes:

1. Quote identity, customer context, line items, totals, and validity.
2. Customer-safe contract name, dates, renewal notice, scope, schedule, exclusions, and billing terms.
3. Customer-safe routine summary, including routine name, scope type, service line, work type, frequency, and customer description.

The customer-facing output does not include internal notes, internal handoff errors, private margins, raw approval tokens, or unrelated account data.

After customer acceptance

When the customer accepts the PPM quote:

1. The quote becomes accepted.
2. Deucalion creates or reuses one active service contract from the quote.
3. The expected routines are created under that service contract.
4. The quote detail shows the generated service contract and routine links.
5. The CRM account contract summary is updated from the generated service contract.
6. A customer contract acknowledgement email is queued after the contract transaction commits.

Acknowledgement dispatch is asynchronous. A provider failure does not roll back the committed service contract or routines. Delivery intent and outcome are persisted for reconciliation, and the idempotent workflow prevents a successful acknowledgement from being sent again when an admin retries the handoff.

Retry a failed handoff

If acceptance succeeds but service contract handoff fails, the quote detail keeps the failure visible.

1. Open the accepted PPM quote.
2. Read the service contract handoff message.
3. Fix the missing account, invalid routine reference, or incomplete PPM setup.
4. Select Create Service Contract.
5. Recheck the linked service contract and routines.

Manual retry is safe to use. If the service contract already exists for the quote, Deucalion reuses it instead of creating a duplicate contract or duplicate routines.

Check the routine plan

1. Open the generated service contract from the quote detail.
2. Review contract dates, renewal notice days, owner, and status.
3. Open each generated routine.
4. Confirm scope, frequency, anchor or next due date, duration, crew size, and field-resource assumptions.
5. Use the routine planning workflow to preview and generate future visits when the work is ready to schedule.

The quote acceptance step creates the maintenance commitment. Routine generation still belongs in the routine planning and Scheduler workflow so planners can review dates, capacity, and assignments before visits are dispatched.

Renewal-window notifications

Service contracts can send internal renewal-window notifications when the contract is inside its notice window.

The notification is preference-gated. Users only receive the internal prompt when their notification preferences allow the service contract renewal-window event.

The notification is deduped by recipient, contract, and window. A user should not receive repeated prompts for the same contract renewal window because the reminder job runs more than once.

Billing boundary

Do not expect the accepted PPM quote or generated service contract to appear in Finance → Ready to Invoice.

The current product intentionally produces no PPM contract candidate until a recurring charge has a canonical occurrence with its own period, due date, amount, and invoice identity. This prevents the whole agreement value from being presented as though it were one recurring visit charge.

When billing must be recorded before that occurrence model is available, make a deliberate manual invoice decision using the agreed terms and account context. Do not infer a recurring amount from the accepted quote candidate queue.

Troubleshooting

Related guides

1. Use Client Handover and Quote Approval for approval links, manual decisions, reminders, and handover context.
2. Use Routine Contracts and Maintenance Planning for service contract and routine planning after quote acceptance.
3. Use Billing Candidates and Accounting Export Availability for ready-to-invoice work, duplicate prevention, and the current export boundary.