diff --git a/CHANGELOG.md b/CHANGELOG.md index ea16897b2..376af64b1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -233,6 +233,7 @@ Update from Maintenance > Update — Queue Update hands the job to cron, which u - Counts: the counts in menus, tabs, list headers and under every list - Showing 1 to 25 of 1,834 records - have a thousands separator, as the dashboard, reports and audit log already did. - Confirmations: archiving a credential from an asset, contact, vendor, service or license page no longer asks first, as archiving anywhere else doesn't - the message's Undo puts it back. Taking a related ticket off a ticket, or a ticket off a service's page, asks first, as the ticket page's other × buttons do. Hints under a few fields - a statement's From, a cron job's schedule, a quote's price per hour - look like every other field's. - Required fields: every field marked * has to be filled in before the window saves, and every field that has to be filled in is marked * - a few had one without the other, such as a credit's note, the comment when merging several tickets, the dates when activating, renewing or ending a contract, and the one choice in the windows that set a location, contact, status or referral on the ticked records. Hints under fields look the same in every window. +- Starter content for the Knowledge Base: a Knowledge Base Articles pack of 29 how-tos and fixes for your clients' staff - passwords and MFA, phishing, Outlook, OneDrive, the VPN, printers, Teams, Wi-Fi, new starters and leavers - each under its category with tags, and reviewed once a year. They come in as drafts only your team can see, ending with how to reach you from Company Details: read each, make it say what your clients use, then publish it to the clients it suits. The Categories pack has twelve Knowledge Base categories and the Tags pack ten article tags. The demo data has a Knowledge Base of its own - articles for every client, by client tag, for one client and for anyone, ones for your team only and drafts - with reads, feedback, earlier versions, one due for review, searches that found nothing and links to them in ticket replies. ### Bug Fixes @@ -474,6 +475,7 @@ Update from Maintenance > Update — Queue Update hands the job to cron, which u - Audit log types: database 4.1.0 renames `logs.log_type` Software, Software Template, Revenue and Account Transfer to License, License Template, Income and Transfer (`agent/post/transfer.php` and `functions/income_import.php` now match the API's Transfer). `auditLogKinds()` has those keys, drops Revenue and adds Database, Demo, Undo and RMM Provider; `auditLogActionStyle()` adds Bulk Link, Offboard, Repair, Reset and Sync. The `log` of the license kind in `archivedKinds()`, `importKinds()` and the tag kinds is License, and `linkLogSide()` (`functions/links.php`) names its type from the `LINK_ENTITIES` label and returns which side it is. - Guest pages: `guestDeadEndHtml($icon, $title, $text)` in `guest/includes/inc_all_guest.php` is the page a guest link ends on - the bad-link pages of the invoice, quote, contract and task approval links, and the Stripe pages' dead ends (`WORDING_PAYMENT_FAILED` is gone). `guest/guest_post.php` uses `'error'` and `'info'` rather than `'danger'`. The task approval handlers in `guest/guest_post.php` and `client/post.php` check the approval exists before reading it. - Icon-only buttons: each `btn-close` that closes a window has `aria-label="Close"`, each split-button caret `aria-label="More actions"`, and each ⋮ menu button `title="More actions"`. +- Starter content: the `kb_articles` pack - `starterContentKbArticles()`, `starterLoadKbArticles()` (through `kbArticleSave()`, as drafts for agents only), `starterUpdateKbArticles()` (`update_starter_kb_articles` in `admin/post/starter_content.php`; an article whose words change keeps a version, one that already matches is left alone), `starterKbFields()`, `starterKbTags()` and `starterKbFill()` (`[Portal]` and `[Contact us]` from `billingCompany()`, `config_ticket_from_email` and the portal switch). `kb` categories in `starterContentCategories()` and tag type 13 in `starterContentTags()`; a starter article counts as used once it is published, read, reviewed, reworded or has feedback. Demo data: `demoDataKbArticles()`, `demoBuildKnowledgeBase()` (after the clients, and on a load that adds no clients - who can read each, `kb_article_versions`, `kb_article_feedback`, `kb_search_misses` and a reply linking the article on the demo tickets it answers), `demoKbCategoryId()`, `demoKbArticleIds()` (title and summary, removed through `kbArticleDelete()`) and `demoKbSearchMisses()`. Removal also clears the demo clients' search misses and feedback, and `ticket_reads` on the demo tickets. ## [26.11.8] diff --git a/ITFlow_Migration_Plan.md b/ITFlow_Migration_Plan.md new file mode 100644 index 000000000..18a2ec52f --- /dev/null +++ b/ITFlow_Migration_Plan.md @@ -0,0 +1,438 @@ +# ConnectWise PSA (on-prem) → ITFlow Migration Plan + +Prepared for Ameer · Updated 2026-11-19 · Real schema confirmed via direct database discovery, cross-checked against ITFlow's own support team's migration guidance + +## 1. Status + +This plan now uses your actual ConnectWise on-prem SQL Server table and column names, confirmed through twenty-five rounds of discovery queries run directly against your database (not the REST API guesses the first draft used) — plus a real cross-check against migration guidance sent directly by ITFlow support (Marcus), which caught several things the schema alone didn't make obvious. `etl_skeleton.py` now has real, working code for every core entity: clients, vendors, locations, contacts, assets, asset↔ticket links, contracts, tickets, ticket replies/time, invoices (including both product and time-based line items, with a fully confirmed billing rate), payments, credits, and quotes (hybrid model — see Section 2). Three stubs remain, all lower-priority scope not yet started: `migrate_attachments()` and the two custom-field functions. + +**One fix from an earlier round is worth flagging specifically**: `tickets.ticket_created_by` is a required (`NOT NULL`) column with no default in ITFlow's schema, and it was missing from the ticket INSERT entirely — under MySQL/MariaDB's default strict SQL mode, that's not a soft gap, it's a hard error on every single ticket row. That's now fixed (defaults to `0`, "system", confirmed acceptable by ITFlow support). + +**A second, unrelated fix is worth flagging just as clearly**: every `migrate_*` function had a crash-safety gap in how it used the local SQLite id-map (`migration_id_map`), the thing every stage relies on to know what's already been migrated and to resolve foreign keys across stages. `record_mapping()` was committing each mapping to SQLite immediately, per row, while the actual ITFlow insert for that same row wasn't committed to MySQL until the *end* of the whole stage. If the script had died, lost a connection, or been killed partway through a stage — after some rows' mappings were already committed to SQLite but before that stage's final ITFlow commit — those rows' mappings would durably say "already migrated" even though ITFlow never actually received them. Re-running the stage would then silently skip them forever (`already_migrated()` finds the mapping, skips the row) with no error raised — permanent, silent data loss for exactly the rows unlucky enough to be mid-flight when something went wrong. Fixed by removing `record_mapping()`'s own commit and committing the id-map right alongside each stage's real `itflow_conn.commit()` instead, so both databases' "this really happened" boundary lines up. See item 24 in Section 6. + +A handful of smaller items are still open — called out inline in the relevant section below and tracked in Section 6, not buried in a caveat at the top. Two external factors also shape how this runs: the Proactive board is being deleted from ConnectWise before migration (not just filtered out by the script), and invoice history is split across two migrations — Sage for older invoices (your own script, runs first) and this script for ConnectWise invoices, migrating with their original numbers/prefix unchanged (see Section 6, item 9, for the collision risk that creates). The script now runs in 11 checkable stages rather than as one long migration — see Section 4 for the full breakdown and CLI usage — and reads its DB credentials from environment variables rather than the file itself, since it's now close to running on a real server (Section 7 covers where and how). + +## 2. Scope — updated based on real data + +- Clients, sites, contacts +- Assets (ConnectWise "Configurations") +- **Service tickets — Reactive board only.** Your ConnectWise instance has 248,829 total ticket-like records, but 240,354 of those (96.6%) are on the "Managed Service - Proactive Alerts" board — automated noise, per your call to exclude it. The "Managed Service - Reactive" board has 8,475 tickets, which is what actually migrates. A third board, "Projects," has zero tickets and can be ignored. +- Ticket notes/discussion and time entries, scoped to the same Reactive-board ticket set +- Agreements/contracts (103 of them) +- Invoices. Originally scoped at 1,695 total; round 25 (Nov 2026) found 1,742 real (non-credit-memo) `Billing_Log` rows (1,301 Agreement-type + 441 Standard-type) — the difference is just new invoices created in ConnectWise in the months since the original count, not a discrepancy to chase. +- **Payments — implemented, sourced from `Billing_Application` (real per-invoice payment applications, covering both full and partial payments — see Section 5.9a).** ITFlow support's own migration guidance was explicit that a "Paid" invoice status should be backed by a real `payments` row for accounting to reconcile, not just a status label. +- **Credits — implemented and confirmed with real numbers (round 25).** ConnectWise credit memos (`Billing_Type_ID='C'`) are not real invoices (your call) — they migrate into ITFlow's dedicated `credits` table instead, linked to the invoice(s) they were applied against. See Section 5.9b. +- ~~Knowledge base articles~~ — **dropped from scope.** The `KB_Resolution` table has zero rows; there's no knowledge base content in this instance. +- Vendors +- Attachments/documents +- Custom fields +- **Quotes — confirmed and implemented.** ITFlow has `quotes`/`quote_items`, structured almost identically to invoices. Round 15 came back with an entire module (`SO_` = **Sales Opportunity**, not "Sales Order" as first guessed) — ConnectWise's full sales/CRM/pipeline system: `SO_Opportunity`, `SO_Pipeline`, `SO_Status`, `SO_Type`, `SO_Probability`, sales team/activity tracking, and reporting views. **Business question resolved: you confirmed the Opportunity record itself is what you call "the quote"** — no separate object gets created once a deal is won. + + Round 16 turned up two more findings. First, a dead end reported honestly: `v_api_collection_system_quote_link` / `v_ML_QuoteLinks` are not quote records at all — just admin config for an external quote-tool integration URL (`System_Screens` where `screen_id = 'quote_integration'`), a naming coincidence like `CS_Survey` before it. Second, a real find: `v_api_collection_sales_order`'s definition reveals **`Order_Header`**, a table round 15's search completely missed (its name doesn't contain "sales," "opportunity," "quote," or "SO_"). This is ConnectWise's actual formal "Sales Order" object — its own status, totals, tax, ship-to/bill-to addresses, and its own line items via `IV_Product` (same pattern as invoice line items) — with only an *optional* link to `SO_Opportunity`. + + Round 17 confirmed the real usage split: 334 `Order_Header` rows total, 230 of them linked to an opportunity (out of 384 opportunities) — so roughly 60% of quotes have progressed to formal pricing, 40% haven't. That's not a data gap; you confirmed it directly by checking a real example ("Truline Bitwarden") in the ConnectWise UI — it's simply an open deal awaiting a decision, not priced yet. **Design confirmed: the hybrid model.** Every `SO_Opportunity` migrates as a quote (full coverage, ~384 rows); the ~230 with a linked `Order_Header` get a real `quote_amount` (from `Order_Header.Total`) and real `quote_items` (from `IV_Product`, filtered by `Order_Header_RecID` — the exact same pattern already used for invoice product line items); the rest migrate as unpriced quote headers (`quote_amount = 0`, no line items), reflecting genuine business reality. Round 18 confirmed the status lookup table is `SO_Opp_Status` (not `SO_Status`, which was queried by mistake first) — `SO_Opp_Status_RecID` is `SO_Opportunity`'s real status FK. See Section 5.9c for the full confirmed mapping. **Implemented and working** in `etl_skeleton.py`'s `migrate_quotes()`. +- ~~ConnectWise Projects module~~ — **confirmed out of scope.** Not used day-to-day; the script never touches `PM_Project_RecID` or project-specific tables. + +## 3. Real table map + +| Business entity | Real ConnectWise table(s) | ITFlow table(s) | +|---|---|---| +| Clients | `Company` (excluding vendor-flagged) | `clients` | +| Sites/locations | `Company_Address` | `locations` | +| Vendors | `Company` (where vendor-flagged via `Company_Company_Type` → `Company_Type.Vendor_Flag`) | `vendors` | +| Contacts | `Contact` | `contacts` | +| Contact phone/email | `Contact_Communication` (+ `Communication_Type` lookup) | `contacts` (email/phone/mobile columns) | +| Assets | `Config` | `assets` | +| Contracts | `AGR_Header` (+ `AGR_Detail` for line items, `AGR_Type` for type) | `contracts` | +| Tickets | `SR_Service` (filtered to `SR_Board_RecID` = Reactive board) | `tickets` | +| Ticket notes | `SR_Detail` | `ticket_replies` | +| Time entries | `Time_Entry` | `ticket_replies` (merged with notes — see 5.7) | +| Invoices | `Billing_Log` (+ `Billing_Status`, `Billing_Type`, `Billing_Terms`, `Currency`), excluding credit memos (`Billing_Type_ID='C'`) | `invoices` | +| Invoice line items | `Time_Entry` rows where `Billing_Log_RecID` is set (time-based lines); products/expenses have their own equivalent tables, not yet confirmed | `invoice_items` | +| Payments | `Billing_Application` (`Payment_Type='P'`) | `payments`, posted to a single dedicated `accounts` row | +| Credits | `Billing_Log` credit memos (`Billing_Type_ID='C'`), linked via `Billing_Application.Credit_Memo_RecID` | `credits` | +| Quotes | `SO_Opportunity` (+ `SO_Opp_Status`, `Currency`), with pricing from `Order_Header` where linked | `quotes` | +| Quote line items | `IV_Product` rows where `Order_Header_RecID` is set (only present for the ~60% of opportunities with a linked, priced order) | `quote_items` | +| Attachments | `DM_Document` + `DM_Relationship` (polymorphic link table) | `files` / `documents` (see 5.10) | +| Technicians/users | `Member` | ITFlow users (needs your own mapping list) | +| Custom fields | Various `*_User_Defined_Field_Value` tables per entity | `custom_fields` / `custom_values` | + +This replaces the REST-API-name guesses from the first draft. A few important structural surprises worth knowing before writing the ETL script: + +- **Invoices aren't called "Invoice" anywhere** — they live in `Billing_Log`, ConnectWise's internal billing/GL module table. +- **Ticket notes and time-entry notes are two different physical tables that ConnectWise's own UI merges for display.** `SR_Detail` holds pure text notes; `Time_Entry` holds notes attached to logged time (`Notes`, `TE_Problem_Flag`, `TE_Resolution_Flag`, `TE_InternalAnalysis_Flag`). The `v_rpt_ServiceNote` view is literally a `UNION ALL` of both — confirms the plan's original instinct to merge them into one `ticket_replies` stream per ticket was right, just from two source tables instead of one. +- **A ticket's opening description isn't a column on the ticket.** `SR_Service` has no "initial description" field — it's the earliest `SR_Detail` row for that ticket (flagged `Problem_Flag`/`Issue_Flag`). Building ITFlow's `ticket_details` needs a join, not a column copy. +- **Company (client) records have no email or phone-on-the-client field at all** in either ConnectWise or ITFlow — phone lives on `Company_Address`/`locations`, email only exists at the contact level. Don't expect a `client_email` anywhere. + +## 4. Migration order, dependencies, and staged execution + +Unchanged in principle from the first draft, now with real tables: + +1. **Clients** ← `Company` (non-vendor) +2. **Locations** ← `Company_Address` +3. **Vendors** ← `Company` (vendor-flagged) +4. **Contacts** ← `Contact` + `Contact_Communication` +5. **Custom field definitions** (one-time setup per entity) +6. **Assets** ← `Config` +7. **Contracts** ← `AGR_Header` +8. **Tickets** ← `SR_Service` (Reactive board only) +9. **Ticket replies** ← `SR_Detail` + `Time_Entry` (merged, ticket-scoped) +10. **Invoices** ← `Billing_Log` (excluding credit memos — see #11a) +11. **Payments** ← `Billing_Application` (needs invoices' ID map) +11a. **Credits** ← `Billing_Log` credit memos (`Billing_Type_ID='C'`) (needs invoices' ID map) +12. **Quotes** ← `SO_Opportunity` (+ `Order_Header` where linked) +13. **Attachments** ← `DM_Document` + `DM_Relationship` +14. **Custom field values** (last — needs every other entity's ID map populated) + +**Your call: this runs in checkable stages, not all at once.** `etl_skeleton.py` now has a `--stage N` CLI flag — run one stage, go check the result directly in ITFlow, then run the next whenever you're satisfied, rather than one long migration you can only inspect at the very end. The same dependency order above is preserved, just grouped into 11 stages: + +| Stage | Contents | What to check in ITFlow before moving on | +|---|---|---| +| 1 | Members, clients, vendors, locations, contacts | Clients/vendors/contacts/locations look right; both technicians' tickets will attribute correctly | +| 2 | Custom field definitions | Not yet implemented — safe no-op | +| 3 | Assets | Assets attached to the right client/location/contact; `asset_type` blank as expected | +| 4 | Contracts | SLA response/resolution numbers look right after the 5-tier → 3-tier collapse | +| 5 | Attachments | Not yet implemented — safe no-op | +| 6 | Tickets, ticket replies/time, asset↔ticket links | ~8,475 Reactive-board tickets present; `ticket_priority` shows Low/Medium/High (ITFlow's confirmed vocabulary); replies show Internal/Public correctly. Needs stages 1 and 3 done first | +| 7 | Invoices | Totals match ConnectWise; line items correct; `invoice_status` shows Draft/Sent/Paid (ITFlow's confirmed vocabulary); no number collision with the Sage-migrated invoices; credit memos no longer appear here at all (see Stage 9) | +| 8 | Payments | A payment row exists for every invoice with real cash applied — full or partial — sourced from `Billing_Application`, posted to your one real `PAYMENT_ACCOUNT_NAME` account. Needs Stage 7 done first | +| 9 | Credits | One `credits` row per ConnectWise credit memo (11 total, confirmed round 25), linked to the invoice it was applied against where there's exactly one — 2 of the 11 were genuinely applied across 3 invoices each and correctly land unlinked with full detail in `credit_note` instead. Needs Stage 7 done first | +| 10 | Quotes | All ~384 opportunities show up as quotes; the ~230 with a linked Order_Header have real amounts/line items, the rest show 0.00 with none — expected, not a bug | +| 11 | Custom field values | Not yet implemented — safe no-op. Must run last regardless | + +Because every entity function already checks the `migration_id_map` SQLite database before inserting anything, stages are safe to run in completely separate sittings — nothing gets duplicated if you stop after Stage 1 today and come back to Stage 3 next week. Usage: + +``` +python etl_skeleton.py --list-stages # see every stage before running anything +python etl_skeleton.py --stage 1 # run just stage 1, then go check ITFlow +python etl_skeleton.py --stage 3 --stage 4 # run several stages in one invocation +python etl_skeleton.py --all # run every stage back to back, once you're confident +``` + +## 5. Entity-by-entity mapping (confirmed columns) + +### 5.1 Clients ← `Company` + +Excludes companies where `Company_Company_Type` → `Company_Type.Vendor_Flag = 1` (those go to 5.3 instead). + +| Real CW column | ITFlow column (`clients`) | Notes | +|---|---|---| +| `Company_Name` | `client_name` | | +| `Company_ID` | `client_abbreviation` | CW allows up to 50 chars, ITFlow's field is 10 — truncate | +| `Lead_Flag` | `client_lead` | Direct boolean | +| `Tax_ID` | `client_tax_id_number` | | +| `Website_URL` | `client_website` | | +| `Currency_RecID` → `Currency.Iso_Code` | `client_currency_code` | Join required | +| `Billing_Terms_RecID` → `Billing_Terms.Due_Days` | `client_net_terms` | Join required | +| `Date_Entered` | `client_created_at` | | +| `Delete_Flag` / `Date_Deleted` | `client_archived_at` | Set timestamp if deleted | +| — | `client_favorite` | No CW equivalent, default 0 | + +`Company.PhoneNbr` and `Company.PhoneNbr_Fax` exist but have no ITFlow home on `clients` (ITFlow keeps phone on `locations` only) — carry them onto the client's default `Company_Address` record instead of dropping them. + +### 5.2 Locations ← `Company_Address` + +| Real CW column | ITFlow column (`locations`) | Notes | +|---|---|---| +| `Description` | `location_name` | | +| `Address_Line1` + `Address_Line2` | `location_address` | Concatenate | +| `City` | `location_city` | | +| `State_ID` | `location_state` | | +| `Zip` | `location_zip` | | +| `PhoneNbr` + `PhoneNbrExt` | `location_phone` + `location_phone_extension` | | +| `PhoneNbr_Fax` | `location_fax` | | +| `Default_Flag` | `location_primary` | | +| `Inactive_Flag` | `location_archived_at` | Set timestamp if true | +| `Company_RecID` | `location_client_id` | Via ID map | +| `Country_RecID` | `location_country` | Needs a `Country` lookup join (not yet pulled — small table, low priority) | + +### 5.3 Vendors ← `Company` (vendor-flagged) + +Same source table as clients, filtered the other direction: `INNER JOIN Company_Company_Type ... INNER JOIN Company_Type ON Vendor_Flag = 1`. + +| Real CW column | ITFlow column (`vendors`) | +|---|---| +| `Company_Name` | `vendor_name` | +| `PhoneNbr` | `vendor_phone` | +| `Website_URL` | `vendor_website` | +| `Account_Nbr` | `vendor_account_number` | + +No company-level email exists on the CW side (see the structural note in Section 3) — `vendor_email` will need to come from that vendor's default contact's `Contact_Communication` row, if one exists, or stay blank. + +### 5.4 Contacts ← `Contact` + `Contact_Communication` + +| Real CW column | ITFlow column (`contacts`) | Notes | +|---|---|---| +| `First_Name` + `Last_Name` | `contact_name` | Concatenate | +| `Title` | `contact_title` | | +| `Default_Billing_Flag` | `contact_billing` | | +| `Default_Flag` | `contact_primary` | | +| `Company_RecID` | `contact_client_id` | Via ID map | +| `Company_Address_RecID` | `contact_location_id` | Via ID map | +| `Inactive_Flag` | `contact_archived_at` | Set timestamp if true | +| `Date_Entered` | `contact_created_at` | | + +Email/phone/mobile come from `Contact_Communication` joined to `Communication_Type` — real columns confirmed: `Communication_Type_RecID`, `Communication_Name`, `Phone_Flag`, `Fax_Flag`, `Email_Flag`, `Disabled`. Your org has 28 custom communication types (Email, Direct, Mobile, Fax, plus custom ones like "Customer Support Phone," "Personal Cellphone," etc. added in 2023), but they all carry the same consistent three-way flag pattern that buckets into phone-like / fax-like / email-like. Telling "mobile" apart from "regular phone" within the phone-flagged types isn't a separate flag — it's a naming convention on `Communication_Name` (`Mobile`, `Personal Cellphone`, `Work Cellphone`, `Shared Work Cellphone` match; everything else phone-flagged defaults to the regular phone field). Fax-flagged types have no ITFlow contact field to land in. **Implemented and working** in `etl_skeleton.py`'s `migrate_contacts()`. + +`contact_technical` (ITFlow's technical-contact flag) has no direct CW equivalent — closest is checking `Contact_Contact_Type` → `Contact_Type.Description` for a type name containing "technical," which is a text-matching heuristic, not a clean join. + +### 5.5 Assets ← `Config` + +| Real CW column | ITFlow column (`assets`) | Notes | +|---|---|---| +| `Config_Name` | `asset_name` | | +| `Model_Number` | `asset_model` | | +| `Serial_Number` | `asset_serial` | | +| `Os_Type` / `Os_Info` | `asset_os` | Combine | +| `Config_Status_RecID` → `Config_Status.Description` | `asset_status` | Join required | +| `Date_Purchased` | `asset_purchase_date` | | +| `Date_Installed` | `asset_install_date` | | +| `Date_Expiration` | `asset_warranty_expire` | Direct match — better than the first draft assumed, CW does track this natively | +| `Notes` | `asset_notes` | Append `IP_Address`/`MAC_Address` here too, since ITFlow has no dedicated columns for either | +| `Company_RecID` | `asset_client_id` | Via ID map | +| `Company_Address_RecID` | `asset_location_id` | Via ID map | +| `Contact_RecID` | `asset_contact_id` | Via ID map | +| `Manufacturer_RecID` | `asset_make` | Needs its lookup table confirmed (`Config` also has a separate `Mfg_Company_RecID` column — the two may be redundant/legacy, worth spot-checking a few real rows before picking one) | + +**Open item:** `Config` has no `Config_Type_RecID` column, and the obvious-looking `v_api_collection_company_configuration_type` view turned out to be a red herring — it's actually built from `dbo.CS_Survey` (a customer survey config, unrelated to asset device types), a naming coincidence. You've confirmed your team does categorize asset types in the ConnectWise UI, so it's tracked somewhere — most likely a custom field (`Config_User_Defined_Field_Value`) rather than a standard column. A follow-up discovery round is checking that table plus `IV_Product` (which `Config.IV_Product_RecID` links to, in case type rides along with the linked inventory product's category). + +### 5.6 Contracts ← `AGR_Header` + +| Real CW column | ITFlow column (`contracts`) | Notes | +|---|---|---| +| `AGR_Name` | `contract_name` | | +| `AGR_Cancel_Flag` | `contract_status` | | +| `AGR_Type_RecID` → `AGR_Type.AGR_Type_Desc` | `contract_type` | Join required | +| `AGR_Date_Start` | `contract_start_date` | | +| `AGR_Date_End` / `AGR_NoEnd_Flag` | `contract_end_date` | | +| `Company_RecID` | `contract_client_id` | Via ID map — no site-level scoping needed, `AGR_Site` has zero rows in your instance | +| `AGR_InvDesc` / `AGR_Notes` | `contract_details` | Combine | +| `Billing_Terms_RecID` | `contract_net_terms` | | +| `SR_SLA_RecID` → `SR_SLAPriority` (per urgency tier) | `contract_sla_*_response_time` / `contract_sla_*_resolution_time` | CW's SLA targets are keyed per-urgency (5 tiers: Critical/High/Medium/Low/Do Not Respond) but ITFlow only has low/medium/high — needs an explicit tier-collapsing rule, not a clean 1:1 join | + +Agreement line items (`AGR_Detail`, 175 rows) don't map to a flat ITFlow contract field — as noted in the first draft, recurring billing structure would need to be rebuilt in ITFlow's `recurring_invoices`/`recurring_invoice_items` separately if it needs to keep working post-migration. + +### 5.7 Tickets ← `SR_Service` (Reactive board only) + +Filter: `WHERE SR_Board_RecID = ` (confirm exact value from your board query results — two boards exist, Reactive and Proactive Alerts; Reactive is the one to keep). + +| Real CW column | ITFlow column (`tickets`) | Notes | +|---|---|---| +| `Summary` | `ticket_subject` | | +| (earliest `SR_Detail` row, `Problem_Flag`/`Issue_Flag`) | `ticket_details` | Not a column — see structural note in Section 3 | +| `SR_Status_RecID` → `SR_Status.Description` | `ticket_status` | Join, then match by name to pre-created ITFlow `ticket_statuses` rows | +| `SR_Urgency_RecID` → `URGENCY_TO_TICKET_PRIORITY` | `ticket_priority` | **Fixed**: previously copied CW's raw urgency text ("Priority 1 - Critical" etc.) straight through. ITFlow support confirmed the app only expects exactly "Low"/"Medium"/"High" (Title Case) — now collapsed via the same RecID mapping already used for the SLA tier logic. "Do Not Respond" folds to Low (judgment call, same open item as before). | +| `SR_Type_RecID` / `SR_SubType_RecID` → their `Description` columns | `ticket_category` | Concatenate | +| `SR_Source_RecID` → `SR_Source.Description` | `ticket_source` | Join required. Real values never sampled — ITFlow's docs suggest Email/Client Portal/In-App/Project Template, but ITFlow support confirmed a custom migration value is fine, so this is cosmetic, not urgent | +| `Company_RecID` | `ticket_client_id` | Via ID map | +| `Contact_RecID` | `ticket_contact_id` | Via ID map | +| `Company_Address_RecID` | `ticket_location_id` | Via ID map | +| `Date_Entered` | `ticket_created_at` | | +| `Date_Closed` | `ticket_closed_at` | | +| `Date_Closed` | `ticket_resolved_at` | **Resolved (round 20):** `SR_Service`'s full column list is now confirmed, and CW simply has no separate resolved-vs-closed concept (`Date_Closed`/`Date_Closed_UTC`/`IsClosed_Flag` exist; nothing resolution-specific does). Set equal to `Date_Closed` — a judgment call (not every closed ticket was necessarily "resolved" in ITFlow's stricter sense), but avoids every migrated ticket looking permanently unresolved for ITFlow's resolution-SLA reporting | +| `Ticket_Owner_RecID` → `Member` | `ticket_assigned_to` | Via technician ID map — this, not `Assigned_By_RecID` or `Entered_By`, is the real "assigned tech" field | +| `Closed_By` → `Member.Member_ID` | `ticket_closed_by` | Note: `Closed_By` stores the Member_ID *code* (text), not the numeric RecID — join on the code, not an integer FK | +| `TimeBillable_Flag` / `BillSR_Flag` | `ticket_billable` | | +| — | `ticket_created_by` | **Critical fix**: `NOT NULL` in ITFlow's schema with no default, and previously missing from the INSERT entirely — under strict SQL mode this errors on every ticket. Now explicitly set to `0` ("system"), confirmed acceptable by ITFlow support | +| — | `ticket_url_key` | **Fixed**: nullable so it never errored, but ITFlow support confirmed it needs a random 200-character string for portal/share links. Now generated per ticket | +| CW's own `SR_Service_RecID` | `ticket_vendor_ticket_number` | A dedicated field ITFlow's guidance calls out for referencing a migrated system's original ticket number, alongside (not replacing) reusing that RecID as `ticket_number` itself | + +Asset linkage: `SR_Config` **confirmed** as the ticket↔configuration join table — its only content columns are `Config_RecID` and `SR_Service_RecID`, a clean many-to-many link. **Implemented and working** in `etl_skeleton.py`'s `migrate_tickets()` (ticket header) and `migrate_asset_ticket_links()` (the `SR_Config` join, run after both assets and tickets exist). `ticket_status` is resolved via a get-or-create helper that matches ITFlow's `ticket_statuses` by name and creates any that don't already exist, so this doesn't need a pre-seeded status list to run. The "Do Not Respond" priority decision (item 2 below) is still open — those tickets migrate like any other for now, priority folded to Low. + +### 5.8 Ticket replies ← `SR_Detail` + `Time_Entry` (merged) + +Two source tables feed one ITFlow `ticket_replies` stream per ticket, matching how ConnectWise's own `v_rpt_ServiceNote` view already unions them: + +| Source | Real CW column | ITFlow column (`ticket_replies`) | +|---|---|---| +| `SR_Detail` | `SR_Detail_Notes` / `SR_Detail_Notes_Markdown` | `ticket_reply` (prefer markdown version when present) | +| `SR_Detail` | `InternalAnalysis_Flag` | `ticket_reply_type` — **confirmed**: `1` = hidden from client (internal), everything else = public. Matches ConnectWise's standard client-portal behavior and your own description of how the team uses it. Written as exactly `"Internal"` / `"Public"` (Title Case) — an earlier version wrote lowercase `"internal"`/`"public"`, which ITFlow support's own example (`'Internal'`, `'Public'`, `'Client'`, quoted literally) implies wouldn't match | +| `SR_Detail` | `Member_RecID` | `ticket_reply_by` (via technician map) | +| `SR_Detail` | `Date_Created_UTC` | `ticket_reply_created_at` | +| `SR_Detail` | `SR_Service_RecID` | `ticket_reply_ticket_id` (via ID map) | +| — | `ticket_reply_time_worked` | Set to `'00:00:00'` for `SR_Detail`-sourced replies (no logged time). Nullable in the schema, but ITFlow support's guidance says this shouldn't be left null | +| `Time_Entry` | `Notes` | `ticket_reply` | +| `Time_Entry` | `TE_InternalAnalysis_Flag` | `ticket_reply_type` (same rule and same Title-Case fix as `SR_Detail`) | +| `Time_Entry` | `Hours_Actual` | `ticket_reply_time_worked` (convert decimal hours → MySQL `TIME`) | +| `Time_Entry` | `Member_RecID` | `ticket_reply_by` | +| `Time_Entry` | `Date_Entered_UTC` | `ticket_reply_created_at` | +| `Time_Entry` | `SR_Service_RecID` | `ticket_reply_ticket_id` | + +`Internal_Member_Flag` / `External_Source_Flag` turned out **not** to be the visibility mechanism — real sample data showed both flags set simultaneously on both technician notes and customer-submitted messages, which reads more like "who authored this / where did it originate" than a visibility toggle. `InternalAnalysis_Flag` is the confirmed answer for *visibility*. + +**Open item, from ITFlow support's guidance**: ITFlow actually supports a *third* `ticket_reply_type` value, `'Client'`, for replies the client themselves submitted — distinct from `'Public'` (an agent's client-facing reply). This migration currently only does the 2-way Internal/Public split; every non-internal reply lands as `'Public'`, whether it was written by a technician or by the client. `Internal_Member_Flag`/`External_Source_Flag` were ruled out as the *visibility* signal above, but never fully ruled out as an *authorship* signal — that's a different question, and worth a follow-up discovery round correlating those flags against replies known to have come from the client portal before attempting a 3-way split. Not attempted yet since it needs real data to confirm rather than guess. + +Both sources filter to the same Reactive-board ticket set via `SR_Service_RecID` — this is what shrinks `SR_Detail`'s raw 787,436 rows and `Time_Entry`'s 4,235 rows down to whatever's actually attached to the 8,475 Reactive tickets. **Implemented and working** in `etl_skeleton.py`'s `migrate_ticket_replies_and_time()`. + +**Note style: verbatim, by your choice.** A large share of `Time_Entry.Notes`/`Notes_Markdown` follow a rigid ConnectWise fill-in-the-blank template: `Time on Site: HH:MM - HH:MM`, `Total non-billable time: ...`, `Total billable time: ...`, the actual work narrative, then `Additional Notes:` / `Items still outstanding:` — almost always left as an empty placeholder (`N/a`, a typo'd `N\a`, `None`, or blank). Three options were laid out side by side against real pasted samples — verbatim (migrate the template exactly as ConnectWise stores it), light cleanup (drop the redundant time restatement and empty placeholder fields, keep everything else), and full restructure (strip all labels, reformat into bullets) — and **you preferred ConnectWise's own note style as-is**. `migrate_ticket_replies_and_time()` migrates both `SR_Detail` and `Time_Entry` notes verbatim, unmodified. A working, tested `clean_onsite_note_template()` function still exists in `etl_skeleton.py` (just not called) in case this preference changes later — it's documented inline as available but unused. + +Also fixed while evaluating this (kept regardless of the style decision, since it's a bug fix not a style choice): `Time_Entry`'s query now prefers `Notes_Markdown` over plain `Notes` (via `COALESCE`), matching what `SR_Detail` already did — this was an oversight in the original implementation. + +### 5.9 Invoices ← `Billing_Log` + +| Real CW column | ITFlow column (`invoices`) | Notes | +|---|---|---| +| `Invoice_Number` | `invoice_number` | | +| `Reference` (fallback: synthesized "ConnectWise Invoice #n") | `invoice_scope` | A real `invoices` column that had been completely unmapped; ITFlow support's guidance calls it "the invoice description" | +| `Billing_Status_RecID` → `BILLING_STATUS_TO_INVOICE_STATUS`, overridden to `Paid` if `Date_Paid` is set | `invoice_status` | See the callout below for why this changed | +| `Date_Invoice` | `invoice_date` | | +| `Date_Invoice` + `Billing_Terms.Due_Days` | `invoice_due` | CW computes due date rather than storing it — replicate the same `DATEADD` logic | +| `Invoice_Amount` | `invoice_amount` | | +| `Currency_RecID` → `Currency.Iso_Code` | `invoice_currency_code` | Join required | +| `Internal_Note` / `Top_Comment` / `Bottom_Comment` | `invoice_note` | Combine | +| — | `invoice_url_key` | Random 200-character string, per ITFlow support's guidance (portal/share links need it) | +| `Company_RecID` | `invoice_client_id` | Via ID map | + +1,742 real (non-credit-memo) invoices confirmed as of round 25 (Nov 2026) — full history, no cutoff needed. + +Line items: `Time_Entry` rows carry their own `Billing_Log_RecID` once invoiced — a billed time entry *is* a line item, not a separate row in a flat items table. **Products follow the identical pattern, confirmed**: `IV_Product` (despite the name, this is a transactional product/parts line-item table, not a catalog) has its own `Billing_Log_RecID` and `SR_Service_RecID` columns, plus `Quantity`, `Unit_Price`, `Unit_Cost`, `Description` — everything needed for `invoice_items`. Expenses almost certainly follow the same pattern in their own table (not yet confirmed, lower priority). + +**`invoice_status`.** An email from ITFlow support (Marcus) confirmed `invoice_status` only has four valid values: Draft, Sent, Paid, Cancelled — the code was previously copying `Billing_Status.Description` straight through, unvalidated against that vocabulary. Discovery round 19 then pulled `Billing_Status`'s real values for the first time: New, Approved, Review, Sent, Closed, Closed - Emailed, Closed - Mailed — a genuine invoice *workflow* state, not a payment state; none of them mean "Paid." `BILLING_STATUS_TO_INVOICE_STATUS` now maps "New"/"Review" → Draft and everything else → Sent (a judgment call — these are historical, already-issued invoices, so defaulting to Sent is safer than Draft for the ambiguous middle statuses like "Approved"). Separately, and regardless of that mapping, `invoice_status` is forced to `"Paid"` whenever `Billing_Log.Date_Paid` is set — see Section 5.9a for why that's the real payment signal, and where the backing `payments` row comes from. + +**Implemented and working** in `etl_skeleton.py`'s `migrate_invoices()` — now excludes credit memos (`Billing_Type_ID='C'`, confirmed not real invoices, with real numbers confirmed round 25 — see Section 5.9b), including the `invoice_due` date-math replication (`Date_Invoice` + the client's `Billing_Terms.Due_Days`, joined via `Company` since `Billing_Log` doesn't carry its own terms), a get-or-create helper for `invoice_category_id` (ITFlow requires a non-null category with no default — a single "Migrated from ConnectWise" category is created and reused), and both product line items (from `IV_Product`) and time line items (from `Time_Entry`) with real quantity/price. Time_Entry's billing rate is now confirmed: `Hourly_Rate` (per-hour rate) × `Hours_Bill` (billed quantity — not always identical to `Hours_Actual`, CW rounds/adjusts some rows) is the line total, and `Extended_Invoice_Amount` is CW's own precomputed version of that same number — spot-checked against real rows and it matches exactly every time, so the script uses `Extended_Invoice_Amount` directly rather than recomputing, keeping migrated totals identical to what CW actually billed. + +### 5.9a Payments ← `Billing_Application` (Payment_Type='P') + +This whole entity exists because of a direct question you asked ("how are we going to mark invoices as paid") plus ITFlow support's own migration guidance, which was explicit: *"Invoices can be marked as paid directly, but the system expects a payment to be associated with the invoice for accounting to reconcile."* A status label alone isn't really what "Paid" is supposed to mean in ITFlow. + +**How we got to the real answer (rounds 19–24):** round 19 confirmed `Billing_Status` is a workflow state, not a payment state, and ruled out four other candidate tables (`EX_Payment`, `Payment_Sources`, `Portal_Payment_Processor*`, `WisePay_Payments` — lookup tables, gateway config, or genuinely 0 rows). That left `Billing_Log.Date_Paid` looking like the real signal — until round 21 checked for a partial-payment column on `Billing_Log` and found nothing, which you then directly contradicted ("There are some invoices with partial payments... visible in ConnectWise itself"). Round 22 ruled out "multiple `Billing_Log` rows per invoice." **Round 23 found the real mechanism, read straight out of ConnectWise's own view SQL** (`OBJECT_DEFINITION` on `v_rpt_AccountsReceivableAging` and `v_InvoiceSearch`), not inferred: both compute `Paid_Amount` from **`dbo.Billing_Application`**, a table no keyword search caught because it's named "Billing_Application," not "Payment." That round also proved `Billing_Log.Date_Paid` is only ever set once an invoice reaches a *zero* balance — every confirmed partial invoice found (e.g. Billing_Log_RecID 1754, Invoice 2783, paid 15.60 of 60.00) has `Date_Paid = NULL`. **Round 24 confirmed `Billing_Application`'s real shape** and closed out the design: `Billing_Log_RecID`, `Applied_Amount`, `Payment_Type` (`'P'` = 1,485 rows, `'C'` = 15 rows), `Date_Applied` (a real per-payment date), `Payment_Source_RecID` (present but every sampled row was `0` — not yet a usable payment-method signal). Critically, zero invoices have more than one `'P'` application row in this data, so one ITFlow `payments` row per invoice is correct. + +| Real CW column | ITFlow column (`payments`) | Notes | +|---|---|---| +| `SUM(Billing_Application.Applied_Amount) WHERE Payment_Type='P', GROUP BY Billing_Log_RecID` | `payment_amount` | The real cash amount actually applied — not `Invoice_Amount`. This is what fixes both the missing-partial-payments bug and the wrong-full-amount bug in one change | +| `MAX(Billing_Application.Date_Applied)` (same grouping), falling back to `Billing_Log.Date_Paid` | `payment_date` | Real per-payment date, not the invoice's own paid-in-full date | +| `Currency_RecID` → `Currency.Iso_Code` | `payment_currency_code` | Join required; falls back to `'GBP'` | +| — | `payment_method` | Still a placeholder — defaults to `'Bank Transfer'`. `Payment_Source_RecID` exists on `Billing_Application` but every sampled row was `0`; not a usable signal yet unless you actually track payment source day-to-day in ConnectWise | +| CW's own `Billing_Log_RecID` | `payment_reference` | For traceability | +| — | `payment_account_id` | **Your explicit call, overriding ITFlow support's suggested default:** posts to a single real `accounts` row — the one inbound bank account you actually reconcile both current and migrated invoices against. Set via `PAYMENT_ACCOUNT_NAME`, matched by exact name via `get_payment_account_id()`, which does **not** create the account if it's missing. **Action needed before Stage 8**: create/confirm that account exists in ITFlow (Finance > Accounts) | +| `Billing_Log_RecID` (via the invoice's own ID map) | `payment_invoice_id` | Requires Stage 7 (Invoices) to have already run | + +**Implemented and working** in `etl_skeleton.py`'s `migrate_payments()`, run as Stage 8, sourced directly from `Billing_Application` rather than gated on `Billing_Log.Date_Paid`. Two things worth knowing, both judgment calls rather than confirmed with you directly — flag if either should work differently: + +- **Credit-memo applications (`Payment_Type='C'`, 15 rows total) are deliberately NOT migrated as ITFlow `payments`.** A credit isn't cash that moved through `PAYMENT_ACCOUNT_NAME`'s real bank account, so including it would misstate that account's actual activity. Real example: Billing_Log_RecID 778 was paid in full through 485.20 cash + 110.00 credit — it migrates one `payments` row for 485.20 (the real cash), while `invoice_status` still correctly shows "Paid" (via `Date_Paid`, which does account for credits). +- **Credit-memo *invoices* themselves — `Billing_Log` rows with `Billing_Type_ID='C'` and a negative `Invoice_Amount`** — you confirmed directly these aren't real invoices. See Section 5.9b for the full resolution. + +### 5.9b Credits ← `Billing_Log` credit memos (`Billing_Type_ID='C'`) + +Credit memos (`Billing_Log` rows with `Billing_Type_ID='C'`, negative `Invoice_Amount`) are **not real invoices** — you confirmed this directly ("that is not an actual invoice") after an earlier version migrated them as regular negative-amount ITFlow invoices. Real example: Billing_Log_RecID 1149, "Parkway Derby LTD", `Invoice_Amount` −33,529.20, `Reference` "PWD001-2023-02CR". `migrate_invoices()` excludes them entirely (`WHERE Billing_Type_ID <> 'C'`). + +You also told us exactly where they should go instead: *"Credits follow the invoicing numbering system and need a row and as a credit and then get applied against an invoice."* ITFlow has a real, purpose-built table for this — confirmed by reading `itflow_schema_reference.sql` directly: `credits` (`credit_amount`, `credit_type` enum, `credit_note`, `credit_client_id`, `credit_invoice_id` — a single nullable FK to one invoice, no FK constraint actually enforced in ITFlow's schema but the column itself is genuinely nullable, `credit_created_at`, `credit_created_by`). + +**Round 25 confirmed every real number this design needed, and the implementation checks out against all of them:** + +- **11 credit memos total**, confirmed via a full `Billing_Type_ID` breakdown of all of `Billing_Log` (1,301 Agreement-type, 441 Standard-type, 11 Credit-Memo-type) — not just the handful seen incidentally in earlier rounds, which turned out to already be the complete set. +- **Every one of the 11 is fully applied** — for each, the sum of its `Billing_Application` applications (`Payment_Type='C'`, grouped by `Credit_Memo_RecID`) matches its own `Invoice_Amount` magnitude exactly (e.g. Credit_Memo_RecID 1149: one application of 33,529.20 against invoice 1124, matching −33,529.20 exactly). No unapplied credits exist in the current data, though the code still correctly supports that state if one shows up later. +- **2 of the 11 really were split across more than one invoice** — exactly the edge case the code was built to handle defensively, now confirmed real rather than hypothetical: Credit_Memo_RecID 655 (−270.00) was applied as 90.00 each against three separate invoices (651, 673, 693), and Credit_Memo_RecID 741 (−270.00) the same way across invoices 707, 765, 793 — both read like a recurring monthly credit for the same client (reference prefix "HBL001") applied one month at a time rather than all at once. For both, `migrate_credits()` correctly leaves `credit_invoice_id` NULL and records all three applied-to invoices/amounts in `credit_note` instead, with a warning logged — verified against real data, not just reasoned through. + +| Real CW column | ITFlow column (`credits`) | Notes | +|---|---|---| +| `ABS(Invoice_Amount)` | `credit_amount` | `Billing_Log` stores the amount negative; ITFlow's column is a plain magnitude | +| — | `credit_type` | Placeholder — defaults to `'manual'` (one of ITFlow's five enum values: prepaid/manual/refund/promotion/usage). `'refund'` may be more accurate for how these are actually used; not confirmed | +| `Invoice_Number` + `Reference` + `Internal_Note` + `Billing_Log_RecID` | `credit_note` | Free text — carries the ConnectWise credit memo's own invoice number (drawn from the same sequence as real invoices, per your note) so it stays traceable even though it never becomes an ITFlow invoice | +| `Date_Invoice` | `credit_created_at` | | +| — | `credit_created_by` | Defaults to `0` ("system"), same convention as `ticket_created_by` | +| `Billing_Application.Credit_Memo_RecID` → `Billing_Log_RecID` it was applied to | `credit_invoice_id` | **The real linkage, confirmed round 25.** Zero applications → `NULL` (doesn't occur in current data, but handled); exactly one invoice (9 of 11 credit memos) → linked via the invoice id map; more than one distinct invoice (2 of 11, confirmed real) → `NULL` with full detail in `credit_note`, logged loudly | +| `Company_RecID` | `credit_client_id` | Standard client id-map lookup | + +**Implemented and confirmed** in `etl_skeleton.py`'s `migrate_credits()`, run as Stage 9 (after Stage 7, Invoices). Only remaining open point: `credit_type` is still a placeholder (`'manual'`) — worth changing to `'refund'` if that better matches how you think about these. + +### 5.9c Quotes ← `SO_Opportunity` (+ `Order_Header` where linked) + +The Opportunity record itself is the quote, the whole way through its life — confirmed by walking through a live example (Opportunity 368 / Order_Header 335, "Truline Bitwarden") in the ConnectWise UI together. **Hybrid model**: every `SO_Opportunity` row migrates as a quote; the subset with a linked `Order_Header` also gets real pricing and line items. + +| Real CW column | ITFlow column (`quotes`) | Notes | +|---|---|---| +| `Opportunity_RecID` | `quote_number` | Reused as-is for traceability — same no-synthetic-prefix approach as invoices, see item 9 below | +| `Opportunity_Name` (fallback: synthesized "ConnectWise Opportunity #n") | `quote_scope` | A real `quotes` column that was already being fetched from CW (`Opportunity_Name`) but never actually used anywhere | +| `SO_Opp_Status_RecID` → `SO_Opp_Status.Description` | `quote_status` | Join required. Column name and full value set (Open, Won, Lost, No Decision, Recommendation, Order Approved, Lost - Price, Lost - Time) confirmed directly by round 18's `COLUMN_NAME` query | +| `Date_Became_Lead` | `quote_date` | | +| `Date_Close_Expected` | `quote_expire` | | +| `Notes` | `quote_note` | | +| `Currency_RecID` → `Currency.Iso_Code` | `quote_currency_code` | Join required; falls back to `'GBP'` when missing | +| `Company_RecID` | `quote_client_id` | Via ID map (client, falling back to vendor) | +| — | `quote_category_id` | No CW equivalent — same get-or-create pattern as `invoice_category_id`, a single "Migrated from ConnectWise" `Quote`-type category, since ITFlow requires this non-null with no default | +| — | `quote_url_key` | Random 200-character string, same reasoning as `invoice_url_key`/`ticket_url_key` | +| `Order_Header.Total` (via linked `Order_Header`, if any) | `quote_amount` | `0` when no linked order exists (unpriced quote) | + +Line items (`quote_items`): sourced from `IV_Product` filtered by `Order_Header_RecID`, the exact same pattern already confirmed for invoice product line items (`Description`/`Quantity`/`Unit_Price`) — only present for quotes with a linked order. + +`SO_Opportunity.Estimated_Total` and `old_Actual_Total` are **not** used — real sample data showed `Estimated_Total = 0.00` on a genuinely active, real-value quote (the "Truline Bitwarden" example), and the `old_` prefix on several related columns (`old_Close_Flag`, `old_Won_Flag`, `old_Competitor`, `old_Close_Notes`) signals they're legacy, superseded by `Order_Header`'s totals for anything that's actually been priced. + +`SO_Opp_Status.Description` as the `quote_status` source is now **directly confirmed** (round 18's `COLUMN_NAME` query), not just the strong inference it was before — the confirmed value set is Open, Won, Lost, No Decision, Recommendation, Order Approved, Lost - Price, Lost - Time, matching what the earlier data-only sample implied exactly. + +**Implemented and working** in `etl_skeleton.py`'s `migrate_quotes()`. + +### 5.10 Attachments ← `DM_Document` + `DM_Relationship` + +`DM_Relationship` is a polymorphic link: one row per attachment-to-parent link, with an `Attached_Record_Type` label (`"Company"`, `"Service"`, etc.) indicating which of its many nullable `*_RecID` columns is actually populated for that row (`Company_RecID`, `Config_RecID`, `SR_Service_RecID`, `Contact_RecID`, `Billing_Log_RecID`, and more). + +| Real CW column | Notes | +|---|---| +| `DM_Document.Title` | File display name | +| `DM_Document.Filename` / `ServerFilename` / `Path` | Needed to locate and download the actual binary — this is a file-transfer step, not just a database copy | +| `DM_Relationship.Attached_Record_Type` | Tells you which join table to populate in ITFlow | + +ITFlow's file-join tables cover contacts, vendors, software, and tickets, but **not clients directly** — a `DM_Relationship` row with `Attached_Record_Type = 'Company'` has no matching ITFlow join table. Those will need to land as ITFlow `documents` (which do belong directly to a `client_id`) rather than as raw `files`. + +### 5.11 Custom fields + +Not yet started — lower priority than the core entities above. Each entity's custom fields live in a `*_User_Defined_Field_Value` table (e.g. `Company_User_Defined_Field_Value`, `Contact_User_Defined_Field_Value`, `Config_User_Defined_Field_Value`, `Time_Entry_User_Defined_Field_Value`), which is a reasonably standard ConnectWise pattern — should be straightforward to confirm once the core entities are working. + +## 6. Still-open items + +Resolved: `Communication_Type`'s columns, `SR_Config` as the ticket↔asset link, the `SR_Detail`/`Time_Entry` visibility rule (`InternalAnalysis_Flag`), asset type (resolved as a decision, not a schema finding), the SLA tier-collapsing rule, the `Time_Entry` billing rate, technician mapping, the quotes design/source (`SO_Opportunity` + `Order_Header` hybrid), `SO_Opp_Status.Description` as the quote-status column, how invoices get marked Paid, a critical `ticket_created_by` bug, `ticket_priority` vocabulary, `ticket_reply_type`/`invoice_status` casing and vocabulary, missing `url_key` fields, `ticket_resolved_at`, `EX_Payment`/`WisePay_Payments`/`GL_Entry`/`GL_EntryDtl` all ruled out as customer-payment sources, which ITFlow account migrated payments post against, full-vs-partial payment (item 22), credit-memo invoices (item 23, now fully confirmed with real numbers — round 25), and the id-map crash-safety gap (item 24). What's left: + +1. ~~Where asset *type* is actually tracked~~ — **resolved by your call, not by finding the column**: it's likely a `Config` custom field via `User_Defined_Field`/`Config_User_Defined_Field_Value` (or lives in ConnectWise Automate, which syncs devices into Manage and owns this classification), but rather than migrate a guess, `asset_type` is left unpopulated in `migrate_assets()` — every ITFlow asset lands with no type set, to be categorized manually after migration. Automate DB access is potentially available for a future pass if you want to revisit this. +2. **"Do Not Respond" priority tickets** — business decision on how these should land in ITFlow (active, closed, or excluded). Not blocking: `migrate_tickets()` currently migrates them like any other ticket. +3. ~~Product/expense invoice line items~~ — **resolved for products**: `IV_Product` follows the identical `Billing_Log_RecID`/`SR_Service_RecID` pattern as `Time_Entry`, and is fully implemented. Expenses not yet confirmed, still low priority. +4. ~~Technician (`Member`) → ITFlow user mapping~~ — **resolved by your update: only 2 technicians exist in this ConnectWise instance.** `migrate_members()` now matches `Member.Email_Address` to an existing ITFlow `users.user_email` (case-insensitive) and records the id mapping — it deliberately does **not** create new ITFlow user accounts, since `users.user_password` is a required hashed-password column and generating a throwaway login from a migration script is the wrong way to hand out PSA access. **Action needed before running:** both technicians need a real ITFlow login already created (the normal way, through the app) with an email address matching their ConnectWise `Email_Address`, or the mapping will log a warning and skip them (everything downstream still degrades to "unassigned" rather than erroring, so this doesn't block a run either way). +5. **`Manufacturer_RecID` vs. `Mfg_Company_RecID`** on `Config` — likely redundant, worth a quick spot-check. +6. **Country lookup** for `locations.location_country` — small table, not yet pulled. +7. ~~The SLA 5-tier → 3-tier collapsing rule for contracts~~ — **resolved**: implemented in `migrate_contracts()` via `URGENCY_TO_SLA_TIER`, Critical and High both collapse to "high," Critical wins on tie. +8. ~~`Time_Entry`'s billing rate/amount column~~ — **resolved**: `Hourly_Rate` × `Hours_Bill` = `Extended_Invoice_Amount`, confirmed against real invoiced rows. `migrate_invoices()` now prices time-based line items using the real numbers. +9. **Sage invoice migration coexistence** — you're migrating older historical invoices from Sage into ITFlow separately, via your own script, before this one runs. `invoice_number`/`invoice_prefix` now migrate exactly as ConnectWise has them — **by your explicit instruction, no synthetic prefix is added**, even though an earlier version of this script did add `'CW-'` specifically to avoid ambiguity with Sage's invoice numbers. Since that's been removed, if a Sage-migrated invoice and a ConnectWise-migrated invoice ever land on the same `invoice_number`, ITFlow has nothing distinguishing them apart from client/date/whichever migration ran first — worth a quick check that your Sage and ConnectWise invoice number ranges genuinely don't overlap before running this for real. Also still worth confirming that script's migration order relative to this one — specifically, that it either reuses this script's client/location id mapping (via the same `migration_id_map` SQLite database) or matches clients by name/some other reliable key, so Sage invoices don't end up attached to duplicate client records. +10. **Proactive board deletion** — you're deleting the "Managed Service - Proactive Alerts" board and its tickets from ConnectWise entirely before running this migration. The script's `WHERE SR_Board_RecID = REACTIVE_BOARD_RECID` filter stays in place regardless, as a harmless safety net (see `etl_skeleton.py` comment above `REACTIVE_BOARD_RECID`) — it costs nothing and protects against a partial cleanup or running against a pre-cleanup copy of the database by mistake. +11. ~~Currency~~ — **resolved**: confirmed **GBP**, not USD. `migrate_clients()`, `migrate_invoices()`, and `migrate_quotes()` all default to `'GBP'` when `Currency_RecID` doesn't resolve to a code (real currency data is always used when present — this only affects rows where it's genuinely missing). +12. ~~`SO_Opp_Status.Description` column name~~ — **resolved**: directly confirmed via `COLUMN_NAME` query. `Description` is real, and the full status value set is Open, Won, Lost, No Decision, Recommendation, Order Approved, Lost - Price, Lost - Time — matching the earlier inference exactly. +13. ~~How invoices get marked Paid~~ — **resolved**: round 19 confirmed `Billing_Status` is a workflow state, not a payment state, and found `Billing_Log.Date_Paid` as the real payment signal, with no separate AR/cash-receipts table in this instance. ITFlow support's own migration guidance confirmed the exact `invoice_status` vocabulary (Draft/Sent/Paid/Cancelled) and that a real `payments` row should back "Paid." Both `migrate_invoices()`'s status logic and `migrate_payments()` (Stage 8) are implemented — see Section 5.9/5.9a. +14. **`ticket_created_by` was silently missing from every ticket insert — fixed, but worth flagging why it mattered.** ITFlow's `tickets.ticket_created_by` column is `NOT NULL` with no `DEFAULT`. The original `migrate_tickets()` never set it, which is fine under lenient SQL modes but is a hard "doesn't have a default value" error under MySQL/MariaDB's default *strict* mode — almost certainly what a fresh ITFlow install runs. This would have meant Stage 6 failing outright on the very first ticket, not a partial/degraded migration. Caught by cross-checking the schema against ITFlow support's own example INSERT statement, not by running against a real database. Now set to `0` ("system"), which ITFlow support confirmed is an acceptable value for this field. +15. ~~`ticket_priority` vocabulary~~ — **resolved**: was passing CW's raw 5-tier text through unchanged; ITFlow support confirmed the app only expects "Low"/"Medium"/"High". Fixed via `URGENCY_TO_TICKET_PRIORITY`, same collapse pattern as the SLA tier logic, tied to the same open "Do Not Respond" judgment call as item 2. +16. ~~`ticket_reply_type` / `invoice_status` casing and vocabulary~~ — **resolved**: ticket replies now write exactly `"Internal"`/`"Public"` (was lowercase); invoice status now constrained to ITFlow's real 4-value set instead of raw ConnectWise text. +17. **`ticket_reply_type`'s third value, `'Client'` — not yet implemented.** ITFlow support's guidance revealed replies can be `Internal`, `Public`, or `Client` (the client's own submission) — this migration only does the 2-way Internal/Public split, so client-submitted replies currently look identical to agent public replies. `Internal_Member_Flag`/`External_Source_Flag` (ruled out earlier as the *visibility* signal) haven't been ruled out as the *authorship* signal for this — worth a real-data discovery round before attempting it, not a guess. +18. ~~`ticket_resolved_at`~~ — **resolved (round 20)**: `SR_Service`'s full column list confirms CW has no separate resolved-vs-closed concept in this instance. `migrate_tickets()` now sets it equal to `Date_Closed` (judgment call, documented in the function's docstring). +19. **`url_key` fields (`ticket_url_key`, `invoice_url_key`, `quote_url_key`) were never populated** — nullable, so nothing errored, but ITFlow support confirmed these need a random 200-character string for portal/share links to work. All three now generate one per row via `generate_url_key()`. +20. ~~`EX_Payment`~~ — **resolved, ruled out**: round 20 confirmed both its real columns and row count. Its columns (`Description`, `Default_Flag`, plus standard audit columns) match the exact shape of every other CW lookup table in this project (`SO_Opp_Status`, `Billing_Status`, etc.) rather than a transaction table — and it has **0 rows** regardless, so it's irrelevant either way. `EX_Payment` is not a source of any payment data. +21. ~~`WisePay_Payments`~~ — **resolved, ruled out**: its columns confirm this is genuinely CW's real online-payment transaction table (`Payment_Date_UTC`, `Batch_Payment_Amount`, `WisePay_Reference`), but it has **0 rows** — this MSP has never taken a payment through it. With every candidate from round 19's search now ruled out, `Billing_Log.Date_Paid` isn't just the best payment signal found in this ConnectWise instance, it's confirmed to be the only one that exists. +22. ~~Full vs. partial payment~~ — **resolved and implemented.** Round 21 (checking `Billing_Log`'s own columns) found nothing; you confirmed partial payments are real anyway. Rounds 22–24 traced it to the real mechanism: `dbo.Billing_Application` (`Billing_Log_RecID`, `Applied_Amount`, `Payment_Type` `'P'`/`'C'`, `Date_Applied`) is what every ConnectWise paid-amount figure is actually computed from, confirmed via ConnectWise's own view SQL and a real example (Invoice 2783, paid 15.60 of 60.00, `Date_Paid` NULL — proving `Date_Paid` is only ever set on full payoff, so the old `Date_Paid`-gated query was silently skipping every partially-paid invoice, not just mis-amounting them). `migrate_payments()` now queries `Billing_Application` directly (`Payment_Type='P'`) for both `payment_amount` and `payment_date`, covering full and partial payments correctly. `GL_Entry`/`GL_EntryDtl` were ruled out along the way (general-ledger/costing records, not a payment ledger). Two judgment calls made, not separately confirmed with you: `Payment_Type='C'` credit-memo applications are excluded from `payments` (not real cash through the bank account); `Payment_Source_RecID` (always `0` in the sample checked) isn't yet used for `payment_method`. See Section 5.9a. +23. ~~Credit-memo invoices (`Billing_Type_ID='C'`, negative `Invoice_Amount`)~~ — **fully resolved and confirmed with real numbers (round 25).** Found while designing item 22's fix; you confirmed directly these are not real invoices (real example: Billing_Log_RecID 1149, "Parkway Derby LTD", −33,529.20, reference "PWD001-2023-02CR"), then told us exactly where they should go instead: *"Credits follow the invoicing numbering system and need a row and as a credit and then get applied against an invoice."* `migrate_invoices()` excludes them entirely; `migrate_credits()` (Stage 9) migrates them into ITFlow's dedicated `credits` table instead. Round 25 confirmed all 11 real credit memos exist, all 11 are fully applied, and 2 of the 11 (Credit_Memo_RecID 655 and 741, both split across exactly 3 invoices each) genuinely exercise the multi-invoice edge case the code was built to handle — verified against real data, not just reasoned through. See Section 5.9b. Only remaining point: `credit_type` is a placeholder (`'manual'`), not confirmed against how you actually categorize these. +24. ~~Id-map/ITFlow commit ordering — crash-safety gap~~ — **resolved.** Every `migrate_*` function called `record_mapping()` per row (which committed the SQLite id-map immediately) but only committed the actual ITFlow insert once, at the end of the whole stage. A crash between those two points would leave the id-map durably believing rows were migrated that ITFlow never received — and `already_migrated()` would then skip re-migrating them on every future run, forever, with no error. Not tied to any specific entity — it applied identically to all stages that call `record_mapping()`. Fixed by removing the commit from `record_mapping()` itself and committing the id-map immediately after each stage's real `itflow_conn.commit()`, so a crash between the two now only risks the same small window every dual-database write has, not a per-row window repeated across an entire stage. `migrate_members()` (which never writes to ITFlow, only maps existing users) gets its own explicit final commit for the same reason. Worth being aware of even after the fix: if a stage does crash mid-run, some ITFlow rows from that stage may exist without a matching id-map entry (since ITFlow's commit — and now the id-map's — only happens at the very end) — re-running the stage will re-attempt those rows. That's a duplicate-row risk on retry after a crash, not silent loss, and most inserts either have natural uniqueness (invoice/quote/ticket numbers) or `INSERT IGNORE` (asset↔ticket links) — worth a manual check of row counts against `stats.extracted` after any run that didn't finish cleanly, before re-running the same stage. +25. ~~Which ITFlow account migrated payments post against~~ — **resolved by your explicit call, overriding the earlier default.** ITFlow support's guidance suggested a separate dedicated "migration" account; you want the opposite — every payment, migrated and current/future alike, posted against the ONE real inbound bank account you actually use, matching your real process. `get_or_create_account()` (which would auto-create a account by name) has been replaced with `get_payment_account_id()`, a strict lookup that does NOT create anything — it requires that account to already exist in ITFlow. **Action needed before Stage 8**: create/confirm that account in ITFlow (Finance > Accounts) and set `PAYMENT_ACCOUNT_NAME` in `etl_skeleton.py` (or the `ITFLOW_PAYMENT_ACCOUNT_NAME` env var) to its exact name — the script now fails fast with a clear error if the name doesn't match, rather than risk creating or posting against the wrong account. + +## 7. Where to run the script + +**Confirmed: ITFlow is self-hosted on the same local network as ConnectWise's on-prem SQL Server.** That's the simplest case — no VPN or firewall changes should be needed between the two. + +The script needs live, simultaneous network access to both databases from whichever single machine runs it: for every batch of rows it reads from ConnectWise and writes to ITFlow within the same function call, so it can't be split across two machines without a rewrite. Concretely: outbound TCP access to ConnectWise's SQL Server (default port 1433) and access to ITFlow's MySQL (default port 3306) at the same time. + +**Recommended: run it directly on the ITFlow server itself**, if it's a machine you can get a shell on (ITFlow is a standard LAMP-style PHP/MySQL app, so this is usually straightforward). That gets MySQL access for free over `localhost` — no firewall rule or MySQL user grant needed for that side — and only needs one thing confirmed: that the ITFlow server can reach the ConnectWise SQL Server's IP and port 1433 across your LAN. If there's any VLAN segmentation between the two, even calling it "the same network," that's worth a quick connectivity test first (e.g. `Test-NetConnection -Port 1433` from the ITFlow box, or `telnet 1433`) before running Stage 1 for real. + +If running directly on the ITFlow server isn't practical, the alternative is any other machine on the same LAN — a workstation, a small VM — as long as ITFlow's MySQL is configured to accept remote connections from that machine specifically (check the MySQL user's host grant, e.g. `'migration_user'@'192.168.1.50'` rather than `'migration_user'@'localhost'`, and that `bind-address` in MySQL's config isn't restricted to `127.0.0.1` only). + +Either way, before running anything for real: + +1. Install the Python dependencies on that machine: `pip install pyodbc mysql-connector-python --break-system-packages` (or `pymssql` instead of `pyodbc`, matching whichever SQL Server driver is actually installed there), plus the ODBC Driver 18 for SQL Server if using `pyodbc`. +2. Set the 8 required environment variables (`CW_DB_SERVER`, `CW_DB_NAME`, `CW_DB_USER`, `CW_DB_PASSWORD`, `ITFLOW_DB_HOST`, `ITFLOW_DB_NAME`, `ITFLOW_DB_USER`, `ITFLOW_DB_PASSWORD`) — see the example block at the top of `etl_skeleton.py`. Credentials are read from the environment now, not typed into the file, since this script may end up living on a real server. The script fails fast with a clear error listing exactly which ones are missing if you forget any. A 9th, `ITFLOW_PAYMENT_ACCOUNT_NAME`, is only required for Stage 8 (Payments) — see step 5 below. +3. For the ConnectWise side, a read-only SQL login is worth creating specifically for this script rather than reusing an admin account, since it only ever runs `SELECT` queries against ConnectWise. +4. Run `python etl_skeleton.py --list-stages` first — it only prints the stage list and touches nothing, a safe way to confirm the script itself is wired up correctly before touching real data. +5. **Before running Stage 8 (Payments)**: create or confirm the real ITFlow account that both migrated and current/future invoice payments should post against (Finance > Accounts) — the one inbound bank account you actually reconcile against, per your call. Set `ITFLOW_PAYMENT_ACCOUNT_NAME` to that account's exact name. `migrate_payments()` looks it up and stops with a clear error rather than guessing or creating a new account if the name doesn't match. +6. **Take a fresh, verified ITFlow database backup immediately before the first real `--all` or per-stage run — separate from the daily 02:00 systemd backup.** The backup strategy decided alongside this plan (see the `itflow-backup-strategy` project doc) gives ITFlow a real transactionally-consistent `mysqldump`, but its own open items note the restore path hasn't actually been tested yet. Don't let this migration be the first time that restore process gets exercised for real — run one manual backup right before Stage 1, and ideally do a throwaway restore-to-scratch-database test at least once beforehand so you know the restore steps work, not just that the dump completes. This matters most for Stages 7/8/9 (Invoices, Payments, Credits), which write real financial data and, for Stage 8, post against a real bank account. + +## 8. Validation checklist (unchanged from first draft, still applies) + +- Row counts per entity roughly match expectations (105 clients, ~1,600 contacts, 541 assets, 8,475 Reactive tickets, 103 contracts, ~1,742 invoices, 11 credits). +- Foreign key integrity — no orphaned `tickets.ticket_client_id`, `contacts.contact_client_id`, etc. +- Every CW ticket status and priority value has a corresponding ITFlow row. +- Client portal users can log in and see only their own data. +- Time totals per client roughly match CW's billed/actual hours for a sample period. +- Attachments open correctly, not just that a `files`/`documents` row exists. +- A final client-by-client walkthrough before decommissioning ConnectWise access. diff --git a/admin/includes/starter_content_pick.php b/admin/includes/starter_content_pick.php index ae6ab8261..7632d630d 100644 --- a/admin/includes/starter_content_pick.php +++ b/admin/includes/starter_content_pick.php @@ -51,7 +51,7 @@ function starterItemLook($pack, $row) { /* The packs whose items have more to them than a line - shown whole by Preview. */ function starterPreviewPacks() { - return ['ticket_templates', 'project_templates', 'canned_responses', 'vendor_templates', 'document_templates', 'license_templates', 'products']; + return ['ticket_templates', 'project_templates', 'canned_responses', 'kb_articles', 'vendor_templates', 'document_templates', 'license_templates', 'products']; } /* [Words in brackets] in a template, marked as the bits filled in as it is used. */ @@ -171,6 +171,16 @@ function starterItemPreview($pack, $row) { $html .= starterPreviewFillIns((array) ($row['fill_ins'] ?? [])); return $html . '

What it says

' . starterPreviewFills($row['content'] ?? '') . '
'; + case 'kb_articles': + $review = intval($row['review_months'] ?? 0); + $html .= '
' + . starterPreviewFact('Category', escapeHtml((string) ($row['category'] ?? ''))) + . starterPreviewFact('Tags', escapeHtml(implode(', ', (array) ($row['tags'] ?? [])))) + . starterPreviewFact('Reviewed', $review ? 'Every ' . ($review === 12 ? 'year' : "$review months") : '') + . starterPreviewFact('Comes in as', 'A draft only your team can see') + . '
'; + return $html . '

What it says

' . starterKbFill($row['content'] ?? '') . '
'; + case 'license_templates': $html .= '
' . starterPreviewFact('Type', escapeHtml((string) ($row['type'] ?? ''))) diff --git a/admin/post/demo_data_model.php b/admin/post/demo_data_model.php index 7e55b676a..073876fa8 100644 --- a/admin/post/demo_data_model.php +++ b/admin/post/demo_data_model.php @@ -722,6 +722,7 @@ function demoDataLoad($mysqli) { 'projects' => 0, 'billing' => 0, 'company' => 0, + 'kb' => 0, 'skipped_credentials' => 0, ]; @@ -768,6 +769,8 @@ function demoDataLoad($mysqli) { // install from - and both builders are guarded, so a run that only fills in // missing clients does not double anything up. demoBuildInternalDiary($mysqli, $context, $counts); + // The Knowledge Base - after the clients, as who can read each article, its feedback and the tickets linking to it are theirs + demoBuildKnowledgeBase($mysqli, $context, $counts); demoBuildCompanyFinancials($mysqli, $context, $counts); demoReconcileAccounts($mysqli, $context); @@ -790,11 +793,25 @@ function demoDataRemove($mysqli) { $clients = demoDataClients($mysqli); $org_vendors = demoDataOrgVendorIds($mysqli); + $kb_articles = demoKbArticleIds($mysqli); - if (!$clients && !$org_vendors) { + if (!$clients && !$org_vendors && !$kb_articles) { return 0; } + // The Knowledge Base articles - matched on title and summary together - with + // their versions, tags, readers and feedback, and the searches that found nothing + foreach ($kb_articles as $kb_article_id) { + kbArticleDelete($kb_article_id); + } + if ($kb_articles || $clients) { + foreach (demoKbSearchMisses() as $miss) { + if ($miss[1] === '') { + mysqli_query($mysqli, "DELETE FROM kb_search_misses WHERE kb_search_miss_source = 'public' AND kb_search_miss_client_id = 0 AND kb_search_miss_query = '" . escapeSql($miss[0]) . "'"); + } + } + } + foreach (array_keys($clients) as $client_id) { $client_id = intval($client_id); @@ -812,6 +829,7 @@ function demoDataRemove($mysqli) { mysqli_query($mysqli, "DELETE FROM ticket_assets WHERE ticket_id IN ($ticket_ids)"); mysqli_query($mysqli, "DELETE FROM ticket_watchers WHERE watcher_ticket_id IN ($ticket_ids)"); mysqli_query($mysqli, "DELETE FROM ticket_views WHERE view_ticket_id IN ($ticket_ids)"); + mysqli_query($mysqli, "DELETE FROM ticket_reads WHERE ticket_id IN ($ticket_ids)"); mysqli_query($mysqli, "DELETE FROM ticket_attachments WHERE ticket_attachment_ticket_id IN ($ticket_ids)"); mysqli_query($mysqli, "DELETE FROM tasks WHERE task_ticket_id IN ($ticket_ids)"); mysqli_query($mysqli, "DELETE FROM sla_history WHERE sla_history_ticket_id IN ($ticket_ids)"); @@ -967,6 +985,10 @@ function demoDataRemove($mysqli) { mysqli_query($mysqli, "DELETE FROM logs WHERE log_client_id = $client_id"); mysqli_query($mysqli, "DELETE FROM notifications WHERE notification_client_id = $client_id"); mysqli_query($mysqli, "DELETE FROM client_tags WHERE client_id = $client_id"); + if (demoKbTablesReady($mysqli)) { + mysqli_query($mysqli, "DELETE FROM kb_search_misses WHERE kb_search_miss_client_id = $client_id"); + mysqli_query($mysqli, "DELETE FROM kb_article_feedback WHERE kb_article_feedback_client_id = $client_id"); + } mysqli_query($mysqli, "DELETE FROM clients WHERE client_id = $client_id"); // Never leave the company's own-client designation pointing at a client that is gone @@ -4555,6 +4577,476 @@ function demoOneOffInvoicePool() { // - fictional contacts must never be deliverable and a fictional domain must // never resolve to somebody's real business if a refresh gets clicked. // build 0 is a Windows house, build 1 is a Linux house. +// ------------------------------ +// demoDataKbArticles +// The Knowledge Base this MSP has grown - its own articles, apart from the +// starter ones (whose titles none of these share, so the Knowledge Base +// Articles pack still adds its own beside them). Who can read each: every +// client, the clients with some client tags, named demo clients, anyone +// (the public help center), or agents only - and two drafts and an archived +// one. Each carries how long ago it went out, how often it is reviewed and +// when it last was, its reads, older versions and what its readers said; and +// 'tickets', the demo ticket subjects whose replies link to it. Removal +// matches an article on its title and summary together. +// name, description, category, tags, content, audience, months ago made, +// review months, months ago reviewed (null never), views, versions (months +// ago => [summary, content] it said then), feedback ([helpful, comment] from +// portal contacts, or public ones with 'public'), tickets, archived months ago +// ------------------------------ +function demoDataKbArticles() { + + $steps = function (array $items) { + return '
  1. ' . implode('
  2. ', $items) . '
'; + }; + $list = function (array $items) { + return '
  • ' . implode('
  • ', $items) . '
'; + }; + $a = function ($name, $description, $category, array $tags, $content, $audience, $made, $review, $reviewed, $views, array $versions = [], array $feedback = [], array $tickets = [], $archived = null) { + return compact('name', 'description', 'category', 'tags', 'content', 'audience', 'made', 'review', 'reviewed', 'views', 'versions', 'feedback', 'tickets', 'archived'); + }; + $yes = [1, '']; + + $support_hours = '

Our help desk is staffed 8:00 AM to 6:00 PM, Monday to Friday, apart from public holidays.

' + . '
How fast we respond
' . $list([ + 'Critical - the business can\'t work, or a security incident: within 1 hour, around the clock for managed clients', + 'High - one person can\'t work: within 2 business hours', + 'Normal - something is wrong but there is a way around it: within 4 business hours', + 'Low - requests and questions: within 1 business day', + ]) + . '
Reaching us

Open a ticket in the client portal or email us, and for anything critical call as well. Every request gets a ticket number by email straight away - reply to that email to add to it.

'; + + return [ + + // Every client + $a('How we handle your support requests', 'Our support hours, how quickly we respond to each priority, and how to reach us.', 'Getting Help', ['How-To'], + $support_hours, ['all'], 22, 12, 3, 486, + [14 => ['Our support hours and how quickly we respond.', str_replace(['1 hour', '2 business hours'], ['2 hours', '4 business hours'], $support_hours)]], + [$yes, $yes, $yes, $yes, $yes, $yes, [0, 'Does the 1 hour include weekends for us? We are not on the managed plan.'], $yes]), + + $a('Reporting a suspicious email to us', 'Use the Report button in Outlook - it reaches us and takes the email out of your inbox.', 'Security', ['Security', 'How-To'], + '

If an email looks wrong, report it rather than deleting it - we check it, and if it is phishing we pull it out of everyone else\'s mailbox too.

' + . $steps(['Don\'t click any links or open attachments.', 'In Outlook, select the email and choose Report on the toolbar, then Report phishing.', 'That\'s it - it goes to us and leaves your inbox.']) + . '

On a phone, open the email, tap the ... menu and choose Report phishing. If you already clicked something or typed your password, call us straight away.

', + ['all'], 19, 6, 2, 371, + [11 => ['Forward suspicious emails to us as an attachment.', '

Forward any suspicious email to us as an attachment, then delete it.

']], + [$yes, $yes, $yes, $yes, [0, 'There is no Report button in my Outlook on the Mac.'], $yes, $yes], + ['Suspicious invoice email reported by staff']), + + $a('Outlook disconnected after a password change', 'What to do when Outlook says Disconnected or keeps asking for your password after you changed it.', 'Email and Calendar', ['Troubleshooting', 'Quick Fix', 'Microsoft 365'], + '

Outlook remembers your old password until you give it the new one. Usually all it takes is:

' + . $steps(['Close Outlook completely.', 'Open it again and type your new password when it asks - tick Remember my credentials.', 'Approve the sign-in on your phone.']) + . '

If it doesn\'t ask, or keeps asking: restart the computer and open Outlook again. Your phone may ask for the new password too - type it in there as well.

' + . '

Still showing Disconnected after a restart? Open a ticket and tell us the time you changed the password.

', + ['all'], 16, 12, 4, 298, [], [$yes, $yes, $yes, $yes, $yes, [0, 'Did all of this and it still says disconnected.'], $yes], + ['Outlook stuck on disconnected after password reset']), + + $a('When multi-factor prompts keep coming back on your phone', 'Why your phone keeps asking you to approve sign-ins, and how to make it stop.', 'Accounts and Passwords', ['Troubleshooting', 'Mobile', 'Security'], + '

A prompt you didn\'t start is a warning - deny it and call us, someone may have your password.

' + . '

If the prompts are yours but keep looping, it is usually the phone\'s mail app or Teams using an old sign-in:

' + . $steps(['Open the Authenticator app and check the time on your phone is set automatically.', 'In the Outlook and Teams apps, sign out and sign in again.', 'If you changed your password recently, update it in each app that asks.', 'Restart the phone.']) + . '

If it still loops, tell us which apps are open and what the prompt says.

', + ['all'], 9, 6, null, 167, [], [$yes, $yes, [0, 'Prompts stopped for a day and came back.'], $yes], + ['Multi factor prompts looping on mobile']), + + $a('A slow computer - what to try first', 'Quick things that speed up a slow computer, and what to tell us if they don\'t.', 'Devices', ['Quick Fix', 'Self-Service'], + $steps(['Restart it - choose Restart, not Shut down.', 'Close browser tabs you don\'t need - each one uses memory.', 'Check for updates waiting to install, and let them finish.', 'Make sure you have space left - Settings > System > Storage.']) + . '

If it is still slow, open a ticket saying when it started and what is slow - starting up, one program, or everything. We can see what it is doing from here.

', + ['all'], 14, 12, 5, 242, [], [$yes, $yes, $yes, $yes, $yes], + ['Workstation running very slowly since last week']), + + // Clients by client tag + $a('What your managed service covers', 'What is included in your managed service agreement, and what is billed as extra work.', 'Policies', ['Policy'], + '
Included
' . $list(['Help desk support for your staff, remote and on site', 'Monitoring, patching and antivirus on every managed computer and server', 'Backups of your servers and Microsoft 365, checked daily', 'Moves, adds and changes for existing staff', 'A quarterly review with us']) + . '
Billed separately
' . $list(['New hardware and software, and setting it up', 'Projects - office moves, new servers, migrations', 'Work on devices we don\'t manage', 'After-hours work you ask for that isn\'t an emergency']) + . '

Not sure if something is covered? Ask before we start - we always quote first.

', + ['tags' => ['Managed']], 20, 12, 7, 133, + [12 => ['What is included in your managed service.', '
Included
  • Help desk support
  • Monitoring and patching
  • Backups
']], + [$yes, $yes, $yes]), + + $a('Reaching us after hours', 'Who to call outside business hours, and what counts as an emergency.', 'Getting Help', ['How-To'], + '

Your agreement includes after-hours support for emergencies. Call our main number and choose the on-call option - it rings the engineer on call, who calls you back within 30 minutes.

' + . '
An emergency is
' . $list(['The whole office, or a site, can\'t work', 'A server or the internet connection is down', 'A suspected security incident - ransomware, a hacked account']) + . '

Everything else, open a ticket and we pick it up first thing.

', + ['tags' => ['After Hours Support']], 18, 12, 4, 64, [], [$yes, $yes]), + + $a('Nextcloud - when files stop syncing', 'Fix a Nextcloud desktop client that has stopped syncing on one computer.', 'Files and Sharing', ['Troubleshooting'], + '

The Nextcloud icon by the clock shows how syncing is going - a red cross or a pause sign means it has stopped.

' + . $steps(['Click the icon and check it says you are signed in - sign in again if it asks.', 'If it says paused, choose Resume sync.', 'Look under Not synced for files with problems - a name with characters like : or ? won\'t sync, rename it.', 'Quit Nextcloud and start it again from the Start menu.']) + . '

Still stuck? Open a ticket with a screenshot of the Nextcloud window.

', + ['tags' => ['Hosting']], 11, 12, null, 58, [], [$yes, [0, 'Mine said the server was unreachable.']], + ['Nextcloud sync stuck on one machine']), + + $a('Sending sensitive information securely', 'How to send records, ID documents and financial details safely, as your compliance requirements expect.', 'Security', ['Security', 'Policy'], + '

Some information can\'t go out as an ordinary email: patient or client records, ID documents, bank and card details.

' + . $list(['Type [secure] at the start of the subject line - the email is encrypted, and the person reads it after confirming their address', 'For files, share a OneDrive link to specific people, with an expiry date, rather than attaching them', 'Never put card numbers or passwords in an email at all']) + . '

If you sent something to the wrong person, tell us straight away - we may be able to recall it, and you may need to report it.

', + ['tags' => ['Compliance']], 13, 6, 5, 104, [], [$yes, $yes, $yes, [0, 'Does [secure] work from the phone app too?']]), + + $a('Working alongside your in-house IT team', 'How we split the work with your own IT staff, and how to raise things with us.', 'Policies', ['Policy'], + '

On a co-managed agreement your own IT team stays the first point of contact for your staff. We look after the infrastructure, security and backups, and back your team up on anything they pass to us.

' + . $list(['Your IT team raises tickets with us through the portal, like anyone else', 'We tell them about changes we make, before we make them', 'Anything urgent, they call us directly']) + . '

Your account manager reviews the split with your IT lead every quarter.

', + ['tags' => ['Co-Managed']], 15, 12, 6, 37), + + // Named clients + $a('Ravenwood - imaging workstation won\'t open X-rays', 'What to check when the imaging software can\'t open patient X-rays in an operatory.', 'Devices', ['Troubleshooting', 'Known Issue'], + '

The imaging software reads X-rays from the imaging server. When it can\'t reach it, images show as a grey box or the software says the image store is unavailable.

' + . $steps(['Check the other operatory - if theirs works too, it is this workstation; if not, call us straight away.', 'Close the imaging software and the patient chart, and open them again.', 'Restart the workstation.']) + . '

Don\'t restart the imaging server yourself, even out of hours - call us. If the sensor itself won\'t take images, Meridian Dental Systems look after that: their number is on the sticker on the sensor\'s box.

', + ['clients' => ['Ravenwood Dental Group']], 8, 6, 1, 41, [], [[1, ''], [1, '']]), + + $a('Kestrel - connecting a shop floor tablet to the production Wi-Fi', 'Get a shop floor tablet onto the production network so it can reach the machine schedules.', 'Network and Wi-Fi', ['How-To'], + '

Shop floor tablets use the production Wi-Fi, not the office or guest network - only it reaches the machine schedules and the CNC file share.

' + . $steps(['On the tablet, open Wi-Fi settings and choose the production network.', 'Sign in with the tablet\'s own account, from the label on its back - not your own.', 'Open the schedule app and check today\'s jobs load.']) + . '

New tablets have to be added by us first - open a ticket with its serial number before it goes on the floor.

', + ['clients' => ['Kestrel Precision Manufacturing']], 6, 12, null, 19), + + $a('Harbor Point - signing in with your security key', 'Use your hardware security key to sign in to your computer and the core banking system.', 'Accounts and Passwords', ['How-To', 'Security'], + '

Every member of staff signs in with a hardware security key as well as their password - your examiners expect it.

' + . $steps(['Plug the key into a USB port, or hold it to the reader.', 'Type your PIN for the key when asked.', 'Touch the gold disc on the key when it flashes.']) + . '

Keep the key on your lanyard, never in the computer when you leave it. Lost or forgotten it? Your branch manager has a temporary key and we can register it in a few minutes.

', + ['clients' => ['Harbor Point Credit Union']], 10, 6, 3, 88, [], [$yes, $yes, $yes]), + + $a('Summit Ridge - showing your screen on the classroom display', 'Cast your laptop to the classroom display, and what to do when it won\'t connect.', 'Phones and Meetings', ['How-To'], + $steps(['Make sure your laptop is on the staff Wi-Fi.', 'Press Windows + K and choose the room\'s display - its name is on the label under the screen.', 'Enter the code shown on the display if it asks.']) + . '

If it isn\'t listed, turn the display off and on with its remote, wait a minute and try again. Sound plays from the display once connected - check the display\'s own volume.

', + ['clients' => ['Summit Ridge Charter School']], 7, 12, null, 156, [], [$yes, $yes, [0, 'Room 14 display never shows up in the list.'], $yes]), + + $a('Blue Mountain - taproom card terminal offline', 'Get a card terminal in the taproom taking payments again.', 'Network and Wi-Fi', ['Troubleshooting', 'Quick Fix'], + $steps(['Check the terminal\'s screen - No connection means the network, anything else call the payment provider.', 'Turn the terminal off and on with its power button.', 'Check the network cable at the back of its dock is clicked in.', 'Use the spare terminal behind the bar while you wait.']) + . '

If both terminals are offline, the taproom\'s internet may be down - call us.

', + ['clients' => ['Blue Mountain Brewing Co']], 5, 12, null, 27), + + // Anyone - every portal, and the public help center when it is on + $a('Service status and planned maintenance', 'Where we post outages and planned maintenance, and how much notice we give.', 'Getting Help', ['How-To'], + '

We post anything affecting more than one client - outages at a provider we rely on, and our own planned maintenance - on our status page and email the contacts at each client affected.

' + . $list(['Planned maintenance is out of hours, with at least 48 hours notice', 'During an outage we update every 30 minutes until it is fixed', 'Once it is fixed we say what happened and what we are changing']) + . '

Something not working that isn\'t on the status page? Tell us - we may not know yet.

', + ['public'], 21, 12, 9, 523, [], [[1, '', 'public'], [1, '', 'public'], [1, '', 'public'], [0, 'Link to the status page please', 'public'], [1, '', 'public']]), + + $a('Is this email really from us?', 'How we contact you, and what we will never ask for - so you can spot someone pretending to be us.', 'Security', ['Security'], + '

Criminals sometimes pretend to be IT support. We will never:

' + . $list(['Ask for your password, or a code from your phone', 'Ask you to install remote control software we haven\'t mentioned in a ticket', 'Ask you to buy gift cards or make an urgent payment', 'Call out of the blue saying your computer has a virus']) + . '

Emails about your tickets come from our help desk address and quote the ticket number. If you are not sure, hang up or don\'t reply, and call us on the number you already have.

', + ['public'], 17, 12, 4, 309, [], [[1, '', 'public'], [1, '', 'public'], [1, '', 'public']]), + + // Agents only + $a('Resetting a user\'s MFA methods', 'Clear a user\'s registered sign-in methods so they can set up a new phone.', 'Internal Procedures', ['How-To', 'Microsoft 365'], + '

Only after confirming who they are - call them back on the number in their contact record, never one they give you.

' + . $steps(['In the Entra admin center, open Users and the user.', 'Choose Authentication methods, then Require re-register multifactor authentication.', 'Revoke their sessions.', 'Note in the ticket how you confirmed who they were.']) + . '

Ask them to set up the new phone straight away - see the client article on moving an authenticator to a new phone.

', + ['agents'], 12, 12, 2, 0), + + $a('Escalating a circuit fault to the provider', 'What to have ready, and how to chase it, when a client\'s internet circuit is down.', 'Internal Procedures', ['How-To'], + $steps(['Confirm it is the circuit - the router\'s WAN is down, and the provider\'s equipment shows no sync.', 'Find the circuit ID and the provider\'s support line in the client\'s documentation.', 'Open the fault with the provider and put their reference in the ticket.', 'Set the ticket to Waiting on Vendor and update the client every hour.']) + . '

If the client has failover, check it took over, and tell them what will be slower until the circuit is back.

', + ['agents'], 15, 12, 10, 0), + + $a('On call - what counts as urgent', 'Which calls to deal with overnight, and which can wait for the morning.', 'Internal Procedures', ['Policy'], + '

Pick up and work it now:

' . $list(['A whole site down, or a server', 'A suspected security incident', 'Anything a client with after-hours support calls in as critical']) + . '

Log it and leave it for the morning queue:

' . $list(['One user, with a way around it', 'Password resets, unless they can\'t work on a night shift', 'Requests and questions']) + . '

Hand over anything still open at the morning stand-up.

', + ['agents'], 13, 6, 3, 0), + + // Drafts + $a('Imaging server share drops after Windows updates', 'Written up from a solved ticket - the imaging share went missing after the monthly updates. Check it before publishing.', 'Devices', ['Known Issue', 'Troubleshooting'], + '

After the monthly Windows updates, the imaging server sometimes comes back without its share, and the operatory workstations can\'t open X-rays.

' + . $steps(['Check the imaging service has started on the server.', 'Check the share is there and its permissions are unchanged.', 'Restart the imaging service, then check from one operatory.']) + . '

We now hold the updates on this server for a week and restart it by hand, out of clinic hours.

', + ['draft'], 1, 0, null, 0), + + $a('Using the new guest Wi-Fi sign-in page', 'How visitors get online now the guest Wi-Fi has a sign-in page.', 'Network and Wi-Fi', ['How-To'], + '

Visitors join the guest network as before, and their phone or laptop opens a sign-in page. They enter their name and email address and accept the terms, and they are online for the day.

' + . '

If the page doesn\'t appear, open any website and it will.

', + ['draft'], 0, 12, null, 0), + + // Archived + $a('Upgrading to Windows 11 - what to expect', 'What changes when your computer moves to Windows 11, and how long it takes.', 'Devices', ['How-To'], + '

We are moving every managed computer to Windows 11 over the next few months, a few each evening. Your files, programs and settings stay as they are.

' + . $list(['It happens overnight - leave the computer on and plugged in', 'The Start button is in the middle of the taskbar now', 'The first sign-in takes a few minutes longer']) + . '

Anything not working afterwards? Open a ticket and mention the upgrade.

', + ['all'], 23, 0, null, 612, [], [$yes, $yes, $yes, $yes], [], 4), + + ]; +} + +// ------------------------------ +// demoKbCategoryId +// A Knowledge Base category by name - the Categories pack's own, with its +// colour, icon and order, when this install doesn't have it yet. Left in +// place on removal, as demoCategoryId()'s are. +// ------------------------------ +function demoKbCategoryId($mysqli, $name) { + static $cache = []; + if (isset($cache[$name])) { + return $cache[$name]; + } + $id = starterCategoryId($mysqli, $name, 'kb'); + if (!$id) { + foreach (starterContentCategories() as $category) { + if ($category['type'] === 'kb' && $category['name'] === $name) { + $id = starterInsert($mysqli, 'categories', [ + 'category_name' => $category['name'], + 'category_type' => 'kb', + 'category_color' => $category['color'], + 'category_icon' => $category['icon'], + 'category_description' => $category['description'], + 'category_order' => $category['order'], + ]); + break; + } + } + } + return $cache[$name] = $id; +} + +// ------------------------------ +// demoKbArticleIds +// The demo's articles here, archived or not - title|summary => id. +// ------------------------------ +function demoKbArticleIds($mysqli) { + $ids = []; + if (!mysqli_num_rows(mysqli_query($mysqli, "SHOW TABLES LIKE 'kb_articles'"))) { + return $ids; + } + foreach (demoDataKbArticles() as $article) { + $row = mysqli_fetch_assoc(mysqli_query($mysqli, "SELECT kb_article_id FROM kb_articles WHERE kb_article_title = '" . escapeSql($article['name']) . "' + AND kb_article_summary = '" . escapeSql($article['description']) . "' LIMIT 1")); + if ($row) { + $ids[$article['name'] . '|' . $article['description']] = intval($row['kb_article_id']); + } + } + return $ids; +} + +// ------------------------------ +// demoKbSearchMisses +// What the demo clients' staff, and visitors to the public help center, +// searched for and didn't find - query, client name ('' for the help +// center), searches, days ago first and last. +// ------------------------------ +function demoKbSearchMisses() { + return [ + ['guest wifi password', 'Ravenwood Dental Group', 6, 70, 3], + ['scan to email', 'Kestrel Precision Manufacturing', 4, 52, 9], + ['out of office', 'Blackburn and Meyer LLP', 3, 40, 12], + ['voicemail pin', 'Harbor Point Credit Union', 2, 33, 18], + ['vpn', 'Sinclair Property Group', 5, 61, 2], + ['new starter form', 'Delaney Construction', 2, 25, 11], + ['chromebook', 'Summit Ridge Charter School', 7, 80, 1], + ['shared calendar', 'Ironbridge Architects', 2, 20, 6], + ['remote support', '', 9, 85, 1], + ['pricing', '', 4, 60, 8], + ]; +} + +// ------------------------------ +// demoBuildKnowledgeBase +// The demo's Knowledge Base articles (demoDataKbArticles()) that aren't here +// - each with who can read it, its tags, older versions, reads and feedback, +// and a reply on the demo tickets it answers linking to it - and the +// searches that found nothing. Once each: an article already here, and a +// search already logged, is left alone. +// ------------------------------ +function demoBuildKnowledgeBase($mysqli, $context, &$counts) { + + if (!mysqli_num_rows(mysqli_query($mysqli, "SHOW TABLES LIKE 'kb_articles'"))) { + return; + } + + $user_id = $context['user_id']; + $clients = array_flip(array_map('mb_strtolower', demoDataClients($mysqli))); + $here = demoKbArticleIds($mysqli); + + foreach (demoDataKbArticles() as $index => $article) { + if (isset($here[$article['name'] . '|' . $article['description']])) { + continue; + } + + // Months ago, as days - so nothing lands past today whatever day of the month it is + $made = demoDateTime($article['made'] * 30 + 2 + $index % 9, 10, ($index * 7) % 60); + $audience = $article['audience']; + $kind = isset($audience[0]) ? $audience[0] : (isset($audience['tags']) ? 'tags' : 'clients'); + $published = $kind !== 'draft'; + $visibility = ['all' => 'clients', 'tags' => 'clients', 'clients' => 'clients', 'public' => 'public'][$kind] ?? 'agents'; + $versions = $article['versions']; + krsort($versions); + + // What it says now, and when it last changed - the newest of its versions is when it was last edited + $updated = $versions ? demoDateTime(max(1, min(array_keys($versions)) * 30 - 20), 14, 30) : null; + $category_id = demoKbCategoryId($mysqli, $article['category']); + $fields = [ + 'kb_article_title' => $article['name'], + 'kb_article_summary' => $article['description'], + 'kb_article_content' => $article['content'], + 'kb_article_content_raw' => kbArticleContentRaw($article['name'], $article['description'], $article['content']), + 'kb_article_category_id' => $category_id, + 'kb_article_visibility' => $visibility, + 'kb_article_all_clients' => $kind === 'all' ? 1 : 0, + 'kb_article_review_months' => intval($article['review']), + 'kb_article_views' => intval($article['views']), + 'kb_article_created_at' => $made, + 'kb_article_created_by' => $user_id, + ]; + if ($published) { + $fields['kb_article_published_at'] = date('Y-m-d H:i:s', strtotime($made . ' +2 hours')); + } + if ($updated) { + $fields['kb_article_updated_at'] = $updated; + $fields['kb_article_updated_by'] = $user_id; + } + if ($article['reviewed'] !== null) { + $fields['kb_article_reviewed_at'] = demoDateTime($article['reviewed'] * 30 + 3, 11, 0); + $fields['kb_article_reviewed_by'] = $user_id; + } + if ($article['archived'] !== null) { + $fields['kb_article_archived_at'] = demoDateTime($article['archived'] * 30 + 1, 16, 0); + } + $kb_article_id = starterInsert($mysqli, 'kb_articles', $fields, ['kb_article_content']); + $counts['kb']++; + + // Who it is for + if ($kind === 'tags') { + demoAttachTags($mysqli, 'kb_article_client_tags', 'kb_article_id', 'tag_id', $kb_article_id, 1, $audience['tags']); + } + $readers = []; + if ($kind === 'clients') { + foreach ($audience['clients'] as $client_name) { + $client_id = intval($clients[mb_strtolower($client_name)] ?? 0); + if ($client_id) { + demoLink($mysqli, 'kb_article_clients', 'kb_article_id', $kb_article_id, 'client_id', $client_id); + } + } + } + demoAttachTags($mysqli, 'kb_article_tags', 'kb_article_id', 'tag_id', $kb_article_id, 13, $article['tags']); + + // What it said before, oldest first - each dated when it was written, the first when the article was + $first = true; + foreach ($versions as $months_ago => $version) { + starterInsert($mysqli, 'kb_article_versions', [ + 'kb_article_version_title' => $article['name'], + 'kb_article_version_summary' => $version[0], + 'kb_article_version_content' => $version[1], + 'kb_article_version_created_at' => $first ? $made : demoDateTime($months_ago * 30 + 5, 10, 0), + 'kb_article_version_created_by' => $user_id, + 'kb_article_version_kb_article_id' => $kb_article_id, + ], ['kb_article_version_content']); + $first = false; + } + + // What its readers said - portal contacts of clients who can read it, or visitors to the help center + if ($published && $article['feedback'] && demoKbTablesReady($mysqli)) { + $contacts = []; + $sql = mysqli_query($mysqli, "SELECT contact_id, contact_client_id FROM contacts + WHERE contact_archived_at IS NULL AND contact_email <> '' AND contact_client_id IN (" . implode(',', array_map('intval', $clients ? array_values($clients) : [0])) . ") + ORDER BY contact_id"); + while ($row = mysqli_fetch_row($sql)) { + $contacts[] = [intval($row[0]), intval($row[1])]; + } + $readable = demoKbReadableClients($mysqli, $kb_article_id); + $contacts = array_values(array_filter($contacts, function ($contact) use ($readable) { + return isset($readable[$contact[1]]); + })); + foreach ($article['feedback'] as $n => $feedback) { + $public = ($feedback[2] ?? '') === 'public'; + if (!$public && !$contacts) { + continue; + } + $contact = $public ? [0, 0] : $contacts[($index * 5 + $n * 3) % count($contacts)]; + $at = demoDateTime(max(1, 3 + (($index * 11 + $n * 17) % 150)), 9 + $n % 8, ($n * 13) % 60); + if (strtotime($at) < strtotime($made)) { + $at = date('Y-m-d H:i:s', strtotime($made . " +" . ($n + 1) . " days")); + } + $row = [ + 'kb_article_feedback_kb_article_id' => $kb_article_id, + 'kb_article_feedback_helpful' => intval($feedback[0]), + 'kb_article_feedback_source' => $public ? 'public' : 'portal', + 'kb_article_feedback_contact_id' => $contact[0], + 'kb_article_feedback_client_id' => $contact[1], + 'kb_article_feedback_created_at' => $at, + ]; + if ($public) { + $row['kb_article_feedback_ip'] = '203.0.113.' . (10 + ($index * 7 + $n) % 200); + } + if ($feedback[1] !== '') { + $row['kb_article_feedback_comment'] = $feedback[1]; + } + // Some of the "no"s have been looked at + if (!$feedback[0] && $index % 2 === 0) { + $row['kb_article_feedback_dealt_at'] = date('Y-m-d H:i:s', strtotime($at . ' +1 day')); + $row['kb_article_feedback_dealt_by'] = $user_id; + } + starterInsert($mysqli, 'kb_article_feedback', $row); + } + } + + // The demo tickets it answers, after it went out, get a reply linking to it + if ($published && $article['tickets'] && $article['archived'] === null) { + $readable = $kind === 'public' ? null : demoKbReadableClients($mysqli, $kb_article_id); + $url = $kind === 'public' ? kbPublicUrl($kb_article_id, $article['name']) : kbPortalArticleUrl($kb_article_id); + $subjects = implode(', ', array_map(function ($subject) { + return "'" . escapeSql($subject) . "'"; + }, $article['tickets'])); + $sql = mysqli_query($mysqli, "SELECT ticket_id, ticket_client_id, ticket_created_at, ticket_resolved_at FROM tickets + WHERE ticket_subject IN ($subjects) AND ticket_created_at > '" . $fields['kb_article_published_at'] . "' + AND ticket_client_id IN (" . implode(',', array_map('intval', $clients ? array_values($clients) : [0])) . ")"); + while ($ticket = mysqli_fetch_assoc($sql)) { + if ($readable !== null && !isset($readable[intval($ticket['ticket_client_id'])])) { + continue; + } + $at = strtotime($ticket['ticket_created_at'] . ' +25 minutes'); + if (!empty($ticket['ticket_resolved_at']) && $at >= strtotime($ticket['ticket_resolved_at'])) { + $at = (strtotime($ticket['ticket_created_at']) + strtotime($ticket['ticket_resolved_at'])) / 2; + } + starterInsert($mysqli, 'ticket_replies', [ + 'ticket_reply' => '

This walks through it step by step, for next time:

' . escapeHtml($article['name']) . '

', + 'ticket_reply_type' => 'Public', + 'ticket_reply_by' => $user_id, + 'ticket_reply_ticket_id' => intval($ticket['ticket_id']), + 'ticket_reply_created_at' => date('Y-m-d H:i:s', intval($at)), + ], ['ticket_reply']); + } + } + } + + // What was searched for and not found + if (demoKbTablesReady($mysqli)) { + foreach (demoKbSearchMisses() as $miss) { + $client_id = $miss[1] === '' ? 0 : intval($clients[mb_strtolower($miss[1])] ?? 0); + if ($miss[1] !== '' && !$client_id) { + continue; + } + mysqli_query($mysqli, "INSERT IGNORE INTO kb_search_misses SET kb_search_miss_query = '" . escapeSql($miss[0]) . "', + kb_search_miss_source = '" . ($client_id ? 'portal' : 'public') . "', kb_search_miss_client_id = $client_id, + kb_search_miss_searches = " . intval($miss[2]) . ", kb_search_miss_first_at = '" . demoDateTime($miss[3], 10, 15) . "', + kb_search_miss_last_at = '" . demoDateTime($miss[4], 14, 40) . "'"); + } + } +} + +// The demo clients who can read an article - [client_id => true] (kbClientSql(), whether or not it is published). +function demoKbReadableClients($mysqli, $kb_article_id) { + $out = []; + $kb_article_id = intval($kb_article_id); + $clients = demoDataClients($mysqli); + foreach (array_keys($clients) as $client_id) { + $client_id = intval($client_id); + $sql = "SELECT 1 FROM kb_articles WHERE kb_article_id = $kb_article_id AND (kb_article_visibility = 'public' OR (kb_article_visibility = 'clients' AND (kb_article_all_clients = 1 + OR EXISTS (SELECT 1 FROM kb_article_clients kc WHERE kc.kb_article_id = kb_articles.kb_article_id AND kc.client_id = $client_id) + OR EXISTS (SELECT 1 FROM kb_article_client_tags kt JOIN client_tags ct ON ct.tag_id = kt.tag_id WHERE kt.kb_article_id = kb_articles.kb_article_id AND ct.client_id = $client_id))))"; + if (mysqli_num_rows(mysqli_query($mysqli, $sql))) { + $out[$client_id] = true; + } + } + return $out; +} + +// Has the database the Knowledge Base's feedback and search tables (database 3.9.7)? Asked of the tables - the demo loads with the module off too. +function demoKbTablesReady($mysqli) { + static $ready = null; + return $ready ?? ($ready = mysqli_num_rows(mysqli_query($mysqli, "SHOW TABLES LIKE 'kb_search_misses'")) > 0); +} + // ------------------------------ function demoDataSpecs() { return [ diff --git a/admin/post/starter_content.php b/admin/post/starter_content.php index 6408a6b58..b42d9f10a 100644 --- a/admin/post/starter_content.php +++ b/admin/post/starter_content.php @@ -182,6 +182,26 @@ if (isset($_POST['update_starter_vendor_templates'])) { } +if (isset($_POST['update_starter_kb_articles'])) { + + // The starter Knowledge Base articles already here, brought up to this version + validateCSRFToken(); + + require_once 'starter_content_model.php'; + + $counts = starterUpdateKbArticles(); + + if ($counts['replaced']) { + logAudit("Starter Content", "Edit", "$session_name brought {$counts['replaced']} starter Knowledge Base articles up to date"); + flashAlert("Brought {$counts['replaced']} starter Knowledge Base articles up to date - any whose words changed keep what they said before in their versions"); + } else { + flashAlert("None of the starter Knowledge Base articles are here to update - add them instead", 'info'); + } + + redirect(); + +} + if (isset($_POST['update_starter_license_templates'])) { // The starter license templates already here, brought up to this version @@ -210,12 +230,15 @@ if (isset($_POST['load_demo_data'])) { $counts = demoDataLoad($mysqli); - if (!$counts['clients']) { + if (!$counts['clients'] && !$counts['kb']) { flashAlert("Nothing to add - every demo client is already here", 'info'); redirect(); } - $summary = "{$counts['clients']} clients, {$counts['contacts']} contacts, {$counts['assets']} assets, {$counts['documentation']} documentation records, {$counts['tickets']} tickets, {$counts['projects']} projects, {$counts['billing']} billing records, {$counts['company']} company records"; + $summary = $counts['clients'] ? "{$counts['clients']} clients, {$counts['contacts']} contacts, {$counts['assets']} assets, {$counts['documentation']} documentation records, {$counts['tickets']} tickets, {$counts['projects']} projects, {$counts['billing']} billing records, {$counts['company']} company records" : ''; + if ($counts['kb']) { + $summary .= ($summary !== '' ? ', ' : '') . "{$counts['kb']} Knowledge Base articles"; + } logAudit("Demo Data", "Create", "$session_name loaded demo data - $summary"); diff --git a/admin/post/starter_content_model.php b/admin/post/starter_content_model.php index 991f40142..46a98bd39 100644 --- a/admin/post/starter_content_model.php +++ b/admin/post/starter_content_model.php @@ -25,12 +25,12 @@ function starterContentPacks() { 'categories' => [ 'label' => 'Categories', 'icon' => 'fa-list-ul', - 'description' => 'Expense, income, referral and ticket categories for an MSP. Income categories are also what products are filed under.', + 'description' => 'Expense, income, referral, ticket and Knowledge Base categories for an MSP. Income categories are also what products are filed under.', ], 'tags' => [ 'label' => 'Tags', 'icon' => 'fa-tags', - 'description' => 'Tags for clients, locations, contacts, credentials, assets, vendors, domains, licenses, services, networks, documents and tickets.', + 'description' => 'Tags for clients, locations, contacts, credentials, assets, vendors, domains, licenses, services, networks, documents, tickets and Knowledge Base articles.', ], 'ticket_templates' => [ 'label' => 'Ticket Templates', @@ -56,6 +56,16 @@ function starterContentPacks() { 'confirm' => 'Bring the %d starter canned responses you have up to date? What they say, where they are offered and what they set up are replaced with this version - changes you made to them are lost. How often they have been used stays.', ], ], + 'kb_articles' => [ + 'label' => 'Knowledge Base Articles', + 'icon' => 'fa-book', + 'description' => "How-tos and fixes clients ask for again and again - resetting a password, setting up MFA, reporting phishing, Outlook, OneDrive, the VPN, printers, Wi-Fi - each filed under its Knowledge Base category with its tags, and reviewed once a year. They come in as drafts only your team can see, ending with how to reach you from Company Details: read each, make it say what your clients use, then publish it to the clients it suits.", + 'requires' => 'categories', + 'update' => [ + 'button' => 'update_starter_kb_articles', + 'confirm' => 'Bring the %d starter Knowledge Base articles you have up to date? Their summary, what they say, category and review period are replaced with this version - what they said before is kept as a version, so changes you made can be put back. Whether they are published, who can read them, their tags, reads and feedback stay as they are.', + ], + ], 'vendor_templates' => [ 'label' => 'Vendor Templates', 'icon' => 'fa-building', @@ -218,6 +228,8 @@ function starterContentLoad($mysqli, $pack, $dry_run = false, $only = null) { return starterLoadProjectTemplates($mysqli, $dry_run, $only); case 'canned_responses': return starterLoadCannedResponses($mysqli, $dry_run, $only); + case 'kb_articles': + return starterLoadKbArticles($mysqli, $dry_run, $only); case 'vendor_templates': return starterLoadVendorTemplates($mysqli, $dry_run, $only); case 'document_templates': @@ -246,6 +258,8 @@ function starterContentRows($pack) { return starterContentProjectTemplates(); case 'canned_responses': return starterContentCannedResponses(); + case 'kb_articles': + return starterContentKbArticles(); case 'vendor_templates': return starterContentVendorTemplates(); case 'document_templates': @@ -294,6 +308,8 @@ function starterItemGroup($pack, $row) { return function_exists('tagEntityByType') ? (string) (tagEntityByType($row[0])['title'] ?? '') : ''; case 'products': return (string) $row[4]; + case 'kb_articles': + return (string) $row['category']; } return ''; } @@ -340,7 +356,8 @@ function starterContentItems($mysqli, $pack) { default: $tables = ['ticket_templates' => ['ticket_templates', 'ticket_template_name'], 'project_templates' => ['project_templates', 'project_template_name'], 'vendor_templates' => ['vendor_templates', 'vendor_template_name'], 'document_templates' => ['document_templates', 'document_template_name'], - 'products' => ['products', 'product_name'], 'license_templates' => ['software_templates', 'software_template_name']]; + 'products' => ['products', 'product_name'], 'license_templates' => ['software_templates', 'software_template_name'], + 'kb_articles' => ['kb_articles', 'kb_article_title']]; if (!isset($tables[$pack])) { return []; } @@ -376,6 +393,7 @@ function starterPackRecords($pack) { 'document_templates' => ['table' => 'document_templates', 'id' => 'document_template_id', 'name' => 'document_template_name', 'archived' => 'document_template_archived_at'], 'products' => ['table' => 'products', 'id' => 'product_id', 'name' => 'product_name', 'archived' => 'product_archived_at', 'kind' => 'product_code'], 'license_templates' => ['table' => 'software_templates', 'id' => 'software_template_id', 'name' => 'software_template_name', 'archived' => 'software_template_archived_at'], + 'kb_articles' => ['table' => 'kb_articles', 'id' => 'kb_article_id', 'name' => 'kb_article_title', 'archived' => 'kb_article_archived_at'], ]; return $packs[$pack] ?? null; } @@ -445,7 +463,7 @@ function starterPackUsed($mysqli, $pack, array $ids) { switch ($pack) { case 'categories': // What Admin > Categories counts for each kind, and what it doesn't - foreach (['Expense', 'Income', 'Referral', 'Ticket'] as $kind) { + foreach (['Expense', 'Income', 'Referral', 'Ticket', 'kb'] as $kind) { foreach (array_keys(categoryUsage($kind)) as $category_id) { $used[intval($category_id)] = true; } @@ -519,6 +537,14 @@ function starterPackUsed($mysqli, $pack, array $ids) { case 'license_templates': $queries = ["SELECT software_template_id FROM software WHERE software_template_id IN ($in)"]; break; + case 'kb_articles': + // Published, read, reviewed, reworded (it has versions) or answered - anything more than the draft it came in as + $queries = [ + "SELECT kb_article_id FROM kb_articles WHERE kb_article_id IN ($in) AND (kb_article_published_at IS NOT NULL OR kb_article_views > 0 OR kb_article_reviewed_at IS NOT NULL)", + "SELECT kb_article_version_kb_article_id FROM kb_article_versions WHERE kb_article_version_kb_article_id IN ($in)", + "SELECT kb_article_feedback_kb_article_id FROM kb_article_feedback WHERE kb_article_feedback_kb_article_id IN ($in)", + ]; + break; } foreach ($queries as $query) { $sql = mysqli_query($mysqli, str_replace('SELECT ', 'SELECT DISTINCT ', $query)); @@ -615,6 +641,8 @@ function starterContentTotal($pack) { return count(starterContentProjectTemplates()); case 'canned_responses': return count(starterContentCannedResponses()); + case 'kb_articles': + return count(starterContentKbArticles()); case 'vendor_templates': return count(starterContentVendorTemplates()); case 'document_templates': @@ -885,6 +913,139 @@ function starterUpdateLicenseTemplates() { return softwareTemplatesImport($templates, 'replace', true); } +// ------------------------------ +// starterLoadKbArticles +// As drafts only agents can read, each with its Knowledge Base category and +// tags - those of the Categories and Tags packs, so one that isn't here +// leaves the article without it. One whose title an article here already +// has, archived or not, is left alone. How to reach you is filled in from +// Company Details as they are now (starterKbFill()). +// ------------------------------ +function starterLoadKbArticles($mysqli, $dry_run = false, $only = null) { + $existing = starterExistingNames($mysqli, 'kb_articles', 'kb_article_title'); + $added = 0; + + foreach (starterOnly('kb_articles', starterContentKbArticles(), $only) as $article) { + if (isset($existing[mb_strtolower($article['name'])])) { + continue; + } + $added++; + if ($dry_run) { + continue; + } + $kb_article_id = kbArticleSave(starterKbFields($mysqli, $article) + ['published' => false, 'visibility' => 'agents', 'all_clients' => false, 'client_tag_ids' => [], 'client_ids' => []]); + starterKbTags($mysqli, $kb_article_id, $article['tags']); + $existing[mb_strtolower($article['name'])] = true; + } + + return $added; +} + +// ------------------------------ +// starterUpdateKbArticles +// The starter articles here, not archived, brought up to this library's +// version - their summary, what they say, category (when it is here) and +// review period. What one said before is kept as a version, as any edit's +// is; one that already says this is left untouched. Whether they are +// published, who can read them, their reads and feedback stay, and they gain +// the library's tags they haven't got. Returns ['replaced' => n]. +// ------------------------------ +function starterUpdateKbArticles() { + global $mysqli; + + $here = starterPackHere($mysqli, 'kb_articles'); + $replaced = 0; + foreach (starterContentKbArticles() as $article) { + $row = kbArticleRow($here[mb_strtolower($article['name'])] ?? 0); + if (!$row) { + continue; + } + $fields = starterKbFields($mysqli, $article); + $fields['title'] = $row['kb_article_title']; + $fields['category_id'] = $fields['category_id'] ?: intval($row['kb_article_category_id']); + if ($fields['summary'] !== (string) $row['kb_article_summary'] || $fields['content'] !== (string) $row['kb_article_content'] + || $fields['category_id'] !== intval($row['kb_article_category_id']) || $fields['review_months'] !== intval($row['kb_article_review_months'])) { + kbArticleSave($fields + ['published' => !empty($row['kb_article_published_at'])] + kbAudienceFields($row), $row); + } + starterKbTags($mysqli, $row['kb_article_id'], $article['tags']); + $replaced++; + } + + return ['replaced' => $replaced]; +} + +// ------------------------------ +// starterKbFields +// A library article as kbArticleSave() takes it - its category this +// install's Knowledge Base category of that name (0 when there is none), and +// what it says filled in (starterKbFill()). +// ------------------------------ +function starterKbFields($mysqli, array $article) { + return [ + 'title' => $article['name'], + 'summary' => $article['description'], + 'category_id' => starterCategoryId($mysqli, $article['category'], 'kb'), + 'review_months' => intval($article['review_months']), + 'content' => starterKbFill($article['content']), + ]; +} + +// ------------------------------ +// starterKbTags +// Puts the Knowledge Base article tags of these names on an article - the +// ones here and not archived, and not on it already. +// ------------------------------ +function starterKbTags($mysqli, $kb_article_id, array $names) { + $kb_article_id = intval($kb_article_id); + if (!$kb_article_id || !$names) { + return; + } + $names_sql = implode(', ', array_map(function ($name) { + return "'" . escapeSql(mb_strtolower($name)) . "'"; + }, $names)); + $sql = mysqli_query($mysqli, "SELECT tag_id FROM tags WHERE tag_type = 13 AND tag_archived_at IS NULL AND LOWER(tag_name) IN ($names_sql)"); + while ($row = mysqli_fetch_row($sql)) { + mysqli_query($mysqli, "INSERT IGNORE INTO kb_article_tags SET kb_article_id = $kb_article_id, tag_id = " . intval($row[0])); + } +} + +// ------------------------------ +// starterKbFill +// A starter article's [Portal] and [Contact us] filled in from this install: +// a link to the client portal (words alone when the portal is off), and a +// closing line saying how to reach you - open a ticket in the portal, the +// address tickets are emailed from (or the company's), and the company's +// phone, from Company Details as they are now. +// ------------------------------ +function starterKbFill($html) { + global $config_base_url, $config_ticket_from_email; + + $company = billingCompany(); + $portal_on = function_exists('moduleOn') && moduleOn('portal') && !empty($config_base_url); + $portal_url = $portal_on ? 'https://' . $config_base_url . '/client/' : ''; + $portal = $portal_on ? 'the client portal' : 'the client portal'; + + $ways = []; + if ($portal_on) { + $ways[] = 'open a ticket in ' . $portal; + } + $email = trim((string) ($config_ticket_from_email ?? '')) ?: trim((string) ($company['company_email'] ?? '')); + if ($email !== '') { + $ways[] = 'email ' . escapeHtml($email) . ''; + } + if (($company['phone_display'] ?? '') !== '') { + $ways[] = 'call ' . escapeHtml($company['phone_display']); + } + if ($ways) { + $last = array_pop($ways); + $contact = '

Still stuck? ' . ucfirst($ways ? implode(', ', $ways) . ' or ' . $last : $last) . ' and we will take it from there.

'; + } else { + $contact = '

Still stuck? Get in touch with us and we will take it from there.

'; + } + + return str_replace(['[Portal]', '[Contact us]'], [$portal, $contact], (string) $html); +} + // ------------------------------ // starterLoadProducts // Products are filed under income categories. A category that is not present @@ -1034,6 +1195,22 @@ function starterContentCategories() { ['Other', '#343a40', 'fa-question-circle', 'Does not fit any standard category'], ]; + // How Knowledge Base articles are grouped - an article's icon is its category's + $kb_categories = [ + ['Getting Help', '#007bff', 'fa-life-ring', 'Reaching the help desk, the client portal and support hours'], + ['Accounts and Passwords', '#ffc107', 'fa-key', 'Signing in, passwords and multi-factor authentication'], + ['Email and Calendar', '#fd7e14', 'fa-envelope', 'Outlook, mailboxes, calendars and shared mail'], + ['Files and Sharing', '#20c997', 'fa-folder-open', 'OneDrive, SharePoint, shared drives and sending files'], + ['Security', '#dc3545', 'fa-shield-alt', 'Phishing, lost devices and keeping data safe'], + ['Remote Work', '#6f42c1', 'fa-laptop-house', 'The VPN, working from home and traveling'], + ['Printing and Scanning', '#6c757d', 'fa-print', 'Printers, scanners and copiers'], + ['Phones and Meetings', '#28a745', 'fa-headset', 'Desk phones, voicemail and video meetings'], + ['Devices', '#17a2b8', 'fa-laptop', 'Computers, phones and tablets, and keeping them up to date'], + ['Network and Wi-Fi', '#6610f2', 'fa-wifi', 'The office and guest Wi-Fi, and the internet connection'], + ['Policies', '#001f3f', 'fa-clipboard-check', 'How we work together - new starters, leavers and acceptable use'], + ['Internal Procedures', '#343a40', 'fa-user-shield', 'How your team does things - kept to agents'], + ]; + $categories = []; $simple_types = [ @@ -1054,17 +1231,19 @@ function starterContentCategories() { } } - $order = 1; - foreach ($ticket_categories as $row) { - $categories[] = [ - 'type' => 'Ticket', - 'name' => $row[0], - 'color' => $row[1], - 'icon' => $row[2], - 'description' => $row[3], - 'order' => $order, - ]; - $order++; + foreach (['Ticket' => $ticket_categories, 'kb' => $kb_categories] as $type => $rows) { + $order = 1; + foreach ($rows as $row) { + $categories[] = [ + 'type' => $type, + 'name' => $row[0], + 'color' => $row[1], + 'icon' => $row[2], + 'description' => $row[3], + 'order' => $order, + ]; + $order++; + } } return $categories; @@ -1074,7 +1253,8 @@ function starterContentCategories() { // ------------------------------ // starterContentTags // tag_type 1 Client, 2 Location, 3 Contact, 4 Credential, 5 Asset, 6 Vendor, 7 Domain, -// 8 License, 9 Service, 10 Network, 11 Document, 12 Ticket - tagKinds() in functions/tags.php. +// 8 License, 9 Service, 10 Network, 11 Document, 12 Ticket, 13 Knowledge Base article - tagKinds() +// in functions/tags.php. // tag_icon is stored without the fa- prefix, the views add it. // ------------------------------ function starterContentTags() { @@ -1220,6 +1400,18 @@ function starterContentTags() { [12, 'Warranty Claim', '#28a745', 'certificate'], [12, 'Waiting on Vendor', '#ffc107', 'hourglass-half'], [12, 'Security', '#343a40', 'shield-alt'], + + // Knowledge Base article + [13, 'How-To', '#007bff', 'list-ol'], + [13, 'Troubleshooting', '#fd7e14', 'wrench'], + [13, 'Quick Fix', '#ffc107', 'bolt'], + [13, 'Self-Service', '#28a745', 'hand-pointer'], + [13, 'Security', '#dc3545', 'shield-alt'], + [13, 'Policy', '#001f3f', 'gavel'], + [13, 'Microsoft 365', '#0078d4', 'cloud'], + [13, 'Mobile', '#17a2b8', 'mobile-alt'], + [13, 'New Starter', '#20c997', 'user-plus'], + [13, 'Known Issue', '#d81b60', 'exclamation-triangle'], ]; return $tags; @@ -2469,3 +2661,378 @@ function starterContentLicenseTemplates() { ]; } + +// ------------------------------ +// starterContentKbArticles +// How-tos and fixes for an MSP's clients - name (the title), description (the +// line under it), category (a Knowledge Base category of the Categories +// pack), tags (Knowledge Base article tags of the Tags pack), review_months +// and content (HTML). Written as the MSP, to its clients' staff, for +// Microsoft 365 and Windows as most clients have them - each says where to +// put what yours differs in. [Portal] and [Contact us] are filled in as each +// comes in (starterKbFill()). +// ------------------------------ +function starterContentKbArticles() { + + $steps = function (array $items) { + return '
  1. ' . implode('
  2. ', $items) . '
'; + }; + $list = function (array $items) { + return '
  • ' . implode('
  • ', $items) . '
'; + }; + $article = function ($name, $description, $category, array $tags, $content, $review_months = 12) { + return ['name' => $name, 'description' => $description, 'category' => $category, 'tags' => $tags, 'review_months' => $review_months, 'content' => $content . '[Contact us]']; + }; + + return [ + + // Getting Help + $article('Getting help from the help desk', 'How to reach us, what to tell us so we can help straight away, and what happens next.', 'Getting Help', ['How-To'], + '

The quickest way to get help is to open a ticket in [Portal] - it reaches the whole team, and you can follow it as we work on it. Email works too, and for anything stopping you from working, call us.

' + . '
Tell us
' . $list([ + 'What you were trying to do, and what happened instead - the exact wording of any error helps a lot (a screenshot is even better)', + 'When it started, and whether anything changed around then', + 'Whether it is just you, or others too', + 'The best number to reach you on, and when you are free', + ]) + . '
What happens next

You get an email with the ticket\'s number straight away. Reply to that email to add anything - keep the number in the subject so it lands on the same ticket. We let you know when someone has picked it up, when we need something from you, and when it is fixed.

' + . '

If something is urgent - you can\'t work, or several people are affected - say so, and call as well as opening the ticket.

'), + + $article('Raising a ticket in the client portal', 'Sign in to the client portal, open a ticket and follow it as we work on it.', 'Getting Help', ['How-To', 'Self-Service'], + '

The client portal is where you open tickets, see what is happening with them and reply to us. It is quicker than email, and nothing gets lost in an inbox.

' + . $steps([ + 'Go to [Portal] and sign in with your work email address. The first time, use Forgot your password? to set one.', + 'Choose New Ticket.', + 'Give it a subject that says what is wrong - "Outlook won\'t open on my laptop" helps more than "Problem".', + 'Say what happened, when it started and anything you have tried. Add a screenshot if you have one.', + 'Choose how urgent it is, then Submit.', + ]) + . '

While you type the subject, the portal suggests articles that might answer it - worth a look, you may not have to wait for us at all.

' + . '

Your tickets are under Tickets. Open one to see where it is up to and to reply. When we mark it resolved, you can reply to reopen it if it isn\'t fixed.

'), + + // Accounts and Passwords + $article('Changing or resetting your Microsoft 365 password', 'Change your password yourself, reset it when you have forgotten it, and what to do when you are locked out.', 'Accounts and Passwords', ['How-To', 'Self-Service', 'Microsoft 365'], + '
Change it while you know it
' . $steps([ + 'Sign in at myaccount.microsoft.com.', + 'Choose Password (or Change password).', + 'Type your old password, then the new one twice, and save.', + ]) + . '
Forgotten it
' . $steps([ + 'Go to passwordreset.microsoftonline.com.', + 'Enter your work email address and the characters shown.', + 'Prove it is you with your authenticator app, a text or a call, as you set up when you registered.', + 'Choose a new password.', + ]) + . '

On a work computer, sign in with the new password straight away. Your phone and other devices will ask for it next time they check email - type it in when they do.

' + . '
Locked out

After too many wrong attempts your account locks for a while. Wait 15 minutes and try again, or use the reset above. If self-service reset isn\'t set up for you, we can reset it - we will check it is really you first, so expect a call back.

' + . '

Never send your password to anyone by email or in a ticket - we will never ask for it.

'), + + $article('Setting up multi-factor authentication', 'Register the Microsoft Authenticator app so signing in needs your phone as well as your password.', 'Accounts and Passwords', ['How-To', 'Security', 'Microsoft 365', 'Mobile'], + '

Multi-factor authentication (MFA) means that signing in takes your password and a tap on your phone. Even if someone gets your password, they can\'t get in without your phone.

' + . '
You need
' . $list(['Your phone, with the Microsoft Authenticator app installed from the App Store or Google Play', 'A computer, signed in to your work account']) + . '
Set it up
' . $steps([ + 'On the computer, go to aka.ms/mfasetup and sign in.', + 'When asked to keep your account secure, choose Next until a QR code shows.', + 'In the Authenticator app, tap +, choose Work or school account, then Scan a QR code, and scan it.', + 'Back on the computer, choose Next. A test notification arrives on your phone - type the number shown on screen into the app and approve it.', + 'Add your phone number as a backup method when asked.', + ]) + . '

From now on, when you sign in somewhere new you are asked to approve it on your phone.

' + . '

Only approve a sign-in you have just started yourself. If your phone asks you to approve one you didn\'t start, deny it and tell us straight away - someone has your password.

'), + + $article('Moving your authenticator to a new phone', 'Get multi-factor sign-in onto a new phone before you wipe or trade in the old one.', 'Accounts and Passwords', ['How-To', 'Mobile', 'Microsoft 365'], + '

Do this while you still have the old phone - without it, you won\'t be able to sign in until we reset your methods.

' + . $steps([ + 'Install Microsoft Authenticator on the new phone.', + 'On a computer, go to mysignins.microsoft.com/security-info and sign in, approving on the old phone.', + 'Choose Add sign-in method, then Authenticator app, and follow the steps with the new phone to scan the QR code.', + 'Make the new phone the default method if asked.', + 'Delete the old phone\'s entry from the list, then remove the account from the app on the old phone.', + 'If your phone number changed, update it on the same page.', + ]) + . '
Already lost or wiped the old phone

Contact us. We will check it is really you, clear your old methods, and you set the new phone up the next time you sign in.

'), + + $article('Choosing a strong password and using a password manager', 'How to pick passwords that are hard to guess and easy to remember, and why a password manager helps.', 'Accounts and Passwords', ['Security'], + '

Most account break-ins use passwords that were guessed or leaked from another website. Two habits stop nearly all of them.

' + . '
Use a passphrase

Three or four random words make a password that is long, strong and easy to remember - copper-lantern-river-oak is far harder to crack than P@ssw0rd1. Don\'t use names, dates, or anything someone could find on your social media.

' + . '
Never reuse it

Every website gets its own password. When one site is breached, criminals try the same email and password everywhere else.

' + . '
Let a password manager remember them
' . $list([ + 'It remembers a different strong password for every site, and fills them in for you', + 'You only remember one passphrase - the one that unlocks it', + 'It only fills a password in on the real website, so it helps you spot fake ones', + ]) + . '

Ask us which password manager we support for your business before you put work passwords in a personal one.

'), + + // Security + $article('Spotting and reporting a phishing email', 'The signs of a phishing email, and how to report one without clicking anything.', 'Security', ['Security', 'How-To'], + '

Phishing emails pretend to be from someone you trust to get you to click a link, open an attachment, enter your password or pay something.

' + . '
Warning signs
' . $list([ + 'It is urgent or threatening - your account will be closed, a payment is overdue, act now', + 'The sender\'s address doesn\'t match who it says it is from - hover over the name to see the real address', + 'A link\'s address, shown when you hover over it, goes somewhere unexpected', + 'It asks you to sign in, pay, change bank details or buy gift cards', + 'An attachment you weren\'t expecting, even from someone you know', + 'A warning banner saying it is from outside the company, when it claims to be from inside', + ]) + . '
Report it
' . $steps([ + 'Don\'t click links, open attachments or reply.', + 'In Outlook, use Report (or Report Phishing) on the toolbar - or forward it to us as an attachment.', + 'Delete it.', + ]) + . '

Not sure? Ask us before you click - we would much rather check ten genuine emails than clean up after one bad one. If someone asks you to change bank details or make an urgent payment, call them on a number you already have to check.

'), + + $article('I clicked a link or entered my password - what now?', 'What to do straight away if you think you fell for a phishing email.', 'Security', ['Security', 'Quick Fix'], + '

It happens to everyone. Acting quickly makes the difference, so don\'t wait to be sure.

' + . $steps([ + 'If you typed your password into a page, change it now - see Changing or resetting your Microsoft 365 password. Change it anywhere else you used the same one.', + 'If you opened an attachment or ran something, unplug the network cable or turn off Wi-Fi on that computer, but leave it switched on.', + 'Call us straight away and tell us what you clicked, when, and what happened. Keep the email - don\'t delete it.', + 'Deny any multi-factor sign-in request you didn\'t start.', + ]) + . '

We will check your account for anything changed - forwarding rules, new sign-ins, sent email - and tell you if anything else needs doing. Nobody is in trouble for reporting it; the only mistake is keeping quiet.

'), + + $article('Lost or stolen laptop or phone', 'What to do straight away when a device with work email or files on it goes missing.', 'Security', ['Security'], + '

Tell us as soon as you notice - day or night. The sooner we know, the less anyone can do with it.

' + . $steps([ + 'Call us, and say which device it is and when you last had it.', + 'If it was stolen, report it to the police and keep the reference number.', + 'Change your Microsoft 365 password from another device.', + ]) + . '

We sign the device out of your work account, and for devices we manage we can lock or wipe it remotely. If it turns up, let us know before you use it again.

'), + + // Devices + $article('Keeping your computer up to date', 'Why updates matter, what the restart reminders mean, and how to get them done without losing work.', 'Devices', ['How-To', 'Self-Service'], + '

Updates fix security holes that attackers use. We send them out to managed computers and schedule most of them for outside working hours - but many only finish when the computer restarts.

' + . '
When it asks you to restart
' . $list([ + 'Save your work and restart at the end of the day, or choose a time that suits you', + 'Don\'t keep putting it off - after a few days it restarts on its own', + 'Leave the computer on and plugged in at night when you can - most updates run then', + ]) + . '
To check yourself

On Windows, open Settings > Windows Update and choose Check for updates. On a Mac, open System Settings > General > Software Update.

' + . '

Keep your phone and tablet up to date too - install updates when they appear.

'), + + $article('Restarting your computer properly', 'Why restarting fixes so much, and why shutting down isn\'t the same.', 'Devices', ['Quick Fix', 'Troubleshooting'], + '

A restart clears out programs that have stopped responding, finishes updates and reconnects to the network. It fixes a surprising number of problems, so it is the first thing to try.

' + . $steps([ + 'Save your work and close your programs.', + 'Choose Start, the power button, then Restart - not Shut down.', + 'Wait for it to start again and sign in.', + ]) + . '

On Windows, Shut down keeps part of the system as it was so it starts faster - it doesn\'t clear things out the way Restart does. Closing a laptop\'s lid only puts it to sleep.

' + . '

If it still isn\'t right after a restart, tell us what you were doing and what you see - and that you have restarted, which saves a step.

'), + + // Email and Calendar + $article('Setting an out of office reply', 'Tell people who email you that you are away, in Outlook or on the web.', 'Email and Calendar', ['How-To', 'Self-Service', 'Microsoft 365'], + '
Outlook on the web, or the new Outlook
' . $steps([ + 'Open Settings (the gear), then Account > Automatic replies.', + 'Turn on Turn on automatic replies.', + 'Tick Send replies only during a time period and choose when you leave and when you are back.', + 'Write the message - one for people in your company, and one for everyone else if you want it to differ.', + 'Choose Save.', + ]) + . '
Classic Outlook on Windows

Choose File > Automatic Replies, then as above.

' + . '

Say when you are back and who to contact meanwhile - but keep personal details, like being on holiday abroad, out of the reply that goes outside the company.

'), + + $article('Sharing your calendar or opening someone else\'s', 'Let colleagues see when you are free, and add their calendars beside yours.', 'Email and Calendar', ['How-To', 'Microsoft 365'], + '
Share yours
' . $steps([ + 'In Outlook, open your calendar.', + 'Choose Share (or right-click your calendar and choose Sharing permissions).', + 'Add the person, and choose what they see - just when you are busy, the titles and places, or everything - or let them edit it.', + 'Choose Share. They get an email to accept.', + ]) + . '
Open someone else\'s

In your calendar choose Add calendar, then Add from directory (or Open shared calendar), and pick the person. You see what they have shared with you.

' + . '

To book a meeting without needing their calendar, use the Scheduling Assistant in a new meeting - it shows when everyone is free.

'), + + $article('Adding a shared mailbox in Outlook', 'Open a shared mailbox like info@ or accounts@ alongside your own.', 'Email and Calendar', ['How-To', 'Microsoft 365'], + '

Once we have given you access, a shared mailbox usually appears in Outlook on its own within an hour or so - restart Outlook if it hasn\'t.

' + . '
If it doesn\'t appear

Outlook on the web or the new Outlook: right-click Folders in the folder list, choose Add shared folder or mailbox and type the mailbox\'s address.

' + . '

Classic Outlook on Windows: choose File > Account Settings > Account Settings, select your account, Change > More Settings > Advanced, then Add the mailbox\'s address.

' + . '
Sending as the shared mailbox

In a new email, show the From field (under Options), choose Other email address and pick the shared mailbox. If you get an error saying you don\'t have permission, ask us - sending as a mailbox is a separate permission from reading it.

' + . '

Need access to a shared mailbox you don\'t have? Open a ticket saying which one - we check with whoever looks after it first.

'), + + $article('Outlook keeps asking for your password or won\'t sync', 'Quick fixes when Outlook prompts for a password over and over, or new email stops arriving.', 'Email and Calendar', ['Troubleshooting', 'Microsoft 365'], + '

Try these in order, checking after each one.

' + . $steps([ + 'Check you can sign in at outlook.office.com. If you can\'t, your password may have expired or your account may be locked - see Changing or resetting your Microsoft 365 password.', + 'If you changed your password recently, type the new one when Outlook asks.', + 'Close Outlook completely and open it again.', + 'Restart the computer.', + 'Check the bottom of the Outlook window - Working Offline means it isn\'t connecting. On the Send / Receive tab, turn Work Offline off.', + 'Check other websites load - if not, it is your internet connection, not Outlook.', + ]) + . '

If email works on the web but not in Outlook, tell us - your Outlook profile may need rebuilding, which we can do remotely.

'), + + // Files and Sharing + $article('Sending large files securely', 'Share files too big for email, or too sensitive for an attachment, with a OneDrive link.', 'Files and Sharing', ['How-To', 'Security', 'Microsoft 365'], + '

Email attachments are limited in size and stay in inboxes forever. A sharing link from OneDrive is better for both: no size limit, and you can stop sharing at any time.

' + . $steps([ + 'Save the file to OneDrive (or find it in SharePoint or Teams).', + 'Right-click it and choose Share.', + 'Choose who the link works for - Specific people is safest - and type their email addresses.', + 'Untick Allow editing unless they need to change it, and set an expiry date for anything sensitive.', + 'Choose Send, or Copy link to paste it into your own email.', + ]) + . '

To stop sharing later, choose Manage access on the file and remove the link.

' + . '

For bank details, ID documents or health information, check with us how your business has agreed to send them before you do.

'), + + $article('Syncing SharePoint and Teams files to your computer', 'Work on shared files from File Explorer, the same as files on your computer.', 'Files and Sharing', ['How-To', 'Microsoft 365'], + $steps([ + 'In Teams, open the channel and its Files tab, and choose Open in SharePoint - or go to the SharePoint site directly.', + 'Choose Sync (or Add shortcut to My files, which works on every computer you sign in to).', + 'Allow the browser to open OneDrive if it asks.', + 'The library appears in File Explorer under your organization\'s name, or in your OneDrive.', + ]) + . '
What the icons mean
' . $list([ + 'A cloud - the file is online only, and downloads when you open it', + 'A green tick - it is on this computer too', + 'Red with a cross - it didn\'t sync. Click the OneDrive cloud by the clock to see why', + ]) + . '

Two people editing the same Word, Excel or PowerPoint file at once is fine - open it from the shared library rather than a copy you emailed around.

'), + + $article('Getting back a deleted or overwritten file', 'Restore a file from the recycle bin, or an earlier version of one, from OneDrive or SharePoint.', 'Files and Sharing', ['How-To', 'Self-Service', 'Microsoft 365'], + '
Deleted
' . $steps([ + 'Go to office.com, open OneDrive (or the SharePoint site the file was in).', + 'Choose Recycle bin.', + 'Select the file and choose Restore.', + ]) + . '

Files stay in the recycle bin for 93 days.

' + . '
Saved over by mistake
' . $steps([ + 'Find the file in OneDrive or SharePoint on the web.', + 'Right-click it and choose Version history.', + 'Find the version from before the change and choose Restore.', + ]) + . '

Can\'t find it, or it was on a shared drive or a computer rather than OneDrive? Tell us the file\'s name, where it was and roughly when it was last right - we can restore it from backup.

'), + + // Remote Work + $article('Connecting to the VPN when you work away from the office', 'Reach the office\'s shared drives and systems securely from home or on the road.', 'Remote Work', ['How-To'], + '

The VPN connects your work computer to the office network over the internet, securely. You need it for shared drives and systems that only run in the office - email, Teams and OneDrive work without it.

' + . $steps([ + 'Connect to the internet first - home Wi-Fi, or your phone\'s hotspot.', + 'Open the VPN app from the system tray by the clock, or from the Start menu.', + 'Choose Connect and sign in with your work account, approving it on your phone.', + 'When it says connected, open your shared drives as usual.', + ]) + . '

Disconnect when you have finished, especially on a hotel or other shared Wi-Fi.

' + . '
If it won\'t connect
' . $list(['Check other websites load', 'Disconnect, wait a minute and connect again', 'Restart the computer', 'Tell us the exact error message - a screenshot is best']) + . '

Your VPN\'s name, and anything different about it, go here.

'), + + $article('Working securely from home or on the road', 'Simple habits that keep work data safe away from the office.', 'Remote Work', ['Security', 'Policy'], + $list([ + 'Lock your screen whenever you step away - press Windows + L, or Control + Command + Q on a Mac', + 'Use your work computer for work, and don\'t let family members use it', + 'Keep work files in OneDrive or SharePoint, not on the desktop or a USB stick', + 'On public or hotel Wi-Fi, connect to the VPN, or use your phone\'s hotspot instead', + 'Don\'t take calls about sensitive matters where others can hear, and watch who can see your screen', + 'Keep your home router updated and change its default password', + 'Print work documents only when you need to, and shred them afterwards', + ]) + . '

If a work device is lost or stolen, tell us straight away - see Lost or stolen laptop or phone.

'), + + // Printing and Scanning + $article('Adding a printer', 'Add an office printer to your computer, or add it again after it disappears.', 'Printing and Scanning', ['How-To'], + '

On managed computers the office printers are added for you. If one is missing:

' + . '
Windows
' . $steps([ + 'Open Settings > Bluetooth & devices > Printers & scanners.', + 'Choose Add device and wait for the list.', + 'Choose the printer by its name - often written on a label on the printer - and Add device.', + ]) + . '
Mac

Open System Settings > Printers & Scanners, choose Add Printer, Scanner or Fax, pick it from the list and choose Add.

' + . '

If it isn\'t listed, make sure you are on the office network (not guest Wi-Fi), then tell us the printer\'s name and where it is.

'), + + $article('Printer not printing', 'Quick checks before you open a ticket about a printer.', 'Printing and Scanning', ['Troubleshooting', 'Quick Fix'], + $steps([ + 'Look at the printer\'s screen - paper jams, empty trays and low toner show there.', + 'Check you sent it to the right printer - the name is in the print window.', + 'Open the print queue - Settings > Printers & scanners, the printer, Open print queue - and cancel anything stuck at the top.', + 'Turn the printer off, wait 30 seconds and turn it on again.', + 'Restart your computer.', + 'Try printing from another computer - if that works, the problem is on yours.', + ]) + . '

Still not printing? Tell us the printer\'s name, what its screen says, and whether it is just you or everyone.

'), + + $article('Scanning to email or a folder', 'Scan documents on the office copier straight to your inbox or a shared folder.', 'Printing and Scanning', ['How-To'], + $steps([ + 'Put the pages face up in the feeder on top, or face down on the glass.', + 'On the copier\'s screen, choose Scan (or Send).', + 'Choose Email and pick yourself from the address book - or choose the folder you scan to.', + 'Check the settings - PDF, color or black and white, one or both sides.', + 'Press Start.', + ]) + . '

The scan arrives in a minute or two. If it doesn\'t, check your junk email folder, then tell us the copier\'s name and the time you scanned.

' + . '

Your copier\'s name, and where scans to a folder land, go here.

'), + + // Phones and Meetings + $article('Fixing sound and video in Teams meetings', 'What to check when people can\'t hear or see you in a Teams meeting, or you can\'t hear them.', 'Phones and Meetings', ['Troubleshooting', 'Microsoft 365'], + '
Before you join

On the joining screen, check the camera preview and choose Device settings (the gear) to pick the right microphone, speaker and camera - a headset, not the laptop\'s own, if you use one.

' + . '
In the meeting
' . $steps([ + 'Check you aren\'t muted in Teams, and that your headset doesn\'t have its own mute switch on.', + 'Choose More > Settings > Device settings and check the microphone and speaker - make a test call from there.', + 'Unplug the headset and plug it in again, then pick it again in Device settings.', + 'Close other apps that might be using the camera or microphone.', + 'Leave the meeting and join again.', + ]) + . '

Choppy sound or frozen video is usually the connection - turn your camera off, move closer to the Wi-Fi, or plug in a network cable.

'), + + $article('Setting up voicemail and forwarding on your desk phone', 'Record your voicemail greeting, check messages and forward calls when you are away from your desk.', 'Phones and Meetings', ['How-To', 'Self-Service'], + '
Voicemail
' . $steps([ + 'Press the Messages (envelope) button, or dial your voicemail number.', + 'Enter your PIN - the first time, use the one we gave you and choose a new one when asked.', + 'Follow the prompts to record your name and greeting.', + ]) + . '
Forwarding

Press Forward on the phone\'s screen, enter the number to forward to, and confirm. Press it again to turn it off. Some systems let you forward from the phone\'s web portal or app instead.

' + . '

Forgotten your voicemail PIN, or want calls to ring your mobile too? Open a ticket - we can set both up.

' + . '

Your phone system\'s voicemail number and the exact buttons go here.

'), + + // Network and Wi-Fi + $article('Connecting to the office or guest Wi-Fi', 'Which Wi-Fi to use for work devices, and for visitors and personal phones.', 'Network and Wi-Fi', ['How-To'], + '

The office has two Wi-Fi networks, kept apart on purpose:

' + . $list([ + 'The staff network - for work computers and work phones. It reaches the printers and shared drives. Managed devices connect to it on their own.', + 'The guest network - for visitors and personal phones. It reaches the internet only.', + ]) + . '

Please don\'t connect personal devices to the staff network, or give its password to visitors. The guest network\'s password is posted at reception, and changes from time to time.

' + . '
Not connecting
' . $list(['Turn Wi-Fi off and on again', 'Choose the network, Forget it, and connect again with the password', 'Restart the device', 'Try a spot nearer the access point - is it just you, or everyone in that area?']) + . '

Your network names go here.

'), + + $article('Slow or no internet - checks before you call', 'Work out whether it is your computer, the Wi-Fi or the office\'s connection.', 'Network and Wi-Fi', ['Troubleshooting', 'Quick Fix'], + $steps([ + 'Try a couple of different websites - is it everything, or one site? One site may be down for everyone.', + 'Ask a colleague - is it just you, or everyone? If everyone, tell us straight away.', + 'If it is just you, turn Wi-Fi off and on, or unplug and replug the network cable.', + 'Restart your computer.', + 'At home, restart your router: unplug it, wait 30 seconds and plug it back in. Give it a few minutes.', + ]) + . '

If the whole office is down, we usually know already from our monitoring - but call so we know it affects you. Working from home and only your connection is slow? That is your internet provider, but tell us if it stops you working and we will help.

'), + + // Policies + $article('New starters and leavers', 'What we need to know before someone joins or leaves, and how far ahead.', 'Policies', ['Policy', 'New Starter'], + '
Someone joining

Let us know at least five working days before their first day - longer if they need a new computer, which can take a couple of weeks to arrive. Tell us:

' + . $list([ + 'Their name, job title and start date', + 'Who they report to, and which team they are in', + 'Who they will work like - we give them the same access, mailboxes and software', + 'Whether they need a computer, phone or desk phone, and where they will sit', + ]) + . '
Someone leaving

Tell us as soon as you know their last day, and straight away if they are leaving sooner than planned. Say:

' + . $list([ + 'Their last day, and when their access should stop - for an awkward exit, ask us to stop it at a set time', + 'Who should get their email and files, and for how long', + 'Which equipment is coming back, and when', + ]) + . '

Only the people allowed to ask for these changes should - we will check with you if a request comes from someone else.

'), + + $article('Acceptable use of work computers and accounts', 'The ground rules for using company computers, email and accounts - a starting point for your own policy.', 'Policies', ['Policy'], + '

A starting point: make it match your organization\'s own policy before publishing it.

' + . $list([ + 'Work computers, phones and accounts are for work. Reasonable personal use is fine, as long as it doesn\'t get in the way of work or break these rules.', + 'Your account is yours alone. Don\'t share your password, or let anyone else use your account or approve sign-ins for them.', + 'Only install software we have approved - ask us first.', + 'Keep work files in the company\'s systems, not on personal accounts, personal devices or USB sticks.', + 'Lock your screen when you step away.', + 'Report anything suspicious straight away - a strange email, a sign-in request you didn\'t start, a lost device. You won\'t be in trouble for reporting it.', + 'What you send and store on company systems isn\'t private, and may be monitored to keep them secure.', + ])), + + ]; + +}