diff --git a/docs/SAMY.help.md b/docs/SAMY.help.md new file mode 100644 index 0000000..8e73138 --- /dev/null +++ b/docs/SAMY.help.md @@ -0,0 +1,120 @@ +<# +.SYNOPSIS + Script Automation Monkey (SAMY) is a unified MSP assistant that automates onboarding, headless offboarding, + Datto RMM deployments, printer provisioning, and toolkit management through a local UI, HTTP endpoints, + or direct PowerShell switches. + +.DESCRIPTION + SAMY can be used in three ways: + 1) Local UI (default) - launches a local web UI and exposes endpoints for tasks. + 2) Headless / RMM mode - run onboarding/offboarding/Datto flows using PowerShell switches. + 3) Toolkit-only / cleanup - install or remove the SVSMSP module and related artifacts. + + The Datto helper (Install-DattoRMM) centralizes: + - Credential retrieval (webhook or direct) + - OAuth token acquisition + - Site list retrieval and optional persistence + - Registry variable writes (HKLM:\Software\SVS\Deployment) + - Agent download/launch and optional installer archiving + + Printer endpoints provide: + - /getprinters (fetch profiles from server; optionally updates local config) + - /installprinters (installs requested printers; supports -WhatIf when enabled) + + Throughout, secrets are never written to logs or console, and all operations produce clear + success/failure messages via Write-LogHybrid. + +.CHANGES + - Windows 11 25H2: execution policy relaunch logic updated to improve reliability. + - UI template: HTML has been moved to samy.html (pulled from repo at runtime). + - UI hint message: now controlled via the {{SamyHintText}} placeholder in samy.html. + Recommended: set $Script:SamyHintText in the script or via a config file (future enhancement). + - Printers: Invoke-InstallPrinters supports enabling -WhatIf on Invoke-SVSPrinterInstall + (see Invoke-InstallPrinters; the line is commented by default). + - Assets: branch/base configuration is centralized in the SAMY asset config section + (SamyBranch/SamyRepoBase). Update those values once to switch UI/CSS/JS/HTML assets. + +.CONFIGURATION + SAMY asset config (branch + repo base): + $Script:SamyBranch = 'beta' # or 'main' + $Script:SamyRepoBase = 'https://git.svstools.ca/SVS_Public_Repo/SAMY/raw/branch' + + UI hint message: + - samy.html contains: {{SamyHintText}} + - PowerShell sets: $Script:SamyHintText = "Please use samy.svstools.ca" + +.PARAMETER SilentInstall + Toolkit-only mode. Installs/updates the SVSMSP toolkit module and exits (no UI). + +.PARAMETER Cleanup + Removes the SVSMSP module, unregisters repos, and clears related artifacts (including registry keys). + +.PARAMETER Offboard + Runs every offboarding task sequentially (same behavior as checking "Select All" in the Off-Boarding tab), + without launching the web UI. + +.PARAMETER UseWebhook + Fetches Datto API credentials from the webhook at WebhookUrl using WebhookPassword. + +.PARAMETER WebhookPassword + Password used to authenticate to the credentials webhook. Mandatory when -UseWebhook is set + for headless Datto modes. May be blank when using an allowlisted IP flow (server-side). + +.PARAMETER WebhookUrl + URL of the credentials webhook endpoint. Defaults to $Global:DattoWebhookUrl. + +.PARAMETER FetchSites + Fetches the list of Datto RMM sites and skips all install/variable-push actions. + +.PARAMETER SaveSitesList + Saves the fetched site list to the desktop as OutputFile. Must be used with -FetchSites. + +.PARAMETER OutputFile + Name of the file to write the site list to (must end in ".csv" or ".json"). + Defaults to 'datto_sites.csv'. + +.PARAMETER SiteUID + The unique identifier of the Datto RMM site. Mandatory when performing install or variable-push. + +.PARAMETER SiteName + The friendly name of the Datto RMM site (used in logging). Mandatory when performing install or variable-push. + +.PARAMETER PushSiteVars + Fetches site-specific variables and writes them under HKLM:\Software\SVS\Deployment. + +.PARAMETER InstallRMM + Downloads and launches the Datto RMM agent installer for the specified site. + +.PARAMETER SaveCopy + Saves a copy of the downloaded Datto RMM installer into C:\Temp. + +.NOTES + Default EventLog : SVSMSP Events + Default Source : SAMY + +.EXAMPLE + & ([ScriptBlock]::Create((iwr 'https://samy.svstools.com' -UseBasicParsing).Content)) -UseWebhook -WebhookPassword 'pwd' SiteUID 'site-123' -SiteName 'Acme Corp' -PushSiteVars -InstallRMM + + # Headlessly installs the Datto RMM agent on “Acme Corp” and writes site variables to the registry. + +.EXAMPLE + & ([ScriptBlock]::Create((iwr 'https://samy.svstools.com' -UseBasicParsing).Content)) -UseWebhook -WebhookPassword 'pwd' -FetchSites -SaveSitesList -OutputFile 'sites.json' + + # Fetches the full site list via webhook and saves it as JSON to your Desktop. + +.EXAMPLE + & ([ScriptBlock]::Create((iwr 'samy.svstools.ca' -UseBasicParsing).Content)) -SilentInstall + +.EXAMPLE + & ([ScriptBlock]::Create((iwr 'samy.svstools.com' -UseBasicParsing).Content)) -Cleanup + +.EXAMPLE + & ([ScriptBlock]::Create((iwr 'samy.svstools.ca' -UseBasicParsing).Content)) -Offboard + + # Runs the off-boarding tasks in sequence without launching the UI. + +.EXAMPLE + # Printer provisioning (called from RMM / scripts) + $profiles = Get-SvsPrinterProfilesFromServer -Uri 'https://bananas.svstools.ca/getprinters' -Password $pw + Set-SvsPrinterLocalConfig -PrinterProfiles $profiles -SkipIfEmpty +#>