From 5aa98d2d3a7cc10e37a0f41e71b7ed09d064fdf4 Mon Sep 17 00:00:00 2001 From: PointStar Date: Mon, 11 May 2026 15:55:43 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20Task=20#9=20=E2=80=94=20finalize=20ONBO?= =?UTF-8?q?ARDING.md=20+=20add=20IT-SETUP.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ONBOARDING.md (Hebrew, lawyer-facing): corrected install URL (.vsto), ribbon group name (Marcus-Law), first-run flow (open from ribbon), added the four feature sections, troubleshooting table, file locations, support channels - IT-SETUP.md (English, admin-facing): runner provisioning, codesign cert generation + Infisical storage + Gitea Actions secrets, GPO push of the public cert to attorney machines, nginx config for ClickOnce serving, per-user API key provisioning, release procedure, URL protocol install, monitoring + off-boarding + troubleshooting playbook Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/IT-SETUP.md | 175 +++++++++++++++++++++++++++++++++++++++++++++ docs/ONBOARDING.md | 108 ++++++++++++++++++---------- 2 files changed, 247 insertions(+), 36 deletions(-) create mode 100644 docs/IT-SETUP.md diff --git a/docs/IT-SETUP.md b/docs/IT-SETUP.md new file mode 100644 index 0000000..21ad343 --- /dev/null +++ b/docs/IT-SETUP.md @@ -0,0 +1,175 @@ +# IT setup guide — Marcus-Law OutlookAddin + +Audience: IT admin. Walks you through deploying the ClickOnce installer, distributing the code-signing certificate via GPO, provisioning per-user EspoCRM API keys, and operating the add-in for the 10 attorneys at Marcus-Law. + +## Prerequisites + +- Windows AD domain (`marcus-law.local`) with GPO push to all attorney machines. +- EspoCRM admin access on `https://crm.prod.marcus-law.co.il`. +- SSH access to `platform.dev.marcus-law.co.il` for serving the ClickOnce artifacts. +- Mattermost webhook for release notifications (`#git-verelasim`). +- Infisical project `outlook-addin` for storing secrets. + +## 1. Build infrastructure + +### Windows CI runner (one-time) + +A Windows 11 Pro VM on Coolify hosts the Gitea Actions runner. It needs: + +- **Visual Studio Build Tools 2022** with workloads: + - `Microsoft.VisualStudio.Workload.Office` (for the VSTO MSBuild targets) + - `Microsoft.VisualStudio.Workload.ManagedDesktop` (for WPF) +- **Windows SDK 10.0.22621** (for `signtool.exe`). +- **.NET Framework 4.8 Developer Pack** (`mage.exe`). +- **WSL Ubuntu** (for the `rsync` step of the publish job). +- **Gitea act_runner** registered as a Windows service with label `windows`. + +### Code-signing certificate + +The runner needs a code-signing certificate in `Cert:\CurrentUser\My`. Generate a self-signed cert once: + +```powershell +$cert = New-SelfSignedCertificate ` + -Subject "CN=Marcus-Law OutlookAddin" ` + -Type CodeSigningCert ` + -CertStoreLocation Cert:\CurrentUser\My ` + -NotAfter (Get-Date).AddYears(3) ` + -KeyAlgorithm RSA ` + -KeyLength 2048 +$thumbprint = $cert.Thumbprint +$pfxPassword = ConvertTo-SecureString -String "" -Force -AsPlainText +Export-PfxCertificate -Cert $cert -FilePath C:\codesign.pfx -Password $pfxPassword +Export-Certificate -Cert $cert -FilePath C:\codesign.cer # public part — for GPO push +``` + +Store these in Infisical `/outlook-addin/`: + +| Key | Value | +|---|---| +| `CODESIGN_THUMBPRINT` | The cert thumbprint (40 hex chars) | +| `CODESIGN_PFX_BASE64` | `[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\codesign.pfx"))` | +| `CODESIGN_PASSWORD` | The PFX password | +| `PLATFORM_DEV_SSH_KEY` | Base64 of the rsync target's ed25519 private key | +| `MATTERMOST_WEBHOOK_RELEASES` | Incoming webhook URL for `#git-verelasim` | + +In Gitea (`Settings → Actions → Secrets`), add four secrets that reference Infisical: + +- `CODESIGN_THUMBPRINT` +- `PLATFORM_DEV_SSH_KEY` +- `MATTERMOST_WEBHOOK_RELEASES` + +(The PFX itself is imported once on the runner; the workflow only uses the thumbprint.) + +## 2. Deploy the certificate via GPO + +The ClickOnce installer refuses to launch unless the publishing certificate is in **Trusted Publishers** on each attorney's machine. Use GPO to push it. + +1. Copy `codesign.cer` to `\\marcus-law.local\SYSVOL\marcus-law.local\Scripts\certs\codesign.cer`. +2. Open **Group Policy Management Console** → edit a GPO scoped to the attorney OU. +3. Navigate to: + `Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies` +4. Right-click **Trusted Publishers → Import…** and pick `codesign.cer`. +5. Repeat under **Trusted Root Certification Authorities** (self-signed cert). +6. Force update everywhere: + ```powershell + Invoke-Command -ComputerName (Get-ADComputer -Filter * -SearchBase "OU=Attorneys,DC=marcus-law,DC=local").Name -ScriptBlock { gpupdate /force } + ``` +7. Verify on one attorney machine: + ```powershell + certutil -store -user TrustedPublisher | findstr /C:"Marcus-Law OutlookAddin" + ``` + +## 3. nginx — serve the ClickOnce artifacts + +On `platform.dev.marcus-law.co.il`, add `/etc/nginx/sites-available/outlook-addin.conf`: + +```nginx +server { + listen 443 ssl http2; + server_name platform.dev.marcus-law.co.il; + ssl_certificate /etc/letsencrypt/live/platform.dev.marcus-law.co.il/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/platform.dev.marcus-law.co.il/privkey.pem; + + location /outlook-addin/ { + alias /var/www/outlook-addin/; + autoindex off; + types { + application/x-ms-application application; + application/x-ms-manifest manifest; + application/octet-stream vsto; + application/octet-stream deploy; + } + add_header Cache-Control "no-cache, must-revalidate"; + } +} +``` + +```bash +sudo mkdir -p /var/www/outlook-addin +sudo chown -R www-data:www-data /var/www/outlook-addin +sudo ln -s /etc/nginx/sites-available/outlook-addin.conf /etc/nginx/sites-enabled/ +sudo nginx -t && sudo systemctl reload nginx +``` + +The CI runner pushes new versions here on every `v*` tag via the publish job. + +## 4. EspoCRM API key provisioning + +Per attorney: + +1. EspoCRM admin → **Administration → Users → Create**. +2. **User Type:** API User (or a Regular User with the "API" role). +3. **Username:** mail prefix (e.g. `chaim` for `chaim@marcus-law.co.il`). +4. **Role:** at least: read Contact / Case / Account / Lead / Email; create Email; read EmailAddress. +5. Save, then **Generate API Key**. Copy it. +6. Store under Infisical `/outlook-addin/users/` (or send via a 1-time link service). + +Send the attorney a personal email matching the ONBOARDING.md template, with their per-user key. + +## 5. Release procedure (each new version) + +1. Tag the commit on `main`: + ```bash + git tag v1.0.0 + git push origin v1.0.0 + ``` +2. Gitea Actions builds Release, signs, generates the ClickOnce artifacts, rsyncs to platform.dev, and posts to `#git-verelasim`. +3. Smoke-test from a clean attorney machine (or a Windows 11 sandbox): + - Browse to `https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto`. + - The ClickOnce installer should run with **no security warning**. If you see "Unknown Publisher", the GPO cert hasn't propagated to that machine. + - First-run Settings → enter creds → Test Connection green. + - Send a test email to a known contact, hit "תייק ל-EspoCRM", confirm it appears in the EspoCRM activity stream. +4. If a release goes badly, push a new tag with a fix; ClickOnce will roll all users forward automatically on their next Outlook start. + +## 6. URL protocol handler (optional) + +To make EspoCRM "Compose email" links open Outlook with the case pre-filled: + +1. After the ClickOnce install, run as the user: + ```powershell + & "$env:LOCALAPPDATA\Apps\OutlookAddinProtocolHandler\install-protocol.ps1" + ``` +2. Verify: `start outlookaddin://compose?caseId=` should open a new Outlook composer with the case pre-populated. (Outlook must be already running so the named pipe is up.) +3. To uninstall the registration: `uninstall-protocol.ps1`. + +## 7. Monitoring + +- **CI status** — Mattermost `#git-verelasim`, plus Gitea Actions UI. +- **Server-side filing** — EspoCRM internal logs (`data/logs/espo-*.log`) for `/api/v1/MailRouter/file` calls. +- **Client-side errors** — when an attorney reports an issue, ask them to send `%LOCALAPPDATA%\MarcusLaw\OutlookAddin\logs\addin-.log`. Logs roll daily, retained 14 days. + +## 8. Off-boarding (attorney leaves) + +1. In EspoCRM admin, delete or disable the API User. +2. Their `creds.dat` on the laptop is DPAPI-encrypted with their Windows user profile — wiping the profile (or the laptop) is enough. +3. No central state to remove beyond EspoCRM. + +## 9. Troubleshooting playbook + +| Symptom | Likely cause | Fix | +|---|---|---| +| Install dialog says "Unknown Publisher" | GPO cert hasn't reached the machine | `gpupdate /force`, then `certutil -store -user TrustedPublisher` to confirm | +| Add-in installs but ribbon group is missing | `Microsoft.VSTORuntime.4.0` missing | ClickOnce normally pulls it; if Office < 2019, install [VSTO 4 Runtime](https://www.microsoft.com/download/details.aspx?id=48217) manually | +| Mass 401s after a renewal | API keys were rotated | Send new keys, ask users to re-open Settings and paste them | +| Retry queue is growing | EspoCRM unreachable, or 5xx errors | Check EspoCRM health; once it's back, the processor drains the queue on its 30-second loop | +| User says "categories disappeared" | They are local to that PC. If they reinstall Outlook on a new machine, categories don't sync (MAPI limitation) | Re-file is harmless — server-side dedups on `messageId` (409 returned, counted as success) | diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index 831a446..3b7e668 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -2,63 +2,99 @@ ## מה זה התוסף? -תוסף ל-Outlook שמאפשר לתייק מיילים ל-EspoCRM ישירות מתוך Outlook, בלי להעתיק/להדביק או להגדיר BCC. +תוסף ל-Outlook שמאפשר לתייק מיילים ל-EspoCRM ישירות מתוך Outlook, בלי להעתיק/להדביק או להגדיר BCC. ארבע יכולות עיקריות: + +1. **תיוק מייל קיים** — סמן מייל, לחץ "תייק ל-EspoCRM", בחר תיק/לקוח. +2. **סרגל צד** — כשפותחים מייל, צד ימין מציג איזה לקוח/תיק קשור לשולח. +3. **כתיבת מייל מתיק** — חלון מייל חדש מקבל כתובת+נושא לפי תיק נבחר, ומתויק אוטומטית כששולחים. +4. **סנכרון תיקיות** — Outlook יסמן או יתייק לבד מיילים שנכנסים לתיקיות שבחרת לנטר. ## דרישות -- Windows 10 או Windows 11 +- Windows 10 / Windows 11 - Outlook desktop (Microsoft 365 / Office 2021 / Office 2019) -- חיבור אינטרנט -- API key אישי ב-EspoCRM (תקבל מהאדמין) +- .NET Framework 4.8 (כבר מותקן בכל הגרסאות הנתמכות) +- חיבור אינטרנט ל-`crm.prod.marcus-law.co.il` +- שם משתמש + API key אישי ב-EspoCRM (תקבל מהאדמין בנפרד) ## התקנה (5 דקות) -1. סגור את Outlook לגמרי (`File → Exit`, או יציאה דרך System Tray). -2. פתח את הלינק: **https://platform.dev.marcus-law.co.il/outlook-addin/setup.exe** -3. לחץ "Install" בחלונית שתיפתח. -4. ההתקנה תיגמר תוך 30 שניות. אם רואים שגיאת "Unknown Publisher" — פנה לאדמין (חסר אישור הצוות). -5. פתח את Outlook. תראה ב-Ribbon תפריט חדש בשם "EspoCRM". +1. סגור את Outlook לגמרי (`File → Exit`). +2. פתח את הלינק במייל שהאדמין שלח: **https://platform.dev.marcus-law.co.il/outlook-addin/OutlookAddin.vsto** +3. ייפתח דיאלוג ClickOnce. לחץ **Install**. +4. ההתקנה תיגמר תוך 30 שניות. אם רואים אזהרת "Unknown Publisher" — **אל תאשר**, פנה לאדמין; חסר אישור הצוות במחשב. +5. פתח את Outlook. בלשונית **Home** של תיבת הדואר תופיע קבוצה חדשה בשם **Marcus-Law** עם שני כפתורים. ## הגדרה ראשונית -1. בפעם הראשונה ש-Outlook ייפתח, ייפתח חלון "ברוך הבא ל-EspoCRM Add-in". -2. **כתובת השרת** — מולא מראש: `https://crm.prod.marcus-law.co.il` -3. **שם משתמש** — כתובת המייל שלך (לדוגמה `chaim@marcus-law.co.il`). -4. **API Key** — הדבק את ה-key שקיבלת מהאדמין (נראה כמו `a1b2c3d4e5f6...`). -5. לחץ "Test Connection". סימן ✓ ירוק = הכל עובד. -6. לחץ "Save & Continue". +1. בפעם הראשונה שתלחץ על "תייק ל-EspoCRM" יישאל אותך התוסף אם לפתוח הגדרות. ענה **כן**. +2. בחלון ההגדרות, טאב **כללי**: + - **כתובת שרת EspoCRM** — מולא מראש: `https://crm.prod.marcus-law.co.il` + - **שם משתמש** — כתובת המייל שלך (לדוגמה `chaim@marcus-law.co.il`). + - **מפתח API** — הדבק את ה-key שקיבלת מהאדמין (נראה כמו `a1b2c3d4e5f6…`). + - **שפת ממשק** — עברית (ברירת מחדל) או English. +3. לחץ **בדוק חיבור**. אם רואים "התחברות תקינה — משתמש: …" בירוק, הכל עובד. +4. לחץ **שמור**. החלון ייסגר והתוסף יתחבר. ## שימוש יומיומי -### תיוק מייל לתיק -- בחר מייל אחד או יותר ברשימה. -- לחץ "**File to EspoCRM**" ב-Ribbon. -- חפש את שם התיק או הלקוח, בחר, לחץ "File". -- המייל יקבל קטגוריה צבעונית "Filed: <שם>" בעמודת הצבע ב-Outlook. +### תיוק מייל קיים +1. סמן מייל אחד או יותר ב-Inbox (אפשר Ctrl-click או Shift-click). +2. בלשונית **Home**, לחץ "**תייק ל-EspoCRM**". +3. ייפתח חלון חיפוש — הקלד 2+ אותיות של שם תיק / לקוח / איש קשר. +4. סמן את התיק הנכון ולחץ **תייק**. המייל יקבל קטגוריה "Filed: <שם>" בעמודת הצבע. +5. אם השולח לא קיים ב-CRM, לחץ "**צור איש קשר חדש מהשולח**" כדי להוסיף אותו ולתייק אליו באותה פעולה. -### מי הלקוח? -- כשפותחים מייל, סיידבר ימני יופיע עם פרטי הלקוח/התיק (אם קיים ב-EspoCRM). -- לחץ "Open in EspoCRM" כדי לעבור ישירות לתיק. +### סרגל "פרטי תיק" (צד ימין) +- ברגע שתפתח מייל יופיע סרגל ימני קטן עם איש הקשר, החברה ו-5 התיקים האחרונים. +- **תייק לתיק הזה** — מתייק לתיק הראשון ברשימה. +- **תייק למקום אחר** — פותח את חלון החיפוש הרגיל. +- **פתח ב-EspoCRM** — פותח את כרטיס איש הקשר בדפדפן. -### כתיבת מייל חדש מתוך תיק -- ב-EspoCRM, פתח תיק → לחץ "Email this case". -- Outlook ייפתח עם כתובת + נושא ממולאים אוטומטית. +### כתיבת מייל מתיק +1. פתח חלון מייל חדש (New Email). +2. בלשונית **Message**, לחץ "**כתוב מתיק**". +3. חפש ובחר תיק. התוסף ימלא אוטומטית את כתובת הנמען (איש קשר ראשי בתיק) ויוסיף בכותרת מספר תיק בסוגריים מרובעים, וקישור לתיק בסוף הגוף. +4. כתוב ושלח. **כשתשלח, המייל יתויק אוטומטית** לאותו תיק ב-EspoCRM, בלי שתצטרך לעשות שום דבר נוסף. -### סנכרון אוטומטי של תיקייה -- לחץ "**Settings**" ב-Ribbon → טאב "Folders". -- סמן את התיקיות שאתה רוצה לנטר (לדוגמה Inbox/Smith Family). -- בחר "Auto-file when confident" או "Notify only". -- מיילים שייכנסו לתיקיות האלו יסומנו/יתויקו אוטומטית. +### סנכרון אוטומטי של תיקיות +1. בלשונית **Home** לחץ "**הגדרות**" → טאב **תיקיות**. +2. סמן את התיקיות שאתה רוצה לנטר (לדוגמה Inbox / לקוחות / כהן). +3. בחר מצב: + - **התרעה בלבד** — Outlook יסמן את המייל ב-Categories עם "Needs filing" כדי שתראה ידנית. + - **תיוק אוטומטי** — התוסף יתייק לבד, רק אם הוא בטוח שהשולח הוא אותו לקוח (התאמה יחידה, חד-משמעית). +4. שמור. מהרגע הזה, כל מייל שמגיע לתיקיות האלה יעבור עיבוד מיידי. + +### עדכון התוסף +- אין צורך להתקין מחדש. ClickOnce בודק עדכונים אוטומטית פעם בשבוע. +- אם רוצים לכפות עדכון: **File → Options → Add-ins → Click-Once Add-ins** או פשוט סגור ופתח את Outlook כעבור 7 ימים. ## בעיות נפוצות | בעיה | פתרון | |---|---| -| Ribbon "EspoCRM" לא מופיע | File → Options → Add-ins → לוודא ש-MarcusLaw.OutlookAddin פעיל | -| "401 Unauthorized" | API key לא נכון או הוחלף — פנה לאדמין | -| "EspoCRM unreachable" | בדוק חיבור לאינטרנט; המיילים יישמרו בתור ויתויקו כשהחיבור יחזור | -| Outlook איטי אחרי התקנה | סגור וטען מחדש את Outlook | +| קבוצת "Marcus-Law" לא מופיעה ב-Ribbon | File → Options → Add-ins → לוודא ש-`MarcusLaw.OutlookAddin` פעיל; אם לא — Add → Browse → בחר ב-`MarcusLaw.OutlookAddin.vsto` | +| "התוסף עדיין לא מוגדר" | פתח את ההגדרות והזן URL/שם משתמש/API key | +| "מפתח ה-API נדחה" | API key לא נכון או הוחלף — פנה לאדמין לקבל key חדש | +| "שגיאת חיבור לשרת" | אין אינטרנט או ה-CRM לא זמין — המיילים יישמרו בתור ויתויקו אוטומטית כשהחיבור יחזור | +| תיוק לקח הרבה זמן | בדוק את כרטיסיית **Diagnostics** בהגדרות; ייתכן שהשרת איטי או שיש תור גדול ב-`%LOCALAPPDATA%\MarcusLaw\OutlookAddin\retry-queue\` | +| Outlook איטי אחרי התקנה | סגור וטען מחדש את Outlook; אם נמשך, פנה לאדמין | + +## איפה נשמרים הקבצים? + +- **לוגים** — `%LOCALAPPDATA%\MarcusLaw\OutlookAddin\logs\addin-YYYYMMDD.log` +- **הגדרות** — `%APPDATA%\MarcusLaw\OutlookAddin\settings.json` +- **תור ניסיונות חוזרים** — `%LOCALAPPDATA%\MarcusLaw\OutlookAddin\retry-queue\*.json` +- **API key** — `%APPDATA%\MarcusLaw\OutlookAddin\creds.dat` (מוצפן DPAPI; לא ניתן לקרוא בלי המשתמש שלך) ## דיווח על בעיה -ב-Settings → טאב "Diagnostics" → לחץ "Send Diagnostic Logs". יווצר קובץ zip ב-`%TEMP%`. שלח אותו לאדמין. +1. שלח מייל ל-`it@marcus-law.co.il`. +2. צרף את התיקייה `%LOCALAPPDATA%\MarcusLaw\OutlookAddin\logs\` בלחיצה ימנית → Send to → Compressed (zipped) folder. +3. תאר במשפט אחד מה ניסית לעשות ומה ראית במקום. + +## תמיכה + +- **Mattermost** — ערוץ `#תמיכה-טכנית` (לשאלות מהירות) +- **מייל** — `it@marcus-law.co.il` +- **שעות פתוחות** — יום שני 9:00–17:00, יום שלישי 9:00–13:00 בשבועיים הראשונים אחרי השקה