MSP CRM records and migration exploration
Status: exploratory CRM implementation for the Sharps and Success Works Commercial Services. Commercial Service is the unified commercial record for MSP, Tech Projects and Hardware. Existing MSP Plans provide the main configuration basis and remain in use for operational continuity.
The agreed direction is to track invoices and their actual lines, linked to Products, service periods and the configured charges behind them. Invoice records provide the document history; their lines provide the commercial reference for a service month. Exact CRM structures develop against Sharps and Success Works. This slice reconciles existing invoices without generating new invoices.
The immediate review is Success Works, September 2026: use the current Managed Services Plan configuration to build the invoice lines and show them under its Commercial Service. Agreement reconciliation and commercial summaries are not prerequisites for this record exercise.
Purpose and scope
Prepare the CRM structure and concrete records needed to represent the selected MSP agreements, their configured charges and their generated invoice lines. Start with a candidate's real records, propose a small change, and check that it also fits the other MSP candidate before treating it as a shared rule.
| Candidate | Use case | Place in the exploration |
|---|---|---|
| Sharps | MSP, including its relationship with audit/onboarding | Follow the Success Works line walkthrough |
| Success Works | MSP renewal with support, infrastructure, website maintenance, devices and separate licences | First concrete review: September invoice lines from current Plan configuration |
| Cercle | Recurring Tech Project | Later |
| Gidget Phase 5 | One-time Tech Project | Later |
| ARACY | Hardware | Later |
Only the two MSP cases enter the current record and migration preparation. Their agreement and invoice evidence determines the periods to inspect; there is no inherited July/August batch or all-customer history requirement. Dashboard, render and forecast-screen designs impose no requirements on this exploration. The existing CRM inventory identifies source records and installed structures to inspect.
Configuration basis and implementation state
The record to configure and review is Commercial Service. For an MSP with an existing Managed Services Plan, start from that Plan and its linked records. Reuse the existing service identity and Plan lookup; a renewal does not require another service solely because its Deal or prices change. MSPs without a Plan need an evidenced source mapping, not a fabricated operational Plan.
| Plan source | Use in the Commercial Service configuration |
|---|---|
| Name and Account | Seed service identity and Company; verify the existing service belongs to that Plan/customer |
| Plan status | Establish the initial MSP lifecycle from operational status; retain service-specific evidence and unresolved dates |
| Original Deal and current-agreement references | Preserve the original relationship and identify the current agreement separately |
| Billing dates | Record operational eligibility evidence; do not substitute these for contract commencement, renewal or service closure |
| Plan type, configured MSP Invoice Lines and their Products | Explain the current billing setup through the linked Plan; inspect the actual charge rows before defining commercial components |
| MSP Seats and eligibility dates | Explain the operational quantity rules; generated invoice lines retain each period's billed quantities |
| Delivery scope and support budget | Seed delivery references and provisional budget evidence; keep customer entitlement and reviewed internal effort separate |
| Generated invoices | Trace individual lines to the service, Product and evidenced coverage period |
The Plan remains the operational source for billing, Seats and configured MSP Invoice Lines. Shared commercial information belongs on the Commercial Service or its linked commercial records. Migration starts from the Plan configuration and supplements it with accepted agreement and invoice evidence. Differences remain explicit; there is no implied billing cutover or automatic two-way sync.
On 8 September 2026, the existing invoice generator was evaluated using Success
Works' current Plan, configured charges, Products and eligible Seats. Its eight
September lines matched the Products, quantities, unit prices and net amounts
on the existing invoice INV-0319. Eight Service_Invoice_Lines records now
link that invoice to the existing Commercial Service, with coverage from
1 to 30 September 2026 and source configured-charge references in their evidence.
Readback verified every prepared field. The existing invoice was reused;
financial values and operational Plan/charge inputs were preserved.
Success Works now has 22 captured lines, including these eight September rows.
Their Reviewed attribution records the verified source mapping and match to
current configuration. Earlier captured lines retain their existing review
states; agreement compliance is a separate question. Sharps retains 21 lines.
Actual Invoice Lines is the first related list after Notes. It shows the invoice, Product, quantity, unit/net amount, source currency, coverage dates and attribution state. This line list is the review artifact. The native record header shows Company, linked Plan, Business Category, Lifecycle and Currency. Success Works' Commercial Summary was cleared and removed from the shared header. Existing current-agreement fields remain source context; no summary or Service Terms record is required to build the lines.
The Plan module also has four populated current-agreement fields for these candidates. They provide source context for the commercial configuration; their existence does not replace implementation on Commercial Service. See the implemented Current Agreement rules and migration command. The accepted Sharps commencement differs from its operational billing start; that discrepancy remains for review without changing billing eligibility.
Agreed direction
An MSP agreement has a stable service identity and configured charges used for billing. Generating an invoice produces the individual period charges. Those invoice lines identify the Product, service and coverage period and preserve the generated quantities and financial values.
A service month is the set of relevant invoice and credit lines for a service and month, within a currency. It does not require its own CRM parent record. The invoice is already the document containing each line. Multiple documents can contribute to the same service month; an invoice can contain lines for different services or coverage periods.
| Responsibility | Starting representation |
|---|---|
| Customer commitment | Commercial Service linked to the customer, operational MSP Plan and relevant Deal/agreement evidence |
| Initial MSP configuration | Existing MSP Plan and linked operational records, supplemented by accepted agreement evidence and explicit discrepancies |
| Charges to generate | Existing MSP charge configuration and dated seat eligibility; inspect before proposing replacements or additional records |
| Invoice history | Existing CRM Invoice linked to its source document, with invoice date, customer, currency, status and totals |
| Charge for an invoiced period | Generated invoice line linked to its invoice, Product, Commercial Service and service period |
| Service month | Grouping of those lines by service and evidenced coverage; draft and issued amounts remain distinguishable |
| Delivery | Budget and recorded work linked through the service, delivery scope and dates |
These responsibilities do not prescribe new modules. In particular,
Service_Charge_Lines, a Service Month header, monthly snapshot children and a
separate snapshot-approval workflow are not prerequisites. Add a structure only
when a candidate demonstrates information or an action the existing records
cannot reasonably support.
Invoice history and reconciliation
The intended relationship is Invoice → actual invoice lines → configured MSP Invoice Line. Each actual line also links to its Product and Commercial Service. One configured charge can explain many actual lines across successive invoices. The existing Managed Services Plan retains the MSP charge configuration and operational billing rules.
Reuse the native CRM Invoices module as the document record. Reconcile an existing CRM invoice to its source invoice, or capture a historical invoice that is missing from CRM. Capturing history does not generate, issue or resend an invoice. Keep a stable source document identifier to avoid duplicate invoice records, and stable source line identifiers to avoid duplicate lines.
| Record | Information and relationship |
|---|---|
| Invoice | Source invoice ID and number, customer, invoice and due dates, currency, source status, subtotal, tax and total; source payment information when available |
| Actual invoice line | Parent Invoice, Commercial Service, Product, billed description, quantity, price, discount and amounts, and service-period dates |
| Configured MSP Invoice Line | The reusable charge on the operational Plan; a lookup from the actual line explains which configured charge it corresponds to |
The CRM_Invoice lookup on Service_Invoice_Lines links captured lines to native
invoices. Configured_MSP_Invoice_Line links them to their configured charges.
Both relationships are populated on all eight September Success Works lines
and verified by readback. The original matching evidence remains on the lines.
The charge-link command
applies explicit mappings while preserving billed values and operational inputs.
Reconcile historical lines using available Plan, Product and charge evidence. A historical match identifies the corresponding configured charge; it does not require the old quantity or price to equal today's configuration. Preserve the invoice's billed values. Leave an ambiguous charge match unassigned and visible for review without excluding the invoice from history. Do not force several possible charges into a single match based only on Product.
Invoice records support reporting by invoice date, customer, currency and document status over time. Service and Product breakdowns use the linked line amounts; service-month reporting uses line coverage dates. Count each invoice's header total once, rather than once per joined line, and reconcile captured line totals to the document. Retain credit and void status so reports can distinguish billed amounts from drafts, reversals and payments.
The Success Works candidate exposes INV-0319 and its eight September lines from
the invoice record, including their configured-charge relationships. Its native
invoice header retains the operational Created / Drafted markers, while the
captured source document is AUTHORISED. Source status and payment information
must be reconciled before those header fields support historical status reports.
Next steps, in order:
- Reconcile Success Works' existing July and August invoices and line-to-charge mappings, retaining historical quantities, prices and unresolved coverage.
- Reconcile source invoice status, credits and available payment information onto invoice records using a defined source-status mapping.
- Apply the same invoice/line/charge model to Sharps.
- Build a native CRM history report across the reconciled invoices, with invoice-date totals and line-based service/Product breakdowns. Keep service-month reporting based on coverage dates.
Invoice generation remains outside this slice. Ongoing synchronisation can be designed after the selected historical records have been reviewed.
Information to carry on invoice lines
This checklist defines line meanings. The first candidate review uses the
installed Service_Invoice_Lines representation linked to native CRM invoices.
Check actual metadata and generator behaviour before extending that mapping.
| Information | Required meaning |
|---|---|
| Invoice/document reference and stable source-line identity | Trace the row to its CRM invoice and Xero document/line where available; distinguish invoice and credit evidence |
| Commercial Service | Own the line at service level; a shared customer or invoice header alone cannot assign every line |
| Product | Identify the reviewed CRM Product sold on an ordinary charge; retain the source code and the basis of the match |
| Description, quantity, unit price, discount, net/tax amounts and currency | Preserve the line values for that document, independently of current Product defaults |
| Service-period start/end | Identify coverage independently of invoice date; a simple monthly line can derive its month from these dates |
| Source configured charge, where available | Link to the configured MSP Invoice Line the actual line corresponds to; retain the match basis without treating a historical reconciliation as proof of generation provenance |
| Status and review evidence | Distinguish draft, issued, credited or voided evidence, and record unresolved Product, service or period assignments |
Product lookup is an identity link. Later catalogue price or description changes
must not replace values on an issued line. A generic Xero item code such as
003 does not establish Product identity. Discounts, credits and informational
rows retain their source values; do not invent a Product merely to make
historical capture pass validation.
For a normal MSP invoice whose lines all cover one month, its billing-period fields can supply proposed line coverage. Confirm that inheritance against the candidate. Catch-up charges and transition items require their own evidence. If a line spans periods, retain it once and design an explicit allocation only when the case requires a monthly split. Allocations must conserve its amount; do not repeat the full amount in each month.
Agreement, billing and delivery boundaries
The accepted agreement and confirmed amendments explain what was agreed. Configured MSP charges explain what the generator is instructed to produce. Issued invoice lines establish what was billed. Keep all three traceable when they disagree. A generated invoice does not automatically amend the agreement, and migration must not rewrite issued financial values to make them match it.
Draft invoices can be regenerated under the operational billing rules. The current generator can replace CRM subform rows during a draft refresh, so a row-position key or an assumption that every CRM row ID survives is insufficient. Inspect how Product, service and period links survive that refresh and how final CRM and Xero lines are matched. Credits and voids retain their source relationships without counting the original amount twice.
A month without an invoice has no generated billed lines. It is not proof that the service was free or inactive. The agreement can still identify an expected charge or a missing invoice; that observation does not require a monthly wrapper. Future forecasting and independent expected-month snapshots are outside this preparation.
Customer support entitlements, billed seats/devices and internal effort budgets are different quantities. Delivery scope and work dates connect effort to the service period. Several invoice Products may fund the same support effort; count that work once rather than attaching its full cost to each charge. Keep separately billed licence costs identifiable. Missing costs and unsupported historical budgets remain unknown, and private staff rates stay outside CRM.
Candidate walkthroughs
Sharps
Start from MSP Plan 42659000014776835, its existing Commercial Service,
configured MSP charges, seat records and generated invoices. The retained CRM
capture also contains a linked audit/onboarding Deal and agreement reference.
Confirm the accepted scope before deciding how onboarding relates to recurring
support; a Deal title alone does not prove a separately sold commitment.
Prepare one fully traced monthly invoice first. For each line, record its current Product, financial values, source charge, proposed service and period. Then inspect a second period or actual amendment to test changing quantities or composition. Include onboarding evidence to resolve its boundary with the recurring service; other Sharps sales are outside this MSP preparation.
Establish whether the existing line representation can hold the required links, which Products or periods are unresolved, and how generated rows can remain traceable after draft refresh.
Success Works
Start from MSP Plan 42659000014765116, renewed Deal 42659000013083305 and
the reviewed agreement commencing 15 May 2026. The private agreement review
establishes the selected accepted Qwilr page as the commercial authority where
its attached schedule conflicts. Preserve that resolved source precedence.
The selected support, infrastructure, website and device components form the agreement baseline. Separately billed Microsoft licences also belong in the invoice-line walkthrough. Unselected optional projects do not create charges or delivery budgets. Signed quantities establish a baseline, not every later month's quantities.
Use the retained June–September invoice capture to choose a simple period and then test the known exceptions: support tier/rate differences, infrastructure quantities, website and separate discounts, device Product/rate associations, and licence additions. Classify each as a representation question, a commercial decision or a possible billing correction. Do not resolve a disputed amount through the migration mapping itself. May transition coverage remains open.
The review includes current work in an older support Project and website scope. Use scope and work-date evidence to propose service ownership; the existence of a newer empty Project or an older reporting service does not settle it. Preserve older service history and avoid duplicate ownership of work or invoice lines.
Record and migration preparation
Start with the saved Success Works September lines, then apply the same approach to Sharps. Use the current Plan configuration and the existing generator as the basis for the chosen month. When that month's invoice already exists, compare the generated lines and capture the matching source lines instead of creating another invoice. Inspect retained evidence first and refresh only candidate records and metadata needed to resolve gaps. Captures are dated evidence, not proof of today's state.
- Map source records. Begin with the existing MSP Plan and follow its customer, original/current Deal, configured charges, Seats, Products, generated invoices and delivery scope. Match its existing Commercial Service before considering creation. Supplement the configuration with agreement evidence and keep operational inputs, agreed terms and generated facts distinguishable.
- Draft concrete target records. Show the existing record and proposed result for every required relationship or value. Prefer existing fields and line records where they fit. Explain what each proposed new field enables.
- Resolve line storage. Compare native invoice Product rows with the installed actual-line capture. Choose where operators maintain attribution and how a mirror, if needed, stays linked and read-only for source values. Avoid a second independently editable copy of the same financial line.
- Try the actual exceptions. Check changes between months, discounts, separate licences, onboarding boundaries and evidenced catch-up or credit cases. Keep unresolved decisions explicit rather than expanding the schema for hypothetical cases.
- Prepare a scoped migration manifest. List exact record/field changes, source evidence, dependencies, exclusions and validation. Identify any future billing-authority change separately from attribution or descriptive changes.
- Review the two cases together. Revise the shared structure where needed. Mark decisions as proposed, supported by a candidate, or agreed. Defer the Tech Project and Hardware walkthroughs until the MSP design is usable.
Use this record worksheet for each proposed change:
| Worksheet column | Content |
|---|---|
| Candidate and business purpose | The specific need this record/field serves |
| Existing module, record and source line | Exact identifiers, with document reference where applicable |
| Current value and proposed value | Concrete before/after values; unknowns remain explicit |
| Proposed action | Reuse, link, update, create, or defer; retirement needs a named replacement and dependency review |
| Evidence and effective period | Agreement, source record or invoice supporting the change |
| Decision state and unresolved question | What is established and what still needs review |
| Validation | Expected saved relationship/value, financial control or generator behaviour |
The preparation package contains a field/relationship proposal, populated worksheets for both candidates, an invoice-line crosswalk, and a migration manifest with an exception list. Detailed customer terms, prices, raw exports and proposed payloads belong in the private working directory; committed documentation records the structure and decisions.
Further changes are ready for record implementation when both cases can be explained using the proposed structure, each migration action has a source and target, and blocking questions are visible. Validate source-line uniqueness, Product/service/period assignments, amount conservation and draft-refresh behaviour as applicable. Repeated migration must not duplicate lines or silently overwrite intervening human edits. No dashboard or monthly parent record is required to review this package.
Evidence and next working session
Private sources in this checkout:
.local/commercial-services/preparation-20260907/sources.json: captured Plans, Seats, configured charges, Products and invoice evidence, including Sharps..local/commercial-services/position-plan-20260907/crm-evidence.json: service, Deal, SOW and delivery references, including Sharps audit/onboarding..local/commercial-services/success-works-20260907/REVIEW.mdandcontract-review.json: agreement decisions, source IDs and reconciliation. Associatedcrm-live.json,xero-live.jsonandwork-live.jsonretain the captured records..local/commercial-services/implementation-20260907/and.local/commercial-services/position-implementation-20260907/: applied-record journals and readback for existing service structures..local/commercial-services/msp-foundation-20260908/: current candidate Commercial Services, linked Plans, field metadata and related-record capture..local/commercial-services/msp-review-20260908/: applied candidate source, decisions, exact preview, write journal and readback for two services and 35 captured invoice lines..local/commercial-services/success-works-lines-20260908/: current Plan inputs, generated September lines, matching invoice, eight line payloads, write journal and verified readback..local/commercial-services/invoice-charge-links-20260908/: refreshed source records, eight reviewed charge mappings, exact lookup preview and verified application journal.
Review Success Works' eight September Actual Invoice Lines directly in its Commercial Service or native Invoice: Products, configured charges, quantities, prices and coverage. Follow the invoice-history steps above. Any billing correction requires its own evidence and operational change. Future invoice generation, draft refresh and ongoing attribution are subsequent implementation work; the candidate migration does not synchronise them automatically. Saved preview schemas and render outputs are not the starting target records.