diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 0473ac6..0a607be 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -52,7 +52,6 @@ Instances of abusive, harassing, or otherwise unacceptable behavior may be repor - **Email:** conduct@christaylor.codes - **Slack:** @CTaylor on [MSPGeek Slack](https://join.mspgeek.com/) -- **GitHub:** Open a confidential issue via the Security Advisory feature All complaints will be reviewed and investigated promptly and fairly. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 507d304..afd122c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -6,14 +6,12 @@ The following is a set of guidelines for contributing. These are mostly guidelin ## Table Of Contents -[I don't want to read this whole thing, I just have a question!!!](#i-don't-want-to-read-this-whole-thing-i-just-have-a-question) +[I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question) [How Can I Contribute?](#how-can-i-contribute) - [Reporting Bugs](#reporting-bugs) - [Suggesting Enhancements](#suggesting-enhancements) -- [Your First Code Contribution](#your-first-code-contribution) -- [Pull Requests](#pull-requests) [AI Contributors](#ai-contributors) @@ -49,18 +47,18 @@ Before creating bug reports, please check existing issues as you might find out #### Before Submitting A Bug Report -- **Check the Wiki.** You might be able to find the cause of the problem and fix things yourself. +- **Check the help.** The [README](../README.md), the [function pages](../ConnectWiseControlAPI_Functions.md), `Get-Help about_ConnectWiseControlAPI` and the [changelog](../CHANGELOG.md) (see "Breaking changes") may explain the problem. - **Check the [MSPGeek Slack Team](https://join.mspgeek.com/)** for help from the community. #### How Do I Submit A (Good) Bug Report -Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined which repository your bug is related to, create an issue on that repository and provide the following information by filling in the template. +Bugs are tracked as [GitHub issues](https://docs.github.com/en/issues). After you've determined which repository your bug is related to, create an issue on that repository and provide the following information by filling in the template. Explain the problem and include additional details to help maintainers reproduce the problem: - **Use a clear and descriptive title** for the issue to identify the problem. - **Describe the exact steps which reproduce the problem** in as many details as possible. -- **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). +- **Provide specific examples to demonstrate the steps**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples. If you're providing snippets in the issue, use [Markdown code blocks](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks). - **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. - **Explain which behavior you expected to see instead and why.** @@ -77,20 +75,20 @@ Before creating enhancement suggestions, please check existing suggestions as yo #### How Do I Submit A (Good) Enhancement Suggestion -Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). Create an issue and provide the following information: +Enhancement suggestions are tracked as [GitHub issues](https://docs.github.com/en/issues). Create an issue and provide the following information: - **Use a clear and descriptive title** for the issue to identify the suggestion. - **Provide a step-by-step description of the suggested enhancement** in as many details as possible. -- **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). +- **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks). - **Describe the current behavior** and **explain which behavior you expected to see instead** and why. -- **Explain why this enhancement would be useful** to most users and isn't something that can or should be implemented as a [community package](<>). +- **Explain why this enhancement would be useful** to most users and isn't something that belongs in your own script. - **List some other text examples where this enhancement exists.** - **Specify which version of the module you're using.** - **Specify the name and version of the OS you're using.** ## AI Contributors -This project welcomes contributions from AI coding agents. AI agents follow the same quality standards as human contributors. See [CLAUDE.md](../CLAUDE.md) for development instructions and conventions. +This project welcomes contributions from AI coding agents. AI agents follow the same quality standards as human contributors. See [AGENTS.md](../AGENTS.md) for development instructions and conventions. ## Styleguides @@ -104,8 +102,6 @@ This project welcomes contributions from AI coding agents. AI agents follow the - Reference issues and pull requests liberally after the first line -- When only changing documentation, include `[ci skip]` in the commit title - - Consider starting the commit message with an applicable emoji: - :art: `:art:` when improving the format/structure of the code - :racehorse: `:racehorse:` when improving performance @@ -123,8 +119,10 @@ This project welcomes contributions from AI coding agents. AI agents follow the ### PowerShell Styleguide -- Refer to the [unofficial guide](https://github.com/PoshCode/PowerShellPracticeAndStyle). +- Follow the repo's [PowerShell style guide](PowerShell-StyleGuide.md); read the note at its top first. Code must run on Windows PowerShell 5.1. +- Run `./Tests/test-local.ps1` before you open a pull request. It runs the same checks as CI. ### Documentation Styleguide -- Documentation is built with [platyPS](https://github.com/PowerShell/platyPS). +- Function help is written as comment-based help in the function's file under `source/Public/`. +- `Docs/`, `ConnectWiseControlAPI_Functions.md` and the help file in `source/en-US/` are generated from it with [platyPS](https://github.com/PowerShell/platyPS). Don't edit them by hand: run `./Build/Update-Help.ps1` and commit the result. diff --git a/.github/ISSUE_TEMPLATE/ai_task.md b/.github/ISSUE_TEMPLATE/ai_task.md index 546db32..02598b7 100644 --- a/.github/ISSUE_TEMPLATE/ai_task.md +++ b/.github/ISSUE_TEMPLATE/ai_task.md @@ -2,7 +2,7 @@ name: AI Task about: Create a structured task for AI coding agents title: '[AI] ' -labels: 'ai-task, ai-ready' +labels: '' assignees: '' --- @@ -27,8 +27,7 @@ assignees: '' -- [ ] All existing tests pass (`Invoke-Pester`) -- [ ] PSScriptAnalyzer reports zero errors +- [ ] `./Tests/test-local.ps1` passes (build, analyzer, Pester on both editions, docs drift) - [ ] New/changed functionality has test coverage - [ ] @@ -49,7 +48,7 @@ assignees: '' ## Technical Notes - + ## Related Issues diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index a91ab71..c56e039 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -36,8 +36,9 @@ assignees: '' - **OS**: [e.g., Windows 11, Windows Server 2022] -- **Module Version**: [e.g., 0.3.5.0] +- **Module Version**: [e.g., 0.5.0] - **PowerShell Version**: [e.g., 5.1, 7.4.0] +- **Connection type**: [`-Credentials`, `-Credentials` with MFA, or `-ApiSecret`] - **ScreenConnect Server Version**: [e.g., 24.1] ## Additional Context diff --git a/.github/PowerShell-StyleGuide.md b/.github/PowerShell-StyleGuide.md index 2873343..e88d54c 100644 --- a/.github/PowerShell-StyleGuide.md +++ b/.github/PowerShell-StyleGuide.md @@ -7,6 +7,17 @@ > `Tests/test-local.ps1` and `Build/Update-Help.ps1`), and test runners must not set a global > `$ErrorActionPreference = 'Stop'` (it breaks the module's error-path tests). Where this guide disagrees, follow > [AGENTS.md](../AGENTS.md); everything else applies as written. +> +> Parts of this guide that name things this repo does not have: +> +> | This guide says | In this repo | +> | --- | --- | +> | `Templates/Function.ps1`, `Scripts/New-Function.ps1` | Copy `source/Public/PageService/Get-CWCSession.ps1` | +> | No MAML/XML help is generated | `Build/Update-Help.ps1` writes `Docs/` and the MAML in `source/en-US/` | +> | `./build.ps1 -Tasks docs`, `Scripts/Update-MarkdownHelp.ps1` | `./Build/Update-Help.ps1` | +> | One test file per exported function | Four suite files under `Tests/` | +> | `-IncludeAnalyzer`, `Invoke-QuickTest.ps1` | `./Tests/test-local.ps1 -Stage Analyze` (or `Test`) | +> | Set `$ErrorActionPreference = 'Stop'`, use `ThrowTerminatingError` | Module functions report with non-terminating `Write-Error` | This is the authoritative style guide for all PowerShell projects. It applies to both formal modules (built with Sampler/ModuleBuilder, using InvokeBuild as the task runner) and standalone script collections. All projects should reference this file rather than duplicating conventions. diff --git a/.github/SECURITY.md b/.github/SECURITY.md index cf162a7..65134e8 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -2,12 +2,12 @@ ## Supported Versions -We actively support the following versions of this project with security updates: +Security fixes go into the latest release on the PowerShell Gallery: | Version | Supported | | ------- | ------------------ | -| Latest | :white_check_mark: | -| < 1.0 | :x: | +| Latest release (0.5.x) | :white_check_mark: | +| Older releases | :x: | ## Reporting a Vulnerability @@ -19,16 +19,11 @@ We take the security of ConnectWiseControlAPI seriously. If you believe you have Instead, please report them via one of the following methods: -1. **GitHub Security Advisories** (Preferred) - - Navigate to the repository's Security tab - - Click "Report a vulnerability" - - Fill out the security advisory form with details - -2. **Direct Email** +1. **Direct Email** (Preferred) - Send an email to: **security@christaylor.codes** - Use the subject line: `[SECURITY] ConnectWiseControlAPI - Brief Description` -3. **Private Message on Slack** +2. **Private Message on Slack** - Contact **@CTaylor** on [MSPGeek Slack](https://join.mspgeek.com/) - Clearly mark the message as security-related @@ -78,7 +73,7 @@ When using this module, please: 2. **Use HTTPS** - The module requires your ScreenConnect server to use HTTPS - - TLS 1.2 is enforced by the module + - The module turns TLS 1.2 on for the PowerShell session; it does not turn older versions off 3. **Keep Updated** - Regularly update the module from the PowerShell Gallery diff --git a/AGENTS.md b/AGENTS.md index 0a0f63d..0e44e60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,9 +40,13 @@ Import-Module ./source/ConnectWiseControlAPI.psd1 -Force ./Tests/test-local.ps1 -Stage Analyze, Manifest # One test file against source/ (HTTP is mocked). Tests import $env:MODULE_TEST_PATH when set, else source/. +# A bare Invoke-Pester uses whatever Pester the machine has (3.4 on Windows PowerShell 5.1), so load the +# pinned one first. Needs one earlier build, which resolves it into output/RequiredModules. +Import-Module ./output/RequiredModules/Pester -RequiredVersion 5.7.1 Invoke-Pester -Path ./Tests/ConnectWiseControlAPI.Private.Tests.ps1 -# Regenerate Docs/, ConnectWiseControlAPI_Functions.md and the MAML help (never edit those by hand) +# Regenerate Docs/, ConnectWiseControlAPI_Functions.md and the MAML help from the comment-based help +# (never edit those by hand; every page is rewritten). Uses the pinned platyPS from output/RequiredModules. ./Build/Update-Help.ps1 ``` @@ -50,21 +54,23 @@ Tooling: PowerShell 7 for the build. Every tool version (Sampler, ModuleBuilder, Pester 5.7.1, PSScriptAnalyzer, platyPS 0.14.2) is pinned exactly in `RequiredModules.psd1`, the only place versions are written. The first build resolves them into `output/RequiredModules`; `Tests/test-local.ps1` imports each tool at its pinned version and fails if it is missing. To raise a pin, change the file in a PR and delete -`output/RequiredModules`. +`output/RequiredModules`. The one exception is Microsoft.PowerShell.PSResourceGet (packaging and publishing): it +comes from the machine or runner, and `Build/Test-ReleasePackage.ps1` needs 1.1.0 or newer. `Tests/ConnectWiseControlAPI.Live.Tests.ps1` skips unless `$env:CWC_SERVER`, `CWC_USER` and `CWC_PASSWORD` are set. -`Tests/Live/Invoke-CWCLiveSmokeTest.ps1` checks behaviour against a real server (read-only unless `-AllowWrites`). +`Tests/Live/Invoke-CWCLiveSmokeTest.ps1` checks behaviour against a real server (read-only unless `-AllowWrites`; +`-CleanupOnly` deletes the notes earlier runs left on the test session). ## CI/CD -`.github/workflows/ci.yml` runs on `windows-latest`. Each job calls one stage of `Tests/test-local.ps1`: +`.github/workflows/ci.yml` runs on `windows-latest`. Each job calls `Tests/test-local.ps1` with one or two stages: | Job | What it checks | | --- | --- | | Build module | `./build.ps1` (Sampler/ModuleBuilder); `Test-ModuleManifest` on source and built manifests | | Pester (PowerShell 7) / Pester (Windows PowerShell 5.1) | Full Pester suite against the built module, both editions | | PSScriptAnalyzer | No analyzer errors in `source/`, and nothing from three rules that block at any severity: `PSUseCompatibleSyntax`, `PSAvoidUsingPlainTextForPassword`, `PSUsePSCredentialType` | -| Docs drift | `Build/Update-Help.ps1` leaves no diff | +| Docs drift | `Build/Update-Help.ps1` leaves no diff: the committed pages and MAML match the comment-based help | Only the build job downloads tools from the Gallery; the other jobs get `output/RequiredModules` as an artifact. A Pester run in which no test passes fails. `.github/workflows/pr-validation.yml` warns when a PR doesn't update @@ -77,7 +83,8 @@ every step below needs the owner's explicit go. 1. Release PR: set `ModuleVersion` in `source/.psd1` (three parts), rename the CHANGELOG's `## [Unreleased]` notes to `## [] - ` (leave an empty `[Unreleased]` above it) and update - the compare links at the bottom. Merge it. + the compare links at the bottom. Run `./Build/Update-Help.ps1` (it writes the version into + `ConnectWiseControlAPI_Functions.md`). Merge it. 2. Dry run on the exact commit that will be tagged: run the **Release** workflow by hand (`gh workflow run release.yml --ref master`). It checks, builds, tests and packages, and publishes nothing. Locally: `./Build/Get-ReleaseInfo.ps1`, then `./Tests/test-local.ps1`, then `./Build/Test-ReleasePackage.ps1`. @@ -111,21 +118,29 @@ The `release` artifact is kept for 30 days; re-runs need it. writes `FunctionsToExport` from the `Public/` file names (the source manifest says `'*'`). The source `.psm1` is only for development: it dot-sources the same files and is **not** used by the build, so module-level code belongs in `source/prefix.ps1`. That file holds the TLS setup and the shared constants: `$script:CWCSessionType`, - `$script:CWCSessionEventType` (live-verified numbers) and the Remote Workforce and RESTful API Manager extension IDs. + `$script:CWCSessionEventType` (live-verified numbers), `$script:CWCDefaultSessionGroup`, `$script:CWCProcessType`, + `$script:CWCAllSessionPermissions`, `$script:InternalUserSource` and the Remote Workforce and RESTful API Manager + extension IDs. - **Requests**: every public function calls `Private/Invoke-CWCServiceMethod.ps1`. It builds the endpoint (`-Service` → `Services/.ashx/`, `-RestApi` / `-ExtensionID` → `App_Extensions//Service.ashx/`) and sends the arguments as a **positional JSON array** matching the - server method's signature. `-Idempotent` turns on retry for HTTP 500 (3 retries, waiting 2/4/8 s; never for - permission errors; otherwise none, so commands/notes/deletes never repeat). Session events go through - `Private/Add-CWCSessionEvent.ps1`. Transport errors carry an ErrorId (`CWC.NotConnected`, `CWC.AuthModeMismatch`, - `CWC.Http`, `CWC.NoResponse`). `-Sensitive` redacts the body from verbose and debug output. + server method's signature. `-Idempotent` turns on retry for HTTP 500 (3 retries, waiting 2/4/8 s). Only a + 500 without an `errorType` (a server fault) or with a rate-limit or timeout `errorType` is retried; permission + errors, bad arguments and missing sessions fail at once. Without `-Idempotent` nothing is retried, so + commands/notes/deletes never repeat. Session events go through `Private/Add-CWCSessionEvent.ps1`. Transport + errors carry an ErrorId (`CWC.NotConnected`, `CWC.AuthModeMismatch`, `CWC.Http`, `CWC.NoResponse`); an MFA + login adds `CWC.MfaRequired`, `CWC.MfaCodeRejected`, `CWC.LoginFailed` and `CWC.LoginThrottled`. A failed sign-in + without MFA or with `-ApiSecret` has no `CWC.*` ErrorId. `-Sensitive` redacts the body from verbose and debug + output. - **Transport**: `Private/Invoke-CWCWebRequest.ps1` checks that a connection exists, **blocks calls that don't match the auth mode** (API-secret connections may only reach the RESTful API Manager), adds auth headers, handles PS 5 vs 6+ error shapes, and returns parsed JSON. -- **Connection state**: `$script:CWCServerConnection` holds `Server`, `AuthType`, and `Headers`. Credentials mode - adds a `WebSession` (cookies) and an anti-forgery token taken from the front page. ApiSecret mode sends - `CTRLAuthHeader`. Connect-CWC validates the login with a test call and restores the previous connection if that - call fails. +- **Connection state**: `$script:CWCServerConnection` holds `Server`, `AuthType`, and `Headers`. Credentials and Mfa + modes add a `WebSession` (cookies) and an anti-forgery token taken from the front page; Mfa also keeps `UserName` + and `IdentityHash`. ApiSecret mode keeps the secret as a SecureString (`ApiSecret`) and sends `CTRLAuthHeader`. + Connect-CWC validates the login with a test call. If that call fails, the previous connection is restored only + when this was a `-Force` refresh of the same server, method and identity; a failed switch to anything else leaves + the module disconnected. ## Adding New Functions @@ -134,7 +149,9 @@ The `release` artifact is kept for 30 days; re-runs need it. 2. Call `Invoke-CWCServiceMethod`. Check the method name and argument order against the ScreenConnect server's `Services/*.ashx` source. Pass `-Idempotent` only for reads and "set to value" updates. 3. Add mocked Pester tests to `Tests/ConnectWiseControlAPI.Public.Tests.ps1`. -4. Run `./Build/Update-Help.ps1` and commit the generated pages. +4. Run `./Build/Update-Help.ps1` and commit the generated pages. Do the same after changing a function's help. + Leave a blank line between the help block's `#>` and a following `#` comment, or the comment becomes part of + the help. ## Code Conventions @@ -146,8 +163,8 @@ Enforced by `.PSScriptAnalyzerSettings.psd1` and `.editorconfig`: - **Code must run on PowerShell 3.0+ / Windows PowerShell 5.1**: no `??`, ternary, `&&`/`||`, or other 7-only syntax. - 4-space indentation, max 120 characters per line, open brace on the same line, cuddled `} else {` / `} catch {`. - Single quotes for constants, double quotes only for interpolation. Approved verbs only. -- Public functions need comment-based help (`.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE`). Not every - function has it yet; add it to any function you touch. +- Public functions need comment-based help (`.SYNOPSIS`, `.DESCRIPTION`, `.PARAMETER`, `.EXAMPLE`). It is the only + source of `Docs/` and the MAML. - Destructive functions use `[CmdletBinding(SupportsShouldProcess)]`. Never pass the request body (it may hold a password) as the `ShouldProcess` target. - Report errors with `Write-Error` (non-terminating) and let callers decide. Return objects, not formatted output. diff --git a/Build/Update-Help.ps1 b/Build/Update-Help.ps1 index a0971ea..7d63a7e 100644 --- a/Build/Update-Help.ps1 +++ b/Build/Update-Help.ps1 @@ -3,9 +3,16 @@ Regenerates Docs/*.md, the module page and the MAML help from the functions' comment-based help. .DESCRIPTION - Run after adding or changing a public function. Requires platyPS (Install-Module platyPS). - Creates pages for new functions, updates existing ones (keeping hand-written text), then fixes what - platyPS gets wrong for this repo: + Run after adding or changing a public function or its help. The comment-based help is the only source: + every page in Docs/ is written again from it, so text edited in a page by hand is lost. Pages of functions + that no longer exist are deleted. Only the header and description of the module page are kept; its + Help Version is set to the module version. + + Uses platyPS at the version pinned in RequiredModules.psd1. The build resolves it into + output/RequiredModules (./Tests/test-local.ps1 -Stage Build); a platyPS of that version installed on the + machine works too. + + Then fixes what platyPS gets wrong for this repo: - PowerShell 7.4+ adds the -ProgressAction common parameter to every page; it is removed. - The module page lives at the repo root, so its links need the Docs/ prefix. Finally rebuilds source/en-US/ConnectWiseControlAPI-help.xml. @@ -21,11 +28,45 @@ $RepoRoot = Split-Path -Parent $PSScriptRoot $DocsPath = Join-Path $RepoRoot 'Docs' $ModulePagePath = Join-Path $RepoRoot 'ConnectWiseControlAPI_Functions.md' -Import-Module platyPS -$Module = Import-Module (Join-Path $RepoRoot 'source\ConnectWiseControlAPI.psd1') -Force -PassThru +# platyPS at the pinned version, from the build's modules when they are there +$PlatyPSVersion = (Import-PowerShellDataFile -Path (Join-Path $RepoRoot 'RequiredModules.psd1')).platyPS +$RequiredModulesPath = Join-Path $RepoRoot 'output\RequiredModules' +$SavedModulePath = $env:PSModulePath +if ((Test-Path $RequiredModulesPath) -and ($env:PSModulePath -notlike "*$RequiredModulesPath*")) { + $env:PSModulePath = $RequiredModulesPath + [IO.Path]::PathSeparator + $env:PSModulePath +} +try { + Import-Module platyPS -RequiredVersion $PlatyPSVersion +} catch { + throw ("platyPS $PlatyPSVersion is not available: $($_.Exception.Message) Run " + + "'./Tests/test-local.ps1 -Stage Build' once, or Install-Module platyPS -RequiredVersion $PlatyPSVersion.") +} finally { + $env:PSModulePath = $SavedModulePath +} +$SourceManifest = Join-Path $RepoRoot 'source\ConnectWiseControlAPI.psd1' +# New-MarkdownHelp finds commands by module name, so another loaded copy (an installed Gallery version, the +# built module) would be documented too. Only the source module may be loaded while the pages are written. +$LoadedBefore = @(Get-Module ConnectWiseControlAPI) +$SourceWasLoaded = [bool]($LoadedBefore | Where-Object { $_.Path -like (Join-Path $RepoRoot 'source\*') }) +foreach ($Other in $LoadedBefore) { + if ($Other.Path -notlike (Join-Path $RepoRoot 'source\*')) { + Write-Warning "Removing ConnectWiseControlAPI $($Other.Version) loaded from $($Other.ModuleBase)." + } + Remove-Module $Other -Force +} +$Module = Import-Module $SourceManifest -Force -PassThru +$Commands = @($Module.ExportedFunctions.Keys | Sort-Object) -$Missing = @($Module.ExportedFunctions.Keys | Where-Object { -not (Test-Path (Join-Path $DocsPath "$_.md")) }) -if ($Missing) { $null = New-MarkdownHelp -Command $Missing -OutputFolder $DocsPath } +# Update-MarkdownHelp keeps the synopsis, description, examples and parameter text of an existing page, so +# changed comment-based help never reached the pages. New-MarkdownHelp -Force writes them from the help. +# Pages of functions that no longer exist are deleted: only platyPS command pages, never other markdown. +foreach ($Stale in Get-ChildItem $DocsPath -Filter '*.md' | Where-Object { $Commands -notcontains $_.BaseName }) { + if ((Get-Content $Stale.FullName -TotalCount 5) -match '^external help file:') { + Write-Warning "Deleting $($Stale.Name): the module has no command of that name." + Remove-Item $Stale.FullName + } +} +$null = New-MarkdownHelp -Module $Module.Name -OutputFolder $DocsPath -Force $null = Update-MarkdownHelpModule -Path $DocsPath -ModulePagePath $ModulePagePath -RefreshModulePage -Force foreach ($Page in Get-ChildItem $DocsPath -Filter '*.md') { @@ -36,9 +77,16 @@ foreach ($Page in Get-ChildItem $DocsPath -Filter '*.md') { } $Text = [IO.File]::ReadAllText($ModulePagePath) -[IO.File]::WriteAllText($ModulePagePath, [regex]::Replace($Text, '\]\((?!Docs/)([A-Za-z-]+\.md)\)', '](Docs/$1)')) +$Text = [regex]::Replace($Text, '\]\((?!Docs/)([A-Za-z-]+\.md)\)', '](Docs/$1)') +# The page header keeps whatever version it had; write the module's +$Text = [regex]::Replace($Text, '(?m)^Help Version: [^\r\n]*', "Help Version: $($Module.Version)") +[IO.File]::WriteAllText($ModulePagePath, $Text) $null = New-ExternalHelp -Path $DocsPath -OutputPath (Join-Path $RepoRoot 'source\en-US') -Force +# Don't leave the source module loaded when this script loaded it: tests run later in this session would find +# two copies of the module. A source module the caller had loaded stays (reloaded, so its connection is gone). +if (-not $SourceWasLoaded) { Remove-Module $Module -Force } + $Placeholders = Select-String -Path (Join-Path $DocsPath '*.md'), $ModulePagePath -Pattern '\{\{' foreach ($Hit in $Placeholders) { Write-Warning "Placeholder left to fill: $($Hit.Filename):$($Hit.LineNumber)" } diff --git a/CHANGELOG.md b/CHANGELOG.md index c5a26c9..bd129eb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -120,6 +120,12 @@ Details are in the sections below. - `Get-CWCSession -Type Support` and `-Type Meeting` without `-Group` read `All Machines`, the Access group; they now read `All Sessions` and `All Meetings` - Failed requests no longer keep the login cookie on the request object stored in `$Error` +- `Get-Help` and the pages in `Docs/` describe the current commands. They had kept text from earlier versions: + examples called commands that do not exist (`End-CWWake`, `Remove-CWCAccessSession`, `Get-CWCSessions`), and + 18 synopses were out of date. `Get-Help Remove-CWCSession` and `Get-Help Remove-CWCSessionNote` no + longer show a code comment as a related link +- `Examples/CreateNewUser.ps1` passed parameters `New-CWCUser` does not have and used the MFA secret as the + password; it now creates the user from a credential Endpoint calls audited against the ScreenConnect server's `Services/*.ashx` source: @@ -174,7 +180,8 @@ Changes to the repository. They do not change the published module. was the Remote Workforce extension) and `./build.ps1` builds the published module into `output///`. Module-level setup moved from the `.psm1` to `source/prefix.ps1`. The build adds the tags the Gallery lists and finds commands by. CI and `Tests/test-local.ps1` test the built module -- `Build/Update-Help.ps1` regenerates `Docs/` and the MAML help in one step +- `Build/Update-Help.ps1` regenerates `Docs/` and the MAML help in one step. It writes every page from the + comment-based help (an update kept the old text of existing pages), with the pinned platyPS - Repo files aligned with the GitHub-Template: `AGENTS.md` (agent guide; `CLAUDE.md` points to it), community files (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue and PR templates), `pr-validation.yml`, `dependabot.yml`, `copilot-instructions.md`, `.vscode/` settings, `.editorconfig`, `.gitattributes`, an expanded `.gitignore`, diff --git a/ConnectWiseControlAPI_Functions.md b/ConnectWiseControlAPI_Functions.md index d3581d5..1ca5ac1 100644 --- a/ConnectWiseControlAPI_Functions.md +++ b/ConnectWiseControlAPI_Functions.md @@ -2,17 +2,17 @@ Module Name: ConnectWiseControlAPI Module Guid: f94fa996-0f01-4c5c-9cd9-3227728ebacb Download Help Link: https://github.com/christaylorcodes/ConnectWiseControlAPI/blob/master/ConnectWiseControlAPI_Functions.md -Help Version: 0.1.2.0 +Help Version: 0.5.0 Locale: en-US --- # ConnectWiseControlAPI Module ## Description -This module wraps the web API into PowerShell functions. +PowerShell commands for the ConnectWise ScreenConnect (formerly ConnectWise Control) web API. Connect-CWC signs in; `Get-Help about_ConnectWiseControlAPI` gives an overview. ## ConnectWiseControlAPI Cmdlets ### [Add-CWCRemoteWorkforceRequiredRole](Docs/Add-CWCRemoteWorkforceRequiredRole.md) -Create a new Remote Workforce security role +Creates the security role required by the Remote Workforce extension. ### [Add-CWCSessionNote](Docs/Add-CWCSessionNote.md) Adds a note to a session. @@ -27,13 +27,13 @@ Opens the ConnectWise ScreenConnect Host client joined to a session, like Join i Finds sessions by session filter expression, name or ID (API secret connections). ### [Get-CWCAuditInfo](Docs/Get-CWCAuditInfo.md) -Shows current audit settings +Shows the current audit settings. ### [Get-CWCAuditLog](Docs/Get-CWCAuditLog.md) -Pull audit log information +Returns audit log entries for a time range. ### [Get-CWCLastContact](Docs/Get-CWCLastContact.md) -Returns the date the machine last connected to the ScreenConnect server. +Returns when a machine was last connected, or whether it connected recently. ### [Get-CWCLauncURL](Docs/Get-CWCLauncURL.md) DEPRECATED. @@ -46,25 +46,25 @@ Gets a Remote Workforce host launch URL for an assigned machine. Lists the Remote Workforce machines assigned to the calling user. ### [Get-CWCSecurityConfigurationInfo](Docs/Get-CWCSecurityConfigurationInfo.md) -Will return security configuration information. +Returns the server's security configuration (user sources, roles, users). ### [Get-CWCSession](Docs/Get-CWCSession.md) -Will return a list of sessions. +Lists sessions of one type in a session group. ### [Get-CWCSessionDetail](Docs/Get-CWCSessionDetail.md) -Will return information about a session. +Returns the details of a session: session info, events, connections and guest screenshot. ### [Get-CWCSessionGroup](Docs/Get-CWCSessionGroup.md) -Returns details of all session groups. +Returns all session groups. ### [Initialize-CWCRemoteWorkforceSessionGroup](Docs/Initialize-CWCRemoteWorkforceSessionGroup.md) Creates or repairs the session group used by the Remote Workforce extension. ### [Invoke-CWCCommand](Docs/Invoke-CWCCommand.md) -Will issue a command against a given machine and return the results. +Runs a command on a session's machine and returns its output. ### [Invoke-CWCWake](Docs/Invoke-CWCWake.md) -Will issue a wake command to a given session. +Sends a wake (Wake-on-LAN) request to sessions. ### [New-CWCAccessToken](Docs/New-CWCAccessToken.md) Gets an access token for joining a session. @@ -73,25 +73,25 @@ Gets an access token for joining a session. Creates a new authenticator-app (TOTP) secret for a ScreenConnect user. ### [New-CWCRemoteWorkforceAssignment](Docs/New-CWCRemoteWorkforceAssignment.md) -Assign a user to machines. +Assigns machines to a Remote Workforce user. ### [New-CWCSession](Docs/New-CWCSession.md) Creates a session. ### [New-CWCUser](Docs/New-CWCUser.md) -Creates a user. +Creates an internal user. ### [Remove-CWCHostFromSession](Docs/Remove-CWCHostFromSession.md) Disconnects one connection (for example a host) from a session. ### [Remove-CWCSession](Docs/Remove-CWCSession.md) -Will end a given session. +Deletes sessions, optionally uninstalling the Access client first. ### [Remove-CWCSessionNote](Docs/Remove-CWCSessionNote.md) Removes notes from a session. ### [Remove-CWCUser](Docs/Remove-CWCUser.md) -Removes an internal user. +Deletes an internal user. ### [Send-CWCSessionMessage](Docs/Send-CWCSessionMessage.md) Sends a chat message to a session's guest. @@ -100,11 +100,11 @@ Sends a chat message to a session's guest. Queues a Toolbox item to run on a session. ### [Update-CWCCustomProperty](Docs/Update-CWCCustomProperty.md) -Will update a custom property for a session. +Sets one custom property of a session. ### [Update-CWCSessionName](Docs/Update-CWCSessionName.md) -Updates the name of a session. +Renames a session. ### [Update-CWCUser](Docs/Update-CWCUser.md) -Update properties of an internal user. +Updates an internal user. diff --git a/Docs/Add-CWCRemoteWorkforceRequiredRole.md b/Docs/Add-CWCRemoteWorkforceRequiredRole.md index b498cdc..84ecccc 100644 --- a/Docs/Add-CWCRemoteWorkforceRequiredRole.md +++ b/Docs/Add-CWCRemoteWorkforceRequiredRole.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Add-CWCRemoteWorkforceRequiredRole ## SYNOPSIS -Create a new Remote Workforce security role +Creates the security role required by the Remote Workforce extension. ## SYNTAX @@ -18,21 +18,26 @@ Add-CWCRemoteWorkforceRequiredRole [-WhatIf] [-Confirm] ``` ## DESCRIPTION -Sometimes Remote Workforce doesn't create the required security role. This will create that role. +Calls the Remote Workforce extension's EnsureRemoteWorkforceSecurityRoleExists endpoint. +The extension creates its role (name from the extension's RoleName setting, "Remote Workforce" +by default) with View Session Group, Join Session and Host Session Without Consent scoped to the +extension's session group, then marks the role as created in the extension settings. + +Idempotent: if the role already exists nothing is changed. +Requires the Administer permission. ## EXAMPLES -### Example 1 -```powershell -PS C:\> Add-CWCRemoteWorkforceRequiredRole +### EXAMPLE 1 +``` +Add-CWCRemoteWorkforceRequiredRole ``` - -Adds the Remote Workforce security role ## PARAMETERS ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -70,5 +75,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES +Requires Connect-CWC -Credentials. +Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. +Pair with Initialize-CWCRemoteWorkforceSessionGroup. +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Connect-CWC.md b/Docs/Connect-CWC.md index 7210dd7..e16169f 100644 --- a/Docs/Connect-CWC.md +++ b/Docs/Connect-CWC.md @@ -1,7 +1,7 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- @@ -42,61 +42,71 @@ Connect-CWC [-Server] -ApiSecret [-Origin ] [-Fo Three ways to sign in: -Credentials alone (default): Basic auth with a ScreenConnect user account that does not use MFA. -Gives access to every function in the module, limited by that user's permissions. Never expires. - --Credentials with -Mfa, -OneTimeCode or -TotpSecret: signs in the way the web page does, with a one-time -code, for accounts that require MFA. Gives the same access as -Credentials alone. The login is a cookie -that the server expires; when it does, commands fail with a permission error and you run Connect-CWC -again. The password and TOTP secret are not kept after the login. +Gives +access to every function in the module, limited by that user's permissions. +Never expires. + +-Credentials with -Mfa, -OneTimeCode or -TotpSecret: signs in the way the web page does, with a +one-time code, for accounts that require MFA. +Gives the same access as -Credentials alone. +The +login is a cookie that the server expires; when it does, commands fail with a permission error +and you run Connect-CWC again. +The password and TOTP secret are not kept after the login. -ApiSecret: the authentication secret configured in the RESTful API Manager extension's -RESTfulAuthenticationSecret setting, sent as the CTRLAuthHeader header. Works when every user account -requires MFA. Only functions backed by that extension are available (see NOTES); other functions return -an error telling you to connect with -Credentials. - -The connection is validated before it is cached. An existing connection to the same server with the same -method and identity (user and password, or secret) is reused unless -Force is given; anything else -reconnects. A cached MFA login is checked with one call first and replaced with a new login if it has -expired. +RESTfulAuthenticationSecret setting, sent as the CTRLAuthHeader header. +Works when every user +account requires MFA. +Only functions backed by that extension are available (see NOTES); other +functions return an error telling you to connect with -Credentials. + +The connection is validated before it is cached. +An existing connection to the same server with +the same method and identity (user and password, or secret) is reused unless -Force is given; +anything else reconnects. +A cached MFA login is checked with one call first and replaced with a +new login if it has expired. ## EXAMPLES -### Example 1 -```powershell -PS C:\> Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) +### EXAMPLE 1 +``` +Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) ``` Connects with an account that does not use MFA. -### Example 2 -```powershell -PS C:\> Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) -Mfa +### EXAMPLE 2 +``` +Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) -Mfa ``` Connects with an account that requires MFA and asks for the one-time code. -### Example 3 -```powershell -PS C:\> Connect-CWC -Server 'screenconnect.example.com' -Credentials $Credential -OneTimeCode (Read-Host 'One-time code') +### EXAMPLE 3 +``` +Connect-CWC -Server 'screenconnect.example.com' -Credentials $Credential -OneTimeCode (Read-Host 'One-time code') ``` Connects with an account that requires MFA, using a code you supply. -Reading it with Read-Host keeps it out of the command history. +Reading it with Read-Host +keeps it out of the command history. -### Example 4 -```powershell -PS C:\> $Credential = Get-Secret -Name 'CWC-Login' -PS C:\> Connect-CWC -Server 'screenconnect.example.com' -Credentials $Credential -TotpSecret (Get-Secret -Name 'CWC-TOTP') +### EXAMPLE 4 +``` +$Credential = Get-Secret -Name 'CWC-Login' +Connect-CWC -Server 'screenconnect.example.com' -Credentials $Credential -TotpSecret (Get-Secret -Name 'CWC-TOTP') ``` Unattended login for an account that requires MFA. -Run it again before each batch of work: when the cached login is still valid it costs one call, and when -it has expired it logs in again. +Run it again before each batch of work: when +the cached login is still valid it costs one call, and when it has expired it logs in again. -### Example 5 -```powershell -PS C:\> $Secret = Read-Host -AsSecureString -Prompt 'RESTful API secret' -PS C:\> Connect-CWC -Server 'screenconnect.example.com' -ApiSecret $Secret +### EXAMPLE 5 +``` +$Secret = Read-Host -AsSecureString -Prompt 'RESTful API secret' +Connect-CWC -Server 'screenconnect.example.com' -ApiSecret $Secret ``` Connects with the RESTful API Manager extension's secret. @@ -104,7 +114,10 @@ Connects with the RESTful API Manager extension's secret. ## PARAMETERS ### -Server -ScreenConnect server hostname, e.g. screenconnect.example.com. A leading http(s):// is removed. HTTPS is always used. +ScreenConnect server hostname, e.g. +screenconnect.example.com. +A leading http(s):// is removed. +HTTPS is always used. ```yaml Type: String @@ -134,9 +147,11 @@ Accept wildcard characters: False ``` ### -Mfa -Sign in for an account that requires MFA, asking for the one-time code at the console when the server -requests it. Works with authenticator apps and with codes the server sends by email or SMS (they are sent -at this point). For interactive use only. +Sign in for an account that requires MFA, asking for the one-time code at the console when the +server requests it. +Works with authenticator apps and with codes the server sends by email or +SMS (they are sent at this point). +For interactive use only. ```yaml Type: SwitchParameter @@ -152,7 +167,8 @@ Accept wildcard characters: False ### -OneTimeCode The current one-time code (6 to 8 digits) for an account that requires MFA. -Quote it, so a leading zero is kept. +Quote it, so a +leading zero is kept. ```yaml Type: String @@ -168,14 +184,17 @@ Accept wildcard characters: False ### -TotpSecret The account's authenticator-app (TOTP) secret, for unattended scripts. -The current code is computed from it at each login; the secret itself is not stored. -Accepts the value ScreenConnect stores for authenticator apps ("ms:" followed by Base32, as New-CWCMFA creates) -or bare Base32. Not for email or SMS codes. - -Keep it in a secret store, e.g. Microsoft.PowerShell.SecretManagement: -TotpSecret (Get-Secret ...). -A TOTP secret stored next to the password turns MFA into a single factor: keep them in separate vaults -where you can, prefer -ApiSecret when its functions are enough, and replace the secret if the computer is -compromised. +The current code is +computed from it at each login; the secret itself is not stored. +Accepts the value ScreenConnect stores +for authenticator apps ("ms:" followed by Base32, as New-CWCMFA creates) or bare Base32. +Not for email or SMS codes. + +Keep it in a secret store, e.g. +Microsoft.PowerShell.SecretManagement: -TotpSecret (Get-Secret ...). +A TOTP secret stored next to the password turns MFA into a single factor: keep them in separate +vaults where you can, prefer -ApiSecret when its functions are enough, and replace the secret if +the computer is compromised. ```yaml Type: SecureString @@ -205,7 +224,9 @@ Accept wildcard characters: False ``` ### -Origin -Origin header sent with -ApiSecret requests. Defaults to https://. Set it to match the +Origin header sent with -ApiSecret requests. +Defaults to https://\. +Set it to match the extension's RESTfulAllowedOrigin setting if that setting is configured. ```yaml @@ -222,9 +243,10 @@ Accept wildcard characters: False ### -Force Reconnect even when the cached connection is for the same server, method and identity. -If that refresh fails, the previous connection is kept. -A failed connection to a different server, method or identity leaves the module disconnected, so later -commands can't reach the old server. +If that +refresh fails, the previous connection is kept. +A failed connection to a different server, method +or identity leaves the module disconnected, so later commands can't reach the old server. ```yaml Type: SwitchParameter @@ -233,7 +255,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -247,19 +269,24 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES -Functions available with -ApiSecret: Get-CWCSessionDetail, Update-CWCSessionName, Invoke-CWCCommand -(queues the command; output is not retrieved), Find-CWCSession, New-CWCSession, Add-CWCSessionNote, -Send-CWCSessionMessage, Send-CWCToolboxItem. +Functions available with -ApiSecret: Get-CWCSessionDetail, Update-CWCSessionName, +Invoke-CWCCommand (queues the command; output is not retrieved), Find-CWCSession, +New-CWCSession, Add-CWCSessionNote, Send-CWCSessionMessage, Send-CWCToolboxItem. Only calls that are safe to repeat (reads, "set to value" updates) are retried on HTTP 500. -The API secret is not tied to a ScreenConnect user: the extension does not apply role permissions or session -group scoping, so it can act on every session. Treat it like an administrator password. +The API secret is not tied to a ScreenConnect user: the extension does not apply role permissions or +session group scoping, so it can act on every session. +Treat it like an administrator password. Requires the RESTful API Manager extension (2d558935-686a-4bd0-9991-07539f5fe749). MFA logins are never retried automatically: each attempt counts toward the server's login limits. -Errors carry an ErrorId: CWC.MfaRequired, CWC.MfaCodeRejected, CWC.LoginFailed, CWC.LoginThrottled or -CWC.NoResponse. The device is never marked as trusted, and the login is never saved to disk. +Errors carry an ErrorId: CWC.MfaRequired, CWC.MfaCodeRejected, CWC.LoginFailed, CWC.LoginThrottled +or CWC.NoResponse. +The device is never marked as trusted, and the login is never saved to disk. + +Author: Chris Taylor ## RELATED LINKS [https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Enter-CWCSession.md b/Docs/Enter-CWCSession.md index b4d8b02..40ad945 100644 --- a/Docs/Enter-CWCSession.md +++ b/Docs/Enter-CWCSession.md @@ -82,9 +82,9 @@ Accept wildcard characters: False ``` ### -Group -Session group containing the session. -Defaults to 'All Machines' for Access, 'All Sessions' for -Support and 'All Meetings' for Meeting. +Session group containing the session: a name, or the path parts of a nested group. +Defaults to +'All Machines' for Access, 'All Sessions' for Support and 'All Meetings' for Meeting. ```yaml Type: String[] @@ -99,7 +99,9 @@ Accept wildcard characters: False ``` ### -Name -Session name shown as the client's title. Taken from the pipeline (e.g. from Get-CWCSession); +Session name shown as the client's title. +Taken from the pipeline (e.g. +from Get-CWCSession); when given, the session lookup is skipped. ```yaml diff --git a/Docs/Get-CWCAuditInfo.md b/Docs/Get-CWCAuditInfo.md index d7dcbbc..775ca01 100644 --- a/Docs/Get-CWCAuditInfo.md +++ b/Docs/Get-CWCAuditInfo.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Get-CWCAuditInfo ## SYNOPSIS -Shows current audit settings +Shows the current audit settings. ## SYNTAX @@ -17,16 +17,14 @@ Get-CWCAuditInfo [] ``` ## DESCRIPTION -Shows current audit settings +Calls AuditService.GetAuditInfo. ## EXAMPLES -### Example 1 -```powershell -PS C:\> Get-CWCAuditInfo +### EXAMPLE 1 +``` +Get-CWCAuditInfo ``` - -Displays the current audit settings ## PARAMETERS @@ -36,10 +34,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### None ## OUTPUTS -### System.Object ## NOTES +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Get-CWCAuditLog.md b/Docs/Get-CWCAuditLog.md index 399356a..143fcd7 100644 --- a/Docs/Get-CWCAuditLog.md +++ b/Docs/Get-CWCAuditLog.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Get-CWCAuditLog ## SYNOPSIS -Pull audit log information +Returns audit log entries for a time range. ## SYNTAX @@ -18,21 +18,24 @@ Get-CWCAuditLog [[-StartDate] ] [[-EndDate] ] [[-SessionName ``` ## DESCRIPTION -Returns the same information as the audit search in web +Calls AuditService.QueryAuditLog. +Times are converted to UTC. ## EXAMPLES -### Example 1 -```powershell -PS C:\> Get-CWCAuditLog -StartDate $(Get-Date).AddDays(-1) -EndDate $(Get-Date) -SessionName 'Computer1' +### EXAMPLE 1 +``` +Get-CWCAuditLog -StartDate (Get-Date).AddDays(-7) -SessionName 'DESKTOP-01' ``` -Get the audit logs for Computer1 for the last day. +Returns the last 7 days of audit entries for the session named DESKTOP-01. ## PARAMETERS ### -StartDate -Start of the time range. Defaults to 24 hours ago. Local times are converted to UTC. +Start of the time range. +Defaults to 24 hours ago. +Local times are converted to UTC. ```yaml Type: DateTime @@ -41,13 +44,15 @@ Aliases: Required: False Position: 1 -Default value: None +Default value: (Get-Date).AddDays(-1) Accept pipeline input: False Accept wildcard characters: False ``` ### -EndDate -End of the time range. Defaults to now. Local times are converted to UTC. +End of the time range. +Defaults to now. +Local times are converted to UTC. ```yaml Type: DateTime @@ -56,7 +61,7 @@ Aliases: Required: False Position: 2 -Default value: None +Default value: (Get-Date) Accept pipeline input: False Accept wildcard characters: False ``` @@ -77,7 +82,8 @@ Accept wildcard characters: False ``` ### -IncludeSessionCaptures -Deprecated. The server no longer accepts this option; it is ignored with a warning. +Deprecated. +The server no longer accepts this option; it is ignored with a warning. ```yaml Type: SwitchParameter @@ -86,13 +92,13 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -EventTypes -Session event type numbers to include (for example 44 for QueuedCommand, 70 for RanCommand). +Session event type numbers to include, for example 44 (QueuedCommand) or 70 (RanCommand). ```yaml Type: Int32[] @@ -127,10 +133,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### None ## OUTPUTS -### System.Object ## NOTES +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Get-CWCLastContact.md b/Docs/Get-CWCLastContact.md index cd2b054..411bdc1 100644 --- a/Docs/Get-CWCLastContact.md +++ b/Docs/Get-CWCLastContact.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Get-CWCLastContact ## SYNOPSIS -Returns the date the machine last connected to the ScreenConnect server. +Returns when a machine was last connected, or whether it connected recently. ## SYNTAX @@ -17,27 +17,25 @@ Get-CWCLastContact -GUID [-Quiet] [-Seconds ] [-Group ] ``` ## DESCRIPTION -Returns the date the machine last connected to the ScreenConnect server. +Reads the session's connect/disconnect events. +Returns the current time if the guest is connected +now, otherwise the time of its last disconnect. +With -Quiet, returns $True when the guest is +connected or was connected within -Seconds, else $False. ## EXAMPLES ### EXAMPLE 1 -```powershell -Get-CWCLastContact -GUID $GUID +``` +Get-CWCLastContact -GUID $SessionID -Quiet -Seconds 300 ``` -Will return the last contact of the machine with that GUID. +Returns $True when the machine is connected or was connected in the last 5 minutes. ## PARAMETERS ### -GUID -The GUID/SessionID for the machine you wish to connect to. -You can retrieve session info with the 'Get-CWCSessions' cmdlets - -On Windows clients, the launch parameters are located in the registry at: - HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ScreenConnect Client (xxxxxxxxxxxxxxxx)\ImagePath -On Linux and Mac clients, it's found in the ClientLaunchParameters.txt file in the client installation folder: - /opt/screenconnect-xxxxxxxxxxxxxxxx/ClientLaunchParameters.txt +Session ID. ```yaml Type: Guid @@ -52,7 +50,7 @@ Accept wildcard characters: False ``` ### -Quiet -Will output a boolean result, $True for Connected or $False for Offline. +Return $True or $False instead of a date. ```yaml Type: SwitchParameter @@ -67,8 +65,9 @@ Accept wildcard characters: False ``` ### -Seconds -Used with the Quiet switch. -The number of seconds a machine needs to be offline before returning $False. +Used with -Quiet: how recent the last contact must be to count. +Defaults to 0, so only a guest that +is connected now counts. ```yaml Type: Int32 @@ -83,7 +82,9 @@ Accept wildcard characters: False ``` ### -Group -Name of session group to use. +Session group containing the session: a name, or the path parts of a nested group. +Defaults to +'All Machines'. ```yaml Type: String[] @@ -105,14 +106,13 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### [datetime] -or [boolean] +### System.Boolean +### System.DateTime ## NOTES -Version: 1.1 -Author: Chris Taylor -Creation Date: 1/20/2016 -Purpose/Change: Initial script development - -Update Date: 8/24/2018 -Purpose/Change: Fix TimeSpan Seconds duration +Requires Connect-CWC -Credentials. +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Get-CWCLauncURL.md b/Docs/Get-CWCLauncURL.md index aedfa1c..6520fb2 100644 --- a/Docs/Get-CWCLauncURL.md +++ b/Docs/Get-CWCLauncURL.md @@ -31,9 +31,13 @@ This function will be removed in v1.0. ### EXAMPLE 1 ``` -Get-CWCRemoteWorkforceLaunchURL -GUID $SessionID +Get-CWCLauncURL -GUID $SessionID ``` +Warns that the command is deprecated and returns what Get-CWCRemoteWorkforceLaunchURL -GUID $SessionID +returns. +Use that command in new scripts. + ## PARAMETERS ### -GUID diff --git a/Docs/Get-CWCRemoteWorkforceLaunchURL.md b/Docs/Get-CWCRemoteWorkforceLaunchURL.md index 43e750a..61168d3 100644 --- a/Docs/Get-CWCRemoteWorkforceLaunchURL.md +++ b/Docs/Get-CWCRemoteWorkforceLaunchURL.md @@ -92,6 +92,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES +Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor diff --git a/Docs/Get-CWCRemoteWorkforceSession.md b/Docs/Get-CWCRemoteWorkforceSession.md index 3174ac0..e4aca9e 100644 --- a/Docs/Get-CWCRemoteWorkforceSession.md +++ b/Docs/Get-CWCRemoteWorkforceSession.md @@ -44,6 +44,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES +Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor diff --git a/Docs/Get-CWCSecurityConfigurationInfo.md b/Docs/Get-CWCSecurityConfigurationInfo.md index 461f553..c315e27 100644 --- a/Docs/Get-CWCSecurityConfigurationInfo.md +++ b/Docs/Get-CWCSecurityConfigurationInfo.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Get-CWCSecurityConfigurationInfo ## SYNOPSIS -Will return security configuration information. +Returns the server's security configuration (user sources, roles, users). ## SYNTAX @@ -17,17 +17,15 @@ Get-CWCSecurityConfigurationInfo [] ``` ## DESCRIPTION -Will return security configuration information. +Calls SecurityService.GetSecurityConfigurationInfo. ## EXAMPLES ### EXAMPLE 1 ``` -Get-CWCSecurityConfigurationInfo +(Get-CWCSecurityConfigurationInfo).UserSources ``` -Returns security configuration - ## PARAMETERS @@ -39,9 +37,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES -Version: 1.0 -Author: Chris Taylor -Creation Date: 1/15/2019 -Purpose/Change: Initial script development +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Get-CWCSession.md b/Docs/Get-CWCSession.md index 921d278..5e450f5 100644 --- a/Docs/Get-CWCSession.md +++ b/Docs/Get-CWCSession.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Get-CWCSession ## SYNOPSIS -Will return a list of sessions. +Lists sessions of one type in a session group. ## SYNTAX @@ -18,21 +18,23 @@ Get-CWCSession [-Type] [[-Group] ] [[-Search] ] [[-Fi ``` ## DESCRIPTION -Allows you to search for access, service or meeting sessions. +Calls PageService.GetLiveData, the same query the web UI's session list uses. ## EXAMPLES ### EXAMPLE 1 ``` -Get-CWCSessions -Type 'Access' -Search 'server1' -Limit 10 +Get-CWCSession -Type Access -Search 'DESKTOP-01' -Limit 1 ``` -Will return the first 10 access sessions that match 'server1'. +Returns the first Access session that matches DESKTOP-01. +Its SessionID is the -GUID the other +session commands take. ## PARAMETERS ### -Type -The type of session Support/Access/Meeting +Session type: Support, Access or Meeting. ```yaml Type: Object @@ -47,7 +49,11 @@ Accept wildcard characters: False ``` ### -Group -Name of session group to use. +Session group: a name, or the path parts of a nested group (e.g. +'Clients','Acme'). +Defaults to +the built-in group for -Type: 'All Machines' (Access), 'All Sessions' (Support) or +'All Meetings' (Meeting). ```yaml Type: String[] @@ -56,13 +62,13 @@ Aliases: Required: False Position: 2 -Default value: All Machines +Default value: None Accept pipeline input: False Accept wildcard characters: False ``` ### -Search -Limit results with search pattern. +Filter text, as typed in the web UI's search box. ```yaml Type: String @@ -77,7 +83,7 @@ Accept wildcard characters: False ``` ### -FindSessionID -Session ID to locate in the results, so the session is included even when -Limit would cut it off. +Session ID to locate, so it is included even when -Limit would cut it off. ```yaml Type: String @@ -92,7 +98,7 @@ Accept wildcard characters: False ``` ### -Limit -Limit the number of results returned. +Maximum number of sessions to return. ```yaml Type: Int32 @@ -114,11 +120,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### ConnectWise ScreenConnect session objects +### ScreenConnect session objects. ## NOTES -Version: 1.0 -Author: Chris Taylor -Creation Date: 10/10/2018 -Purpose/Change: Initial script development +Requires Connect-CWC -Credentials. +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Get-CWCSessionDetail.md b/Docs/Get-CWCSessionDetail.md index 669ac63..56cd7f9 100644 --- a/Docs/Get-CWCSessionDetail.md +++ b/Docs/Get-CWCSessionDetail.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Get-CWCSessionDetail ## SYNOPSIS -Will return information about a session. +Returns the details of a session: session info, events, connections and guest screenshot. ## SYNTAX @@ -17,21 +17,32 @@ Get-CWCSessionDetail [[-Group] ] [-GUID] [[-Include] ``` ## DESCRIPTION -Displays more information about a session. +Credentials connections: PageService.GetSessionDetails. +Event Time values are milliseconds elapsed +since the event, relative to the response's BaseTime. +The call is rate limited by the server. + +API secret connections: the RESTful API Manager extension's GetSessionDetailsBySessionID, which +returns the server's raw session details; -Group and -Include are ignored. ## EXAMPLES ### EXAMPLE 1 ``` -Get-CWCSessionDetail -Group 'All Sessions' -GUID $Session.SessionID +(Get-CWCSessionDetail -GUID $SessionID -Include Events).Events | Where-Object EventType -eq 32 ``` -Will return details of the requested session. +Returns the note events of the session (event type 32 is AddedNote), without downloading the +screenshot. +A deleted note stays in the list; a later event whose CorrelationEventID is the note's +EventID marks it as deleted. ## PARAMETERS ### -Group -Name of session group to use. +Session group containing the session: a name, or the path parts of a nested group. +Defaults to +'All Machines'. ```yaml Type: String[] @@ -46,7 +57,7 @@ Accept wildcard characters: False ``` ### -GUID -GUID of the machine to retrieve session details. +Session ID. ```yaml Type: Guid @@ -61,7 +72,12 @@ Accept wildcard characters: False ``` ### -Include -Parts of the session details to return: SessionInfo, GuestScreenshotContent, Events, Connections. Omit to return everything, including the guest screenshot. Ignored on -ApiSecret connections. +Parts to return: SessionInfo, GuestScreenshotContent, Events, Connections. +Omit for everything, +including the guest screenshot. +Request only what you need when polling. +Ignored on API secret +connections. ```yaml Type: String[] @@ -83,11 +99,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### ConnectWise ScreenConnect session objects +### The session details object the server returns. ## NOTES -Version: 1.0 -Author: Chris Taylor -Creation Date: 1/15/2019 -Purpose/Change: Initial script development +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Get-CWCSessionGroup.md b/Docs/Get-CWCSessionGroup.md index a33e74f..6cba878 100644 --- a/Docs/Get-CWCSessionGroup.md +++ b/Docs/Get-CWCSessionGroup.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Get-CWCSessionGroup ## SYNOPSIS -Returns details of all session groups. +Returns all session groups. ## SYNTAX @@ -17,16 +17,15 @@ Get-CWCSessionGroup [] ``` ## DESCRIPTION -Returns details of all session groups. +Calls SessionGroupService.GetSessionGroups. +Requires the ManageSessionGroups permission. ## EXAMPLES -### Example 1 -```powershell -PS C:\> Get-CWCSessionGroup +### EXAMPLE 1 +``` +Get-CWCSessionGroup | Select-Object Name, SessionType ``` - -Returns details of all session groups. ## PARAMETERS @@ -36,10 +35,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### None ## OUTPUTS -### System.Object ## NOTES +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Initialize-CWCRemoteWorkforceSessionGroup.md b/Docs/Initialize-CWCRemoteWorkforceSessionGroup.md index b5ce41b..d2d2792 100644 --- a/Docs/Initialize-CWCRemoteWorkforceSessionGroup.md +++ b/Docs/Initialize-CWCRemoteWorkforceSessionGroup.md @@ -78,6 +78,7 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES +Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor diff --git a/Docs/Invoke-CWCCommand.md b/Docs/Invoke-CWCCommand.md index bdce59f..371d2e1 100644 --- a/Docs/Invoke-CWCCommand.md +++ b/Docs/Invoke-CWCCommand.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Invoke-CWCCommand ## SYNOPSIS -Will issue a command against a given machine and return the results. +Runs a command on a session's machine and returns its output. ## SYNTAX @@ -18,29 +18,32 @@ Invoke-CWCCommand [-GUID] [[-Command] ] [[-TimeOut] ] [[-M ``` ## DESCRIPTION -Will issue a command against a given machine and return the results. +Queues a QueuedCommand event (44) and polls the session's events until the matching RanCommand +output (70) arrives or -TimeOut passes. + +API secret connections queue the command through the RESTful API Manager extension; the output is +not retrieved (a warning says so unless -NoWait is used). ## EXAMPLES ### EXAMPLE 1 -```powershell -Invoke-CWCCommand -GUID $GUID -Command 'hostname' +``` +Invoke-CWCCommand -GUID $SessionID -Command 'hostname' ``` -Will return the hostname of the machine. +Runs hostname in cmd.exe on the machine and returns its output. ### EXAMPLE 2 -```powershell -Invoke-CWCCommand -GUID $GUID -TimeOut 120000 -Command 'iwr -UseBasicParsing "https://bit.ly/ltposh" | iex; Restart-LTService' -PowerShell +``` +Invoke-CWCCommand -GUID $SessionID -Command 'Get-Service Spooler' -PowerShell -TimeOut 30000 ``` -Will restart the Automate agent on the target machine. +Runs a PowerShell command and waits up to 30 seconds for its output. ## PARAMETERS ### -GUID -The GUID identifier for the machine you wish to connect to. -You can retrieve session info with the 'Get-CWCSessions' cmdlets +Session ID. ```yaml Type: Guid @@ -55,7 +58,7 @@ Accept wildcard characters: False ``` ### -Command -The command you wish to issue to the machine. +Command line to run (cmd.exe unless -PowerShell is used). ```yaml Type: String @@ -70,8 +73,8 @@ Accept wildcard characters: False ``` ### -TimeOut -The amount of time in milliseconds that a command can execute. -The default is 10000 milliseconds. +Milliseconds the command may run, and how long to wait for its output. +Defaults to 10000. ```yaml Type: Int32 @@ -86,7 +89,8 @@ Accept wildcard characters: False ``` ### -MaxLength -Maximum number of characters of command output to return. Defaults to 10000. +Maximum number of characters of output to return. +Defaults to 10000. ```yaml Type: Int32 @@ -95,13 +99,13 @@ Aliases: Required: False Position: 4 -Default value: None +Default value: 10000 Accept pipeline input: False Accept wildcard characters: False ``` ### -PowerShell -Issues the command in a powershell session. +Run the command in PowerShell. ```yaml Type: SwitchParameter @@ -116,7 +120,9 @@ Accept wildcard characters: False ``` ### -Group -Name of session group to use. +Session group containing the session: a name, or the path parts of a nested group. +Defaults to +'All Machines'. ```yaml Type: String[] @@ -131,7 +137,7 @@ Accept wildcard characters: False ``` ### -NoWait -Will not wait for the output of the command. +Queue the command and return without waiting for output. ```yaml Type: SwitchParameter @@ -140,7 +146,7 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -153,14 +159,11 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS -### The output of the Command provided. +### The output of the command, as text. Nothing with -NoWait or on an API secret connection. ## NOTES -Version: 1.0 - -Author: Chris Taylor +Author: Chris Taylor -Creation Date: 1/20/2016 +## RELATED LINKS -Purpose/Change: Initial script development +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) -## RELATED LINKS diff --git a/Docs/Invoke-CWCWake.md b/Docs/Invoke-CWCWake.md index 0da2e14..5dd5c2a 100644 --- a/Docs/Invoke-CWCWake.md +++ b/Docs/Invoke-CWCWake.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Invoke-CWCWake ## SYNOPSIS -Will issue a wake command to a given session. +Sends a wake (Wake-on-LAN) request to sessions. ## SYNTAX @@ -17,22 +17,19 @@ Invoke-CWCWake [-GUID] [-Type] [] ``` ## DESCRIPTION -Will issue a wake command to a given access or support session. +Queues a QueuedWake event (43) for each session, in the built-in group for -Type. ## EXAMPLES ### EXAMPLE 1 ``` -End-CWWake -GUID $GUID +Invoke-CWCWake -GUID $SessionID -Type Access ``` -Will issue a wake command to a given session. - ## PARAMETERS ### -GUID -The GUID identifier for the session you wish to end. -Accepts an array of GUIDs +One or more session IDs. ```yaml Type: Guid[] @@ -47,7 +44,7 @@ Accept wildcard characters: False ``` ### -Type -The type of session Support/Access +Session type: Support or Access. ```yaml Type: String @@ -70,9 +67,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES -Version: 1.0 -Author: Chris Taylor -Creation Date: 12/7/2018 -Purpose/Change: Initial script development +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/New-CWCAccessToken.md b/Docs/New-CWCAccessToken.md index 542d860..fe0555b 100644 --- a/Docs/New-CWCAccessToken.md +++ b/Docs/New-CWCAccessToken.md @@ -34,7 +34,9 @@ $Token = New-CWCAccessToken -GUID $SessionID ## PARAMETERS ### -Group -Session group containing the session. +Session group containing the session: a name, or the path parts of a nested group +(e.g. +'Clients','Acme'). Defaults to 'All Machines'. ```yaml diff --git a/Docs/New-CWCMFA.md b/Docs/New-CWCMFA.md index aab54d4..2bf5252 100644 --- a/Docs/New-CWCMFA.md +++ b/Docs/New-CWCMFA.md @@ -1,7 +1,7 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- @@ -19,27 +19,30 @@ New-CWCMFA [[-DisplayName] ] [[-UserAccount] ] [-WhatIf] ## DESCRIPTION Generates a random 16-character Base32 secret. -Returns it in the form ScreenConnect stores ("ms:\") together with a QR code URL to scan with an -authenticator app. -Nothing is sent to the ScreenConnect server: pass the OTP value to New-CWCUser or Update-CWCUser to set it on -an account. +Returns it in the form ScreenConnect stores ("ms:\") +together with a QR code URL to scan with an authenticator app. +Nothing is sent to the ScreenConnect +server: pass the OTP value to New-CWCUser or Update-CWCUser to set it on an account. The QR code URL is on quickchart.io and contains the secret. -Open it only if you accept sending the secret to that service. +Open it only if you accept sending the +secret to that service. ## EXAMPLES -### Example 1 -```powershell -PS C:\> New-CWCMFA -DisplayName 'My ScreenConnect Server' -UserAccount 'CTaylor' +### EXAMPLE 1 +``` +$Mfa = New-CWCMFA -UserAccount 'jdoe' +$Mfa.OTP ``` -Creates an MFA OTP code and QR URL with the provided information. +Creates a secret for jdoe and shows the value to store on the account. ## PARAMETERS ### -DisplayName Label the authenticator app shows for the entry. +Defaults to 'ScreenConnect'. ```yaml Type: Object @@ -54,7 +57,7 @@ Accept wildcard characters: False ``` ### -UserAccount -User account to display in OTP app. +Account name the authenticator app shows for the entry. ```yaml Type: Object @@ -69,7 +72,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -104,10 +108,14 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### None ## OUTPUTS -### System.Object +### PSCustomObject with QR (URL of the QR code image) and OTP ("ms:" followed by the secret). ## NOTES +Works without a connection. +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/New-CWCRemoteWorkforceAssignment.md b/Docs/New-CWCRemoteWorkforceAssignment.md index cdb1a36..c92b6ca 100644 --- a/Docs/New-CWCRemoteWorkforceAssignment.md +++ b/Docs/New-CWCRemoteWorkforceAssignment.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # New-CWCRemoteWorkforceAssignment ## SYNOPSIS -Assign a user to machines. +Assigns machines to a Remote Workforce user. ## SYNTAX @@ -18,19 +18,21 @@ New-CWCRemoteWorkforceAssignment [-GUID] [-Username] [[-Displa ``` ## DESCRIPTION -Uses the remote workforce extension to assign a user to machines +Calls the Remote Workforce extension's AddAssignmentNoteToSession, which adds an assignment note +(AddedNote) to each session. +The user can then launch the machine from the Remote Workforce page. ## EXAMPLES ### EXAMPLE 1 -```powershell -PS C:\> New-CWCRemoteWorkforceAssignment -GUID $GUID -Username 'CTaylor' -DisplayName 'Chris Taylor' +``` +New-CWCRemoteWorkforceAssignment -GUID $SessionID -Username 'jdoe' -DisplayName 'Jane Doe' ``` ## PARAMETERS ### -GUID -GUID of the session you want to assign the user access to. +One or more session IDs. ```yaml Type: Guid[] @@ -45,7 +47,7 @@ Accept wildcard characters: False ``` ### -Username -Username of the account you want to assign remote workforce access to. +ScreenConnect user name of the assignee. ```yaml Type: String @@ -60,7 +62,7 @@ Accept wildcard characters: False ``` ### -DisplayName -Name that is displayed when user is connected to a session. +Display name of the assignee. ```yaml Type: String @@ -75,7 +77,9 @@ Accept wildcard characters: False ``` ### -Group -Session group containing the session(s). Defaults to 'All Machines' where a default exists. +Session group containing the sessions: a name, or the path parts of a nested group. +Defaults to +'All Machines'. ```yaml Type: String[] @@ -84,13 +88,14 @@ Aliases: Required: False Position: 4 -Default value: None +Default value: All Machines Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -128,12 +133,10 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES -Version: 1.1 - -Author: Chris Taylor +Requires Connect-CWC -Credentials and the Remote Workforce extension. +Author: Chris Taylor -Creation Date: 10/25/2018 +## RELATED LINKS -Purpose/Change: Initial script development +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) -## RELATED LINKS diff --git a/Docs/New-CWCUser.md b/Docs/New-CWCUser.md index 998785e..d713a73 100644 --- a/Docs/New-CWCUser.md +++ b/Docs/New-CWCUser.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # New-CWCUser ## SYNOPSIS -Creates a user. +Creates an internal user. ## SYNTAX @@ -19,27 +19,32 @@ New-CWCUser [-Credentials] [[-OTP] ] [[-DisplayName] [-Group] [-Uninstall] ``` ## DESCRIPTION -Will end a given access or support session. +Queues a DeletedSession event (21) per session, or QueuedUninstallAndDelete (100) with -Uninstall. +Prompts for each session by default (ConfirmImpact High); use -Confirm:$false in unattended scripts. ## EXAMPLES ### EXAMPLE 1 -```powershell -Remove-CWCAccessSession -GUID $GUID ``` - -Will remove the given access session +Remove-CWCSession -GUID $SessionID -Group 'All Machines' -Uninstall -Confirm:$false +``` ## PARAMETERS ### -GUID -The GUID identifier for the session you wish to end. -Accepts an array of GUIDs. +One or more session IDs. ```yaml Type: Guid[] @@ -48,7 +46,7 @@ Accept wildcard characters: False ``` ### -Group -Session group containing the session(s). Defaults to 'All Machines' where a default exists. +Session group containing the sessions: a name, or the path parts of a nested group. ```yaml Type: String[] @@ -63,7 +61,8 @@ Accept wildcard characters: False ``` ### -Uninstall -Queue an uninstall of the Access client and delete the session (QueuedUninstallAndDelete) instead of only deleting the session record. +Uninstall the Access client from the machine and delete the session, instead of only deleting the +session record. ```yaml Type: SwitchParameter @@ -72,13 +71,14 @@ Aliases: Required: False Position: Named -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -116,9 +116,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES -Version: 1.0 -Author: Chris Taylor -Creation Date: 10/10/2018 -Purpose/Change: Initial script development +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Remove-CWCSessionNote.md b/Docs/Remove-CWCSessionNote.md index 19f3495..f171e89 100644 --- a/Docs/Remove-CWCSessionNote.md +++ b/Docs/Remove-CWCSessionNote.md @@ -28,9 +28,9 @@ Deletes notes (AddedNote events) by adding a DeletedEvent correlated to each not the ScreenConnect web UI removes a note. The user needs the RemoveNote permission in -Group. --NoteEventID removes specific notes; -All removes every note still on the session. -Notes that -are already deleted are skipped. +-NoteEventID removes the given notes (without checking them first). +-All reads the session and +removes every note still on it, skipping notes that are already deleted. ## EXAMPLES diff --git a/Docs/Remove-CWCUser.md b/Docs/Remove-CWCUser.md index 6f3d778..d0c580f 100644 --- a/Docs/Remove-CWCUser.md +++ b/Docs/Remove-CWCUser.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Remove-CWCUser ## SYNOPSIS -Removes an internal user. +Deletes an internal user. ## SYNTAX @@ -17,21 +17,19 @@ Remove-CWCUser [-User] [-WhatIf] [-Confirm] [] ``` ## DESCRIPTION -Removes the provided internal user. +Calls SecurityService.DeleteUser. ## EXAMPLES -### Example 1 -```powershell -PS C:\> Remove-CWCUser -User 'ctaylor' +### EXAMPLE 1 +``` +Remove-CWCUser -User 'jdoe' ``` - -Removes the 'ctaylor' user from ScreenConnect. ## PARAMETERS ### -User -The user to remove. +User name of the account to delete. ```yaml Type: String @@ -82,10 +80,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### None ## OUTPUTS -### System.Object ## NOTES +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Send-CWCSessionMessage.md b/Docs/Send-CWCSessionMessage.md index 43a4080..4deadff 100644 --- a/Docs/Send-CWCSessionMessage.md +++ b/Docs/Send-CWCSessionMessage.md @@ -69,6 +69,10 @@ Accept wildcard characters: False ### -From Sender name shown to the guest (API secret connections only). +Defaults to 'RESTful API', the +extension's default RESTfulUserName. +The extension uses this value, not its RESTfulUserName +setting, so pass -From to match a renamed setting (or any name you want the guest to see). ```yaml Type: String diff --git a/Docs/Send-CWCToolboxItem.md b/Docs/Send-CWCToolboxItem.md index fe91808..2205420 100644 --- a/Docs/Send-CWCToolboxItem.md +++ b/Docs/Send-CWCToolboxItem.md @@ -23,7 +23,10 @@ Queues a QueuedTool session event naming the Toolbox item. Credentials connections: PageService.AddSessionEvents; the user needs the RunSharedTool permission in -Group. -API secret connections: the RESTful API Manager extension's SendToolboxItemToSession; -Group is ignored. +API secret connections: the RESTful API Manager extension's SendToolboxItemToSession. +The event +is attributed to the extension's RESTfulUserName setting ("RESTful API" unless renamed); -Group +is ignored. ## EXAMPLES diff --git a/Docs/Update-CWCCustomProperty.md b/Docs/Update-CWCCustomProperty.md index 2788bb2..4973dd9 100644 --- a/Docs/Update-CWCCustomProperty.md +++ b/Docs/Update-CWCCustomProperty.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Update-CWCCustomProperty ## SYNOPSIS -Will update a custom property for a session. +Sets one custom property of a session. ## SYNTAX @@ -17,27 +17,19 @@ Update-CWCCustomProperty [-GUID] [-Property] [[-Value] ] ``` ## DESCRIPTION -Will update a custom property for a session. +Calls PageService.UpdateSessionCustomPropertyValue. ## EXAMPLES ### EXAMPLE 1 ``` -Update-CWCCustomProperty -GUID $GUID -Property 2 -Value 'New Department' +Update-CWCCustomProperty -GUID $SessionID -Property 1 -Value 'Acme' ``` -Will update the sessions department to 'New Department' - ## PARAMETERS ### -GUID -The GUID/SessionID for the machine you wish to connect to. -You can retrieve session info with the 'Get-CWCSessions' cmdlets - -On Windows clients, the launch parameters are located in the registry at: - HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ScreenConnect Client (xxxxxxxxxxxxxxxx)\ImagePath -On Linux and Mac clients, it's found in the ClientLaunchParameters.txt file in the client installation folder: - /opt/screenconnect-xxxxxxxxxxxxxxxx/ClientLaunchParameters.txt +Session ID. ```yaml Type: Guid @@ -52,7 +44,7 @@ Accept wildcard characters: False ``` ### -Property -The property number of the property you want to change. +The property number of the property to change. ```yaml Type: Int32 @@ -61,13 +53,13 @@ Aliases: Required: True Position: 2 -Default value: None +Default value: 0 Accept pipeline input: False Accept wildcard characters: False ``` ### -Value -The value you want to set the property to. +New value. ```yaml Type: String @@ -82,7 +74,9 @@ Accept wildcard characters: False ``` ### -Group -Look for the session in these groups. +Session group containing the session: a name, or the path parts of a nested group. +Defaults to +'All Machines'. ```yaml Type: String[] @@ -97,7 +91,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -135,12 +130,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES -Version: 1.1 +Author: Chris Taylor -Author: Chris Taylor - -Creation Date: 10/25/2018 +## RELATED LINKS -Purpose/Change: Initial script development +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) -## RELATED LINKS diff --git a/Docs/Update-CWCSessionName.md b/Docs/Update-CWCSessionName.md index baea85e..265db4d 100644 --- a/Docs/Update-CWCSessionName.md +++ b/Docs/Update-CWCSessionName.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Update-CWCSessionName ## SYNOPSIS -Updates the name of a session. +Renames a session. ## SYNTAX @@ -17,27 +17,21 @@ Update-CWCSessionName [-GUID] [-NewName] [[-Group] ] [ ``` ## DESCRIPTION -Updates the name of a session on the ScreenConnect server. +Credentials connections: PageService.UpdateSessionName. +API secret connections: the RESTful API +Manager extension's UpdateSessionName (-Group is ignored). ## EXAMPLES ### EXAMPLE 1 -```powershell -Update-CWCSessionName -GUID $GUID -NewName 'Session1' ``` - -Will rename the session to Session1 +Update-CWCSessionName -GUID $SessionID -NewName 'ACME-FrontDesk' +``` ## PARAMETERS ### -GUID -The GUID/SessionID for the machine you wish to connect to. -You can retrieve session info with the 'Get-CWCSessions' cmdlets - -On Windows clients, the launch parameters are located in the registry at: - HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ScreenConnect Client (xxxxxxxxxxxxxxxx)\ImagePath -On Linux and Mac clients, it's found in the ClientLaunchParameters.txt file in the client installation folder: - /opt/screenconnect-xxxxxxxxxxxxxxxx/ClientLaunchParameters.txt +Session ID. ```yaml Type: Guid @@ -52,7 +46,7 @@ Accept wildcard characters: False ``` ### -NewName -The new name for the session. +New session name. ```yaml Type: String @@ -67,7 +61,9 @@ Accept wildcard characters: False ``` ### -Group -Group to look for the session in. +Session group containing the session: a name, or the path parts of a nested group. +Defaults to +'All Machines'. ```yaml Type: String[] @@ -82,7 +78,8 @@ Accept wildcard characters: False ``` ### -WhatIf -Shows what would happen if the cmdlet runs. The cmdlet is not run. +Shows what would happen if the cmdlet runs. +The cmdlet is not run. ```yaml Type: SwitchParameter @@ -120,9 +117,9 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## OUTPUTS ## NOTES -Version: 1.1 -Author: Chris Taylor -Creation Date: 10/25/2018 -Purpose/Change: Initial script development +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Docs/Update-CWCUser.md b/Docs/Update-CWCUser.md index 75d4418..ed8341e 100644 --- a/Docs/Update-CWCUser.md +++ b/Docs/Update-CWCUser.md @@ -1,14 +1,14 @@ --- external help file: ConnectWiseControlAPI-help.xml Module Name: ConnectWiseControlAPI -online version: +online version: https://github.com/christaylorcodes/ConnectWiseControlAPI schema: 2.0.0 --- # Update-CWCUser ## SYNOPSIS -Update properties of an internal user. +Updates an internal user. ## SYNTAX @@ -19,21 +19,25 @@ Update-CWCUser [-UserToUpdate] [[-NewUserName] ] [[-Password] < ``` ## DESCRIPTION -Will update an internal user. Only the properties given will update. +Reads the user, applies the given changes and saves it (SecurityService.SaveUser). +Parameters not +given keep their current values, with one exception: "change password at next login" is switched +off unless -ForcePassChange is given. +The password is never written to verbose or debug output. ## EXAMPLES -### Example 1 -```powershell -PS C:\> Update-CWCUser -UserToUpdate 'ctaylor' -Password $SecureString -ForcePassChange $True +### EXAMPLE 1 +``` +Update-CWCUser -UserToUpdate 'jdoe' -Password (Read-Host -AsSecureString) -ForcePassChange $True ``` -Updates the password for 'ctaylor' and forces a password change at next logon. +Sets a new password for jdoe and makes them change it at the next login. ## PARAMETERS ### -UserToUpdate -The user account you want to update. +User name of the account to update. ```yaml Type: String @@ -48,7 +52,7 @@ Accept wildcard characters: False ``` ### -NewUserName -The new username of the user you are updating. +New user name. ```yaml Type: String @@ -63,7 +67,7 @@ Accept wildcard characters: False ``` ### -Password -The wanted password of the user. +New password. ```yaml Type: SecureString @@ -78,7 +82,8 @@ Accept wildcard characters: False ``` ### -OTP -The wanted MFA option for the user. +The OTP key used for MFA. +Can be generated with New-CWCMFA. ```yaml Type: String @@ -93,7 +98,7 @@ Accept wildcard characters: False ``` ### -DisplayName -The wanted display name for the user. +New display name. ```yaml Type: String @@ -108,7 +113,7 @@ Accept wildcard characters: False ``` ### -Email -The wanted email address for the user. +New email address. ```yaml Type: String @@ -123,7 +128,10 @@ Accept wildcard characters: False ``` ### -SecurityGroups -The wanted security groups the user should be a member of. +Roles the user should be a member of. +Replaces the current list. +An empty list is ignored, so this +cannot remove every role. ```yaml Type: String[] @@ -138,7 +146,9 @@ Accept wildcard characters: False ``` ### -ForcePassChange -Force the user to change their password at next logon. +Force the user to change their password at next login. +Without it the setting is switched off, even +when it was on before. ```yaml Type: Boolean @@ -147,7 +157,7 @@ Aliases: Required: False Position: 8 -Default value: None +Default value: False Accept pipeline input: False Accept wildcard characters: False ``` @@ -189,10 +199,12 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable ## INPUTS -### None ## OUTPUTS -### System.Object ## NOTES +Author: Chris Taylor ## RELATED LINKS + +[https://github.com/christaylorcodes/ConnectWiseControlAPI](https://github.com/christaylorcodes/ConnectWiseControlAPI) + diff --git a/Examples/CreateNewUser.ps1 b/Examples/CreateNewUser.ps1 index 90a9b5a..926947c 100644 --- a/Examples/CreateNewUser.ps1 +++ b/Examples/CreateNewUser.ps1 @@ -1,7 +1,7 @@ # Your ScreenConnect server URL $Server = 'screenconnect.domain.com' -# Get ScreenConnect credentials +# Get ScreenConnect credentials (an account that can manage users) $Credentials = Get-Credential # Load module @@ -11,18 +11,30 @@ Import-Module 'ConnectWiseControlAPI' # Save connection info Connect-CWC -Server $Server -Credentials $Credentials -# Generate a new MFA token -$MFA = New-CWCMFA +# The user to create +$UserName = 'jdoe' +$Email = 'jdoe@domain.com' +$DisplayName = 'John Doe' + +# User name and first password of the new user +$NewUserCredentials = Get-Credential -UserName $UserName -Message 'Password for the new user' + +# Generate an authenticator-app (TOTP) secret for the user. Nothing is sent to the server yet. +$MFA = New-CWCMFA -UserAccount $UserName + $NewUser = @{ - UserName = $DomainUser.Email - Password = $MFA.OTP - Email = $DomainUser.Email - DisplayName = $DomainUser.AccountName - OTP = $MFA.OTP + Credentials = $NewUserCredentials + Email = $Email + DisplayName = $DisplayName + # Sets the secret on the account, so the user signs in with a code from their authenticator app + OTP = $MFA.OTP + # The role(s) the user gets. This one is created by Add-CWCRemoteWorkforceRequiredRole SecurityGroups = 'Remote Workforce' } -New-CWCUser @NewUser -Verbose +# The user must change the password at first login (pass -ForcePassChange $false to turn that off) +New-CWCUser @NewUser -# You now have a new Remote Workforce user created with MFA enabled -# If you need a QR -$MFA.QR \ No newline at end of file +# You now have a new Remote Workforce user with MFA enabled. +# The user adds the secret to an authenticator app by scanning a QR code. This URL shows one, but it is on +# quickchart.io and contains the secret: open it only if you accept sending the secret to that service. +$MFA.QR diff --git a/README.md b/README.md index c26ccd1..34e1f5d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@


- logo + logo
ConnectWiseControlAPI
@@ -117,8 +117,6 @@ In-depth tutorials on [christaylor.codes](https://christaylor.codes): If you use this project please give it a star and follow so you can get updated when new features are released. This also lets me know what projects are getting used and what ones I should dedicate more time to. If you want to get more involved please see the [contributing page](.github/CONTRIBUTING.md). Projects need all kinds of help even if you don't know how to code. -Want to share something you created using the module? Submit it to be featured as a Community Package. - ## Donating If you cant take time to contribute maybe you would like to help another way. diff --git a/Tests/ConnectWiseControlAPI.Module.Tests.ps1 b/Tests/ConnectWiseControlAPI.Module.Tests.ps1 index bfe21e2..8c34da7 100644 --- a/Tests/ConnectWiseControlAPI.Module.Tests.ps1 +++ b/Tests/ConnectWiseControlAPI.Module.Tests.ps1 @@ -413,4 +413,25 @@ Describe 'Generated help' { @(Select-String -Path $Files -Pattern 'ProgressAction' | ForEach-Object { "$($_.Filename):$($_.LineNumber)" }) | Should -BeNullOrEmpty -Because 'run ./Build/Update-Help.ps1 to regenerate the help' } + + # Until 0.5.0 was reviewed the pages kept old text: examples called End-CWWake, Remove-CWCAccessSession and + # Get-CWCSessions, none of which exist. Every Verb-CWC name in the help must be a command of the module. + It 'names only commands the module has' { + $Files = @(Get-ChildItem $DocsPath -Filter '*.md' | ForEach-Object FullName) + + (Join-Path $RepoRoot 'source\en-US\ConnectWiseControlAPI-help.xml') + $Known = @(Get-Command -Module ConnectWiseControlAPI | ForEach-Object Name) + $Unknown = @(Select-String -Path $Files -Pattern '\b[A-Za-z]+-CW[A-Za-z]*\b' -AllMatches | ForEach-Object { + $Hit = $_ + $Hit.Matches | Where-Object { $Known -notcontains $_.Value } | + ForEach-Object { "$($Hit.Filename):$($Hit.LineNumber) $($_.Value)" } + }) + $Unknown | Should -BeNullOrEmpty -Because 'the help names a command that does not exist' + } + + It 'has the module version on the module page' { + $SourceManifest = Join-Path $RepoRoot 'source\ConnectWiseControlAPI.psd1' + $Version = [regex]::Escape((Import-PowerShellDataFile -Path $SourceManifest).ModuleVersion) + Join-Path $RepoRoot 'ConnectWiseControlAPI_Functions.md' | + Should -FileContentMatch "(?m)^Help Version: $Version\s*$" -Because 'run ./Build/Update-Help.ps1' + } } diff --git a/Tests/ConnectWiseControlAPI.Public.Tests.ps1 b/Tests/ConnectWiseControlAPI.Public.Tests.ps1 index bb25858..39be70c 100644 --- a/Tests/ConnectWiseControlAPI.Public.Tests.ps1 +++ b/Tests/ConnectWiseControlAPI.Public.Tests.ps1 @@ -336,6 +336,10 @@ Describe 'ErrorId survives a failed read' { param($ID) Invoke-CWCCommand -GUID $ID -Command 'hostname' -ErrorAction Ignore } } + @{ Name = 'Remove-CWCSessionNote'; Call = { + param($ID) Remove-CWCSessionNote -GUID $ID -All -Confirm:$false -ErrorAction Ignore + } + } ) { { & $Call $SessionID } | Should -Not -Throw } @@ -2490,3 +2494,20 @@ Describe 'Enter-CWCSession pipeline binding' { } } } + +Describe 'Enter-CWCSession error reporting' { + It 'keeps the CWC ErrorId when the access token request fails' { + InModuleScope 'ConnectWiseControlAPI' { + $script:CWCServerConnection = @{ Server = 'test.example.com'; AuthType = 'Credentials'; Headers = @{} } + Mock Get-CWCHostLaunchContext { [PSCustomObject]@{ Scheme = 'sc-test'; RelayHost = 'relay'; RelayPort = 443; PublicKey = 'k' } } + Mock New-CWCAccessToken { Write-Error 'Needs permission' -ErrorId 'CWC.Http403' } + Mock Invoke-CWCServiceMethod {} + $Reported = New-Object System.Collections.ArrayList + $Quiet = @{ WarningAction = 'SilentlyContinue'; ErrorAction = 'SilentlyContinue'; ErrorVariable = '+Reported' } + [PSCustomObject]@{ SessionID = [guid]::NewGuid(); Name = 'Ticket 1'; SessionType = 0 } | + Enter-CWCSession -UrlOnly @Quiet | Should -BeNullOrEmpty + $Reported[-1].FullyQualifiedErrorId | Should -Be 'CWC.Http403,Enter-CWCSession' + "$($Reported[-1])" | Should -Match 'JoinSession' + } + } +} diff --git a/Tests/Live/Invoke-CWCLiveSmokeTest.ps1 b/Tests/Live/Invoke-CWCLiveSmokeTest.ps1 index c86eda3..43aa3ed 100644 --- a/Tests/Live/Invoke-CWCLiveSmokeTest.ps1 +++ b/Tests/Live/Invoke-CWCLiveSmokeTest.ps1 @@ -5,6 +5,7 @@ .DESCRIPTION Read-only by default. -AllowWrites adds actions on ONE test session you choose (a command, a note, a message, an optional toolbox item, a wake) and creates + deletes one throwaway Support session. + -CleanupOnly is the other exception: it deletes the notes earlier runs left on the test session. Records results (no secrets, no headers) to a JSON file. Run once on PS 7 and once on PS 5.1. diff --git a/Tests/test-local.ps1 b/Tests/test-local.ps1 index 7f836a3..14ada73 100644 --- a/Tests/test-local.ps1 +++ b/Tests/test-local.ps1 @@ -3,14 +3,14 @@ Runs the same checks as CI: build, PSScriptAnalyzer, manifest, Pester and docs drift. .DESCRIPTION - CI (.github/workflows/ci.yml) calls this script one stage at a time, so a green local run means a - green CI run. With no parameters it runs every stage. In PowerShell 7 on Windows the Test stage - also re-runs the Pester suite under Windows PowerShell 5.1 (powershell.exe), because the module - must work on both. + CI (.github/workflows/ci.yml) calls this script with one or two stages per job, and the release workflow + with all of them, so a green local run means a green CI run. With no parameters it runs every stage. + In PowerShell 7 on Windows the Test stage also re-runs the Pester suite under Windows PowerShell 5.1 + (powershell.exe), because the module must work on both. Stages: - Build ./build.ps1 -ResolveDependency -Tasks build (Sampler/ModuleBuilder) -> output///. - Needs PowerShell 7. + Build ./build.ps1 -Tasks build (Sampler/ModuleBuilder) -> output///. The first run adds + -ResolveDependency to fetch the pinned tools into output/RequiredModules. Needs PowerShell 7. Analyze PSScriptAnalyzer over source/ with .PSScriptAnalyzerSettings.psd1. Errors fail. Manifest Test-ModuleManifest on the source manifest and, if built, the built one. Test Pester over Tests/ against the BUILT module (what gets published). Live tests skip unless @@ -108,8 +108,8 @@ if ($Stage -contains 'Build') { $Failures.Add('Build: needs PowerShell 7 (run ./build.ps1 from pwsh)') } else { $BuildArgs = @('-NoProfile', '-File', (Join-Path $RepoRoot 'build.ps1'), '-Tasks', 'build') - # Resolve dependencies only when output/RequiredModules is missing. Delete that folder to resolve again - # (after changing a pin in RequiredModules.psd1). + # Resolve dependencies only once: resolving again after a pin changed leaves two versions side by side, + # which the Assert_RequiredModule_Versions task rejects. Delete output/RequiredModules to refresh them. $Resolve = -not (Test-Path $RequiredModulesPath) if ($Resolve) { $BuildArgs += '-ResolveDependency' } # Pin the version to the manifest: Sampler would otherwise use GitVersion when it is installed. diff --git a/source/Public/AuditService/Get-CWCAuditLog.ps1 b/source/Public/AuditService/Get-CWCAuditLog.ps1 index fd21b7c..f3277c3 100644 --- a/source/Public/AuditService/Get-CWCAuditLog.ps1 +++ b/source/Public/AuditService/Get-CWCAuditLog.ps1 @@ -7,10 +7,10 @@ function Get-CWCAuditLog { Calls AuditService.QueryAuditLog. Times are converted to UTC. .PARAMETER StartDate - Start of the time range. Defaults to 24 hours ago. + Start of the time range. Defaults to 24 hours ago. Local times are converted to UTC. .PARAMETER EndDate - End of the time range. Defaults to now. + End of the time range. Defaults to now. Local times are converted to UTC. .PARAMETER SessionName Only return entries for sessions with this name. @@ -19,7 +19,7 @@ function Get-CWCAuditLog { Deprecated. The server no longer accepts this option; it is ignored with a warning. .PARAMETER EventTypes - Session event type numbers to include. + Session event type numbers to include, for example 44 (QueuedCommand) or 70 (RanCommand). .PARAMETER SecurityTypes Security event type numbers to include. @@ -27,6 +27,8 @@ function Get-CWCAuditLog { .EXAMPLE Get-CWCAuditLog -StartDate (Get-Date).AddDays(-7) -SessionName 'DESKTOP-01' + Returns the last 7 days of audit entries for the session named DESKTOP-01. + .NOTES Author: Chris Taylor diff --git a/source/Public/Authentication/Connect-CWC.ps1 b/source/Public/Authentication/Connect-CWC.ps1 index e32007c..b85afd4 100644 --- a/source/Public/Authentication/Connect-CWC.ps1 +++ b/source/Public/Authentication/Connect-CWC.ps1 @@ -89,6 +89,8 @@ function Connect-CWC { $Secret = Read-Host -AsSecureString -Prompt 'RESTful API secret' Connect-CWC -Server 'screenconnect.example.com' -ApiSecret $Secret + Connects with the RESTful API Manager extension's secret. + .NOTES Functions available with -ApiSecret: Get-CWCSessionDetail, Update-CWCSessionName, Invoke-CWCCommand (queues the command; output is not retrieved), Find-CWCSession, diff --git a/source/Public/Extensions/RemoteWorkforce/Add-CWCRemoteWorkforceRequiredRole.ps1 b/source/Public/Extensions/RemoteWorkforce/Add-CWCRemoteWorkforceRequiredRole.ps1 index 18b8bc9..a79a797 100644 --- a/source/Public/Extensions/RemoteWorkforce/Add-CWCRemoteWorkforceRequiredRole.ps1 +++ b/source/Public/Extensions/RemoteWorkforce/Add-CWCRemoteWorkforceRequiredRole.ps1 @@ -15,6 +15,7 @@ function Add-CWCRemoteWorkforceRequiredRole { Add-CWCRemoteWorkforceRequiredRole .NOTES + Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Pair with Initialize-CWCRemoteWorkforceSessionGroup. Author: Chris Taylor diff --git a/source/Public/Extensions/RemoteWorkforce/Get-CWCLauncURL.ps1 b/source/Public/Extensions/RemoteWorkforce/Get-CWCLauncURL.ps1 index 9dd685a..901a5de 100644 --- a/source/Public/Extensions/RemoteWorkforce/Get-CWCLauncURL.ps1 +++ b/source/Public/Extensions/RemoteWorkforce/Get-CWCLauncURL.ps1 @@ -28,7 +28,10 @@ function Get-CWCLauncURL { Ignored. Not accepted by the server. .EXAMPLE - Get-CWCRemoteWorkforceLaunchURL -GUID $SessionID + Get-CWCLauncURL -GUID $SessionID + + Warns that the command is deprecated and returns what Get-CWCRemoteWorkforceLaunchURL -GUID $SessionID + returns. Use that command in new scripts. .NOTES Deprecated in favor of Get-CWCRemoteWorkforceLaunchURL. diff --git a/source/Public/Extensions/RemoteWorkforce/Get-CWCRemoteWorkforceLaunchURL.ps1 b/source/Public/Extensions/RemoteWorkforce/Get-CWCRemoteWorkforceLaunchURL.ps1 index e6e6820..fb38789 100644 --- a/source/Public/Extensions/RemoteWorkforce/Get-CWCRemoteWorkforceLaunchURL.ps1 +++ b/source/Public/Extensions/RemoteWorkforce/Get-CWCRemoteWorkforceLaunchURL.ps1 @@ -28,6 +28,7 @@ function Get-CWCRemoteWorkforceLaunchURL { Get-CWCRemoteWorkforceLaunchURL -SessionName 'DESKTOP-01' .NOTES + Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor diff --git a/source/Public/Extensions/RemoteWorkforce/Get-CWCRemoteWorkforceSession.ps1 b/source/Public/Extensions/RemoteWorkforce/Get-CWCRemoteWorkforceSession.ps1 index aa84acb..981560c 100644 --- a/source/Public/Extensions/RemoteWorkforce/Get-CWCRemoteWorkforceSession.ps1 +++ b/source/Public/Extensions/RemoteWorkforce/Get-CWCRemoteWorkforceSession.ps1 @@ -15,6 +15,7 @@ function Get-CWCRemoteWorkforceSession { Get-CWCRemoteWorkforceSession | Get-CWCRemoteWorkforceLaunchURL .NOTES + Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor diff --git a/source/Public/Extensions/RemoteWorkforce/Initialize-CWCRemoteWorkforceSessionGroup.ps1 b/source/Public/Extensions/RemoteWorkforce/Initialize-CWCRemoteWorkforceSessionGroup.ps1 index 51ec8e0..29ca6c4 100644 --- a/source/Public/Extensions/RemoteWorkforce/Initialize-CWCRemoteWorkforceSessionGroup.ps1 +++ b/source/Public/Extensions/RemoteWorkforce/Initialize-CWCRemoteWorkforceSessionGroup.ps1 @@ -16,6 +16,7 @@ function Initialize-CWCRemoteWorkforceSessionGroup { Initialize-CWCRemoteWorkforceSessionGroup .NOTES + Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor diff --git a/source/Public/Helpers/New-CWCMFA.ps1 b/source/Public/Helpers/New-CWCMFA.ps1 index 2667dea..5df389b 100644 --- a/source/Public/Helpers/New-CWCMFA.ps1 +++ b/source/Public/Helpers/New-CWCMFA.ps1 @@ -12,7 +12,7 @@ function New-CWCMFA { secret to that service. .PARAMETER DisplayName - Label the authenticator app shows for the entry. + Label the authenticator app shows for the entry. Defaults to 'ScreenConnect'. .PARAMETER UserAccount Account name the authenticator app shows for the entry. @@ -24,7 +24,14 @@ function New-CWCMFA { Creates a secret for jdoe and shows the value to store on the account. .OUTPUTS - PSCustomObject with QR (URL of the QR code image) and OTP ("ms:"). + PSCustomObject with QR (URL of the QR code image) and OTP ("ms:" followed by the secret). + + .NOTES + Works without a connection. + Author: Chris Taylor + + .LINK + https://github.com/christaylorcodes/ConnectWiseControlAPI #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'None')] param( diff --git a/source/Public/PageService/Enter-CWCSession.ps1 b/source/Public/PageService/Enter-CWCSession.ps1 index 3bca7db..315a96c 100644 --- a/source/Public/PageService/Enter-CWCSession.ps1 +++ b/source/Public/PageService/Enter-CWCSession.ps1 @@ -143,7 +143,17 @@ function Enter-CWCSession { } if (-not $Token) { try { $Token = New-CWCAccessToken -Group $SessionGroup -GUID $GUID -ErrorAction Stop } - catch { return Write-Error "Could not get an access token for session $GUID (JoinSession permission in '$GroupText' is required): $($_.Exception.Message)" } + catch { + $TokenMessage = "Could not get an access token for session $GUID (the JoinSession permission in " + + "'$GroupText' is needed): $($_.Exception.Message)" + $TokenErrorId = "$($_.FullyQualifiedErrorId)".Split(',')[0] + if ($TokenErrorId -notlike 'CWC.*') { return Write-Error $TokenMessage } + # Keep the transport's ErrorId (CWC.Http403, CWC.NoResponse, ...), category and exception + $TokenException = New-Object System.Exception($TokenMessage, $_.Exception) + $TokenRecord = New-Object System.Management.Automation.ErrorRecord( + $TokenException, $TokenErrorId, $_.CategoryInfo.Category, $GUID) + return $PSCmdlet.WriteError($TokenRecord) + } } if (-not $Token) { return Write-Error "The server returned no access token for session $GUID." } diff --git a/source/Public/PageService/Get-CWCLastContact.ps1 b/source/Public/PageService/Get-CWCLastContact.ps1 index fbf61bc..0cee9eb 100644 --- a/source/Public/PageService/Get-CWCLastContact.ps1 +++ b/source/Public/PageService/Get-CWCLastContact.ps1 @@ -15,7 +15,8 @@ function Get-CWCLastContact { Return $True or $False instead of a date. .PARAMETER Seconds - Used with -Quiet: how recent the last contact must be to count. + Used with -Quiet: how recent the last contact must be to count. Defaults to 0, so only a guest that + is connected now counts. .PARAMETER Group Session group containing the session: a name, or the path parts of a nested group. Defaults to @@ -24,7 +25,10 @@ function Get-CWCLastContact { .EXAMPLE Get-CWCLastContact -GUID $SessionID -Quiet -Seconds 300 + Returns $True when the machine is connected or was connected in the last 5 minutes. + .NOTES + Requires Connect-CWC -Credentials. Author: Chris Taylor .LINK diff --git a/source/Public/PageService/Get-CWCSession.ps1 b/source/Public/PageService/Get-CWCSession.ps1 index face76f..86fc6ff 100644 --- a/source/Public/PageService/Get-CWCSession.ps1 +++ b/source/Public/PageService/Get-CWCSession.ps1 @@ -26,6 +26,12 @@ function Get-CWCSession { .EXAMPLE Get-CWCSession -Type Access -Search 'DESKTOP-01' -Limit 1 + Returns the first Access session that matches DESKTOP-01. Its SessionID is the -GUID the other + session commands take. + + .OUTPUTS + ScreenConnect session objects. + .NOTES Requires Connect-CWC -Credentials. Author: Chris Taylor diff --git a/source/Public/PageService/Get-CWCSessionDetail.ps1 b/source/Public/PageService/Get-CWCSessionDetail.ps1 index 3ab62c5..34897c0 100644 --- a/source/Public/PageService/Get-CWCSessionDetail.ps1 +++ b/source/Public/PageService/Get-CWCSessionDetail.ps1 @@ -19,11 +19,19 @@ function Get-CWCSessionDetail { .PARAMETER Include Parts to return: SessionInfo, GuestScreenshotContent, Events, Connections. Omit for everything, - including the guest screenshot. Request only what you need when polling. + including the guest screenshot. Request only what you need when polling. Ignored on API secret + connections. .EXAMPLE (Get-CWCSessionDetail -GUID $SessionID -Include Events).Events | Where-Object EventType -eq 32 + Returns the note events of the session (event type 32 is AddedNote), without downloading the + screenshot. A deleted note stays in the list; a later event whose CorrelationEventID is the note's + EventID marks it as deleted. + + .OUTPUTS + The session details object the server returns. + .NOTES Author: Chris Taylor diff --git a/source/Public/PageService/Invoke-CWCCommand.ps1 b/source/Public/PageService/Invoke-CWCCommand.ps1 index 5118ace..6a5bfbe 100644 --- a/source/Public/PageService/Invoke-CWCCommand.ps1 +++ b/source/Public/PageService/Invoke-CWCCommand.ps1 @@ -32,9 +32,19 @@ function Invoke-CWCCommand { .PARAMETER NoWait Queue the command and return without waiting for output. + .EXAMPLE + Invoke-CWCCommand -GUID $SessionID -Command 'hostname' + + Runs hostname in cmd.exe on the machine and returns its output. + .EXAMPLE Invoke-CWCCommand -GUID $SessionID -Command 'Get-Service Spooler' -PowerShell -TimeOut 30000 + Runs a PowerShell command and waits up to 30 seconds for its output. + + .OUTPUTS + The output of the command, as text. Nothing with -NoWait or on an API secret connection. + .NOTES Author: Chris Taylor diff --git a/source/Public/PageService/Remove-CWCSession.ps1 b/source/Public/PageService/Remove-CWCSession.ps1 index 4ac9f3a..3a81b79 100644 --- a/source/Public/PageService/Remove-CWCSession.ps1 +++ b/source/Public/PageService/Remove-CWCSession.ps1 @@ -27,6 +27,8 @@ function Remove-CWCSession .LINK https://github.com/christaylorcodes/ConnectWiseControlAPI #> + + # (Blank line above: a comment directly after the help block becomes part of the help.) # ConfirmImpact High: deleting (or uninstalling) sessions is irreversible, and -GUID accepts # many IDs at once, so prompt by default. [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')] diff --git a/source/Public/PageService/Remove-CWCSessionNote.ps1 b/source/Public/PageService/Remove-CWCSessionNote.ps1 index 1f623a2..9d48709 100644 --- a/source/Public/PageService/Remove-CWCSessionNote.ps1 +++ b/source/Public/PageService/Remove-CWCSessionNote.ps1 @@ -42,6 +42,8 @@ function Remove-CWCSessionNote { .LINK https://github.com/christaylorcodes/ConnectWiseControlAPI #> + + # (Blank line above: a comment directly after the help block becomes part of the help.) # ConfirmImpact High: removed notes can't be restored, and -All can remove many at once [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High', DefaultParameterSetName = 'ById')] param( diff --git a/source/Public/SecurityService/New-CWCUser.ps1 b/source/Public/SecurityService/New-CWCUser.ps1 index 3b81a91..f004c80 100644 --- a/source/Public/SecurityService/New-CWCUser.ps1 +++ b/source/Public/SecurityService/New-CWCUser.ps1 @@ -25,7 +25,16 @@ function New-CWCUser { Force the user to change their password at next login. Defaults to $true. .EXAMPLE - New-CWCUser -Credentials (Get-Credential -UserName 'jdoe') -Email 'jdoe@example.com' -SecurityGroups 'Technicians' + $Credentials = Get-Credential -UserName 'jdoe' -Message 'Password for the new user' + New-CWCUser -Credentials $Credentials -Email 'jdoe@example.com' -SecurityGroups 'Technicians' + + Creates the user jdoe in the Technicians role. The user must change the password at first login. + + .EXAMPLE + $Mfa = New-CWCMFA -UserAccount 'jdoe' + New-CWCUser -Credentials $Credentials -OTP $Mfa.OTP -SecurityGroups 'Technicians' -ForcePassChange $false + + Creates the user with an authenticator-app secret and without a forced password change. .NOTES Author: Chris Taylor diff --git a/source/Public/SecurityService/Update-CWCUser.ps1 b/source/Public/SecurityService/Update-CWCUser.ps1 index 973efaa..8fb80ab 100644 --- a/source/Public/SecurityService/Update-CWCUser.ps1 +++ b/source/Public/SecurityService/Update-CWCUser.ps1 @@ -5,7 +5,8 @@ function Update-CWCUser { .DESCRIPTION Reads the user, applies the given changes and saves it (SecurityService.SaveUser). Parameters not - given keep their current values. The password is never written to verbose or debug output. + given keep their current values, with one exception: "change password at next login" is switched + off unless -ForcePassChange is given. The password is never written to verbose or debug output. .PARAMETER UserToUpdate User name of the account to update. @@ -26,13 +27,17 @@ function Update-CWCUser { New email address. .PARAMETER SecurityGroups - Roles the user should be a member of. + Roles the user should be a member of. Replaces the current list. An empty list is ignored, so this + cannot remove every role. .PARAMETER ForcePassChange - Force the user to change their password at next login. + Force the user to change their password at next login. Without it the setting is switched off, even + when it was on before. .EXAMPLE - Update-CWCUser -UserToUpdate 'jdoe' -Password (Read-Host -AsSecureString) + Update-CWCUser -UserToUpdate 'jdoe' -Password (Read-Host -AsSecureString) -ForcePassChange $True + + Sets a new password for jdoe and makes them change it at the next login. .NOTES Author: Chris Taylor diff --git a/source/en-US/ConnectWiseControlAPI-help.xml b/source/en-US/ConnectWiseControlAPI-help.xml index 1e29b22..39977a2 100644 --- a/source/en-US/ConnectWiseControlAPI-help.xml +++ b/source/en-US/ConnectWiseControlAPI-help.xml @@ -6,11 +6,12 @@ Add CWCRemoteWorkforceRequiredRole - Create a new Remote Workforce security role + Creates the security role required by the Remote Workforce extension. - Sometimes Remote Workforce doesn't create the required security role. This will create that role. + Calls the Remote Workforce extension's EnsureRemoteWorkforceSecurityRoleExists endpoint. The extension creates its role (name from the extension's RoleName setting, "Remote Workforce" by default) with View Session Group, Join Session and Host Session Without Consent scoped to the extension's session group, then marks the role as created in the extension settings. + Idempotent: if the role already exists nothing is changed. Requires the Administer permission. @@ -69,19 +70,24 @@ - + Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Pair with Initialize-CWCRemoteWorkforceSessionGroup. Author: Chris Taylor - -------------------------- Example 1 -------------------------- - PS C:\> Add-CWCRemoteWorkforceRequiredRole + -------------------------- EXAMPLE 1 -------------------------- + Add-CWCRemoteWorkforceRequiredRole - Adds the Remote Workforce security role + - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -607,42 +613,43 @@ Functions available with -ApiSecret: Get-CWCSessionDetail, Update-CWCSessionName, Invoke-CWCCommand (queues the command; output is not retrieved), Find-CWCSession, New-CWCSession, Add-CWCSessionNote, Send-CWCSessionMessage, Send-CWCToolboxItem. Only calls that are safe to repeat (reads, "set to value" updates) are retried on HTTP 500. The API secret is not tied to a ScreenConnect user: the extension does not apply role permissions or session group scoping, so it can act on every session. Treat it like an administrator password. Requires the RESTful API Manager extension (2d558935-686a-4bd0-9991-07539f5fe749). MFA logins are never retried automatically: each attempt counts toward the server's login limits. Errors carry an ErrorId: CWC.MfaRequired, CWC.MfaCodeRejected, CWC.LoginFailed, CWC.LoginThrottled or CWC.NoResponse. The device is never marked as trusted, and the login is never saved to disk. + Author: Chris Taylor - -------------------------- Example 1 -------------------------- - PS C:\> Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) + -------------------------- EXAMPLE 1 -------------------------- + Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) Connects with an account that does not use MFA. - -------------------------- Example 2 -------------------------- - PS C:\> Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) -Mfa + -------------------------- EXAMPLE 2 -------------------------- + Connect-CWC -Server 'screenconnect.example.com' -Credentials (Get-Credential) -Mfa Connects with an account that requires MFA and asks for the one-time code. - -------------------------- Example 3 -------------------------- - PS C:\> Connect-CWC -Server 'screenconnect.example.com' -Credentials $Credential -OneTimeCode (Read-Host 'One-time code') + -------------------------- EXAMPLE 3 -------------------------- + Connect-CWC -Server 'screenconnect.example.com' -Credentials $Credential -OneTimeCode (Read-Host 'One-time code') Connects with an account that requires MFA, using a code you supply. Reading it with Read-Host keeps it out of the command history. - -------------------------- Example 4 -------------------------- - PS C:\> $Credential = Get-Secret -Name 'CWC-Login' -PS C:\> Connect-CWC -Server 'screenconnect.example.com' -Credentials $Credential -TotpSecret (Get-Secret -Name 'CWC-TOTP') + -------------------------- EXAMPLE 4 -------------------------- + $Credential = Get-Secret -Name 'CWC-Login' +Connect-CWC -Server 'screenconnect.example.com' -Credentials $Credential -TotpSecret (Get-Secret -Name 'CWC-TOTP') Unattended login for an account that requires MFA. Run it again before each batch of work: when the cached login is still valid it costs one call, and when it has expired it logs in again. - -------------------------- Example 5 -------------------------- - PS C:\> $Secret = Read-Host -AsSecureString -Prompt 'RESTful API secret' -PS C:\> Connect-CWC -Server 'screenconnect.example.com' -ApiSecret $Secret + -------------------------- EXAMPLE 5 -------------------------- + $Secret = Read-Host -AsSecureString -Prompt 'RESTful API secret' +Connect-CWC -Server 'screenconnect.example.com' -ApiSecret $Secret Connects with the RESTful API Manager extension's secret. @@ -699,7 +706,7 @@ PS C:\> Connect-CWC -Server 'screenconnect.example.com' -ApiSecret $Secret Group - Session group containing the session. Defaults to 'All Machines' for Access, 'All Sessions' for Support and 'All Meetings' for Meeting. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines' for Access, 'All Sessions' for Support and 'All Meetings' for Meeting. String[] @@ -761,7 +768,7 @@ PS C:\> Connect-CWC -Server 'screenconnect.example.com' -ApiSecret $Secret Group - Session group containing the session. Defaults to 'All Machines' for Access, 'All Sessions' for Support and 'All Meetings' for Meeting. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines' for Access, 'All Sessions' for Support and 'All Meetings' for Meeting. String[] @@ -977,11 +984,11 @@ open $Url # macOS Get CWCAuditInfo - Shows current audit settings + Shows the current audit settings. - Shows current audit settings + Calls AuditService.GetAuditInfo. @@ -989,41 +996,28 @@ open $Url # macOS - - - - None - - - - - - - - - - System.Object - - - - - - + + - + Author: Chris Taylor - -------------------------- Example 1 -------------------------- - PS C:\> Get-CWCAuditInfo + -------------------------- EXAMPLE 1 -------------------------- + Get-CWCAuditInfo - Displays the current audit settings + - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -1031,11 +1025,11 @@ open $Url # macOS Get CWCAuditLog - Pull audit log information + Returns audit log entries for a time range. - Returns the same information as the audit search in web + Calls AuditService.QueryAuditLog. Times are converted to UTC. @@ -1050,7 +1044,7 @@ open $Url # macOS DateTime - None + (Get-Date).AddDays(-1) EndDate @@ -1062,7 +1056,7 @@ open $Url # macOS DateTime - None + (Get-Date) SessionName @@ -1079,7 +1073,7 @@ open $Url # macOS EventTypes - Session event type numbers to include (for example 44 for QueuedCommand, 70 for RanCommand). + Session event type numbers to include, for example 44 (QueuedCommand) or 70 (RanCommand). Int32[] @@ -1124,7 +1118,7 @@ open $Url # macOS DateTime - None + (Get-Date).AddDays(-1) EndDate @@ -1136,7 +1130,7 @@ open $Url # macOS DateTime - None + (Get-Date) SessionName @@ -1165,7 +1159,7 @@ open $Url # macOS EventTypes - Session event type numbers to include (for example 44 for QueuedCommand, 70 for RanCommand). + Session event type numbers to include, for example 44 (QueuedCommand) or 70 (RanCommand). Int32[] @@ -1187,41 +1181,28 @@ open $Url # macOS None - - - - None - - - - - - - - - - System.Object - - - - - - + + - + Author: Chris Taylor - -------------------------- Example 1 -------------------------- - PS C:\> Get-CWCAuditLog -StartDate $(Get-Date).AddDays(-1) -EndDate $(Get-Date) -SessionName 'Computer1' + -------------------------- EXAMPLE 1 -------------------------- + Get-CWCAuditLog -StartDate (Get-Date).AddDays(-7) -SessionName 'DESKTOP-01' - Get the audit logs for Computer1 for the last day. + Returns the last 7 days of audit entries for the session named DESKTOP-01. - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -1229,11 +1210,11 @@ open $Url # macOS Get CWCLastContact - Returns the date the machine last connected to the ScreenConnect server. + Returns when a machine was last connected, or whether it connected recently. - Returns the date the machine last connected to the ScreenConnect server. + Reads the session's connect/disconnect events. Returns the current time if the guest is connected now, otherwise the time of its last disconnect. With -Quiet, returns $True when the guest is connected or was connected within -Seconds, else $False. @@ -1241,8 +1222,7 @@ open $Url # macOS GUID - The GUID/SessionID for the machine you wish to connect to. You can retrieve session info with the 'Get-CWCSessions' cmdlets - On Windows clients, the launch parameters are located in the registry at: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ScreenConnect Client (xxxxxxxxxxxxxxxx)\ImagePath On Linux and Mac clients, it's found in the ClientLaunchParameters.txt file in the client installation folder: /opt/screenconnect-xxxxxxxxxxxxxxxx/ClientLaunchParameters.txt + Session ID. Guid @@ -1254,7 +1234,7 @@ open $Url # macOS Quiet - Will output a boolean result, $True for Connected or $False for Offline. + Return $True or $False instead of a date. SwitchParameter @@ -1265,7 +1245,7 @@ open $Url # macOS Seconds - Used with the Quiet switch. The number of seconds a machine needs to be offline before returning $False. + Used with -Quiet: how recent the last contact must be to count. Defaults to 0, so only a guest that is connected now counts. Int32 @@ -1277,7 +1257,7 @@ open $Url # macOS Group - Name of session group to use. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -1292,8 +1272,7 @@ open $Url # macOS GUID - The GUID/SessionID for the machine you wish to connect to. You can retrieve session info with the 'Get-CWCSessions' cmdlets - On Windows clients, the launch parameters are located in the registry at: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ScreenConnect Client (xxxxxxxxxxxxxxxx)\ImagePath On Linux and Mac clients, it's found in the ClientLaunchParameters.txt file in the client installation folder: /opt/screenconnect-xxxxxxxxxxxxxxxx/ClientLaunchParameters.txt + Session ID. Guid @@ -1305,7 +1284,7 @@ open $Url # macOS Quiet - Will output a boolean result, $True for Connected or $False for Offline. + Return $True or $False instead of a date. SwitchParameter @@ -1317,7 +1296,7 @@ open $Url # macOS Seconds - Used with the Quiet switch. The number of seconds a machine needs to be offline before returning $False. + Used with -Quiet: how recent the last contact must be to count. Defaults to 0, so only a guest that is connected now counts. Int32 @@ -1329,7 +1308,7 @@ open $Url # macOS Group - Name of session group to use. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -1343,7 +1322,15 @@ open $Url # macOS - [datetime] -or [boolean] + System.Boolean + + + + + + + + System.DateTime @@ -1352,20 +1339,24 @@ open $Url # macOS - Version: 1.1 Author: Chris Taylor Creation Date: 1/20/2016 Purpose/Change: Initial script development - Update Date: 8/24/2018 Purpose/Change: Fix TimeSpan Seconds duration + Requires Connect-CWC -Credentials. Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - Get-CWCLastContact -GUID $GUID + Get-CWCLastContact -GUID $SessionID -Quiet -Seconds 300 - Will return the last contact of the machine with that GUID. + Returns $True when the machine is connected or was connected in the last 5 minutes. - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -1586,9 +1577,9 @@ open $Url # macOS -------------------------- EXAMPLE 1 -------------------------- - Get-CWCRemoteWorkforceLaunchURL -GUID $SessionID + Get-CWCLauncURL -GUID $SessionID - + Warns that the command is deprecated and returns what Get-CWCRemoteWorkforceLaunchURL -GUID $SessionID returns. Use that command in new scripts. @@ -1674,7 +1665,7 @@ open $Url # macOS - Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor + Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor @@ -1729,7 +1720,7 @@ open $Url # macOS - Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor + Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor @@ -1761,11 +1752,11 @@ open $Url # macOS Get CWCSecurityConfigurationInfo - Will return security configuration information. + Returns the server's security configuration (user sources, roles, users). - Will return security configuration information. + Calls SecurityService.GetSecurityConfigurationInfo. @@ -1777,19 +1768,24 @@ open $Url # macOS - Version: 1.0 Author: Chris Taylor Creation Date: 1/15/2019 Purpose/Change: Initial script development + Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - Get-CWCSecurityConfigurationInfo + (Get-CWCSecurityConfigurationInfo).UserSources - Returns security configuration + - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -1797,11 +1793,11 @@ open $Url # macOS Get CWCSession - Will return a list of sessions. + Lists sessions of one type in a session group. - Allows you to search for access, service or meeting sessions. + Calls PageService.GetLiveData, the same query the web UI's session list uses. @@ -1809,7 +1805,7 @@ open $Url # macOS Type - The type of session Support/Access/Meeting + Session type: Support, Access or Meeting. Object @@ -1821,19 +1817,19 @@ open $Url # macOS Group - Name of session group to use. + Session group: a name, or the path parts of a nested group (e.g. 'Clients','Acme'). Defaults to the built-in group for -Type: 'All Machines' (Access), 'All Sessions' (Support) or 'All Meetings' (Meeting). String[] String[] - All Machines + None Search - Limit results with search pattern. + Filter text, as typed in the web UI's search box. String @@ -1845,7 +1841,7 @@ open $Url # macOS FindSessionID - Session ID to locate in the results, so the session is included even when -Limit would cut it off. + Session ID to locate, so it is included even when -Limit would cut it off. String @@ -1857,7 +1853,7 @@ open $Url # macOS Limit - Limit the number of results returned. + Maximum number of sessions to return. Int32 @@ -1872,7 +1868,7 @@ open $Url # macOS Type - The type of session Support/Access/Meeting + Session type: Support, Access or Meeting. Object @@ -1884,19 +1880,19 @@ open $Url # macOS Group - Name of session group to use. + Session group: a name, or the path parts of a nested group (e.g. 'Clients','Acme'). Defaults to the built-in group for -Type: 'All Machines' (Access), 'All Sessions' (Support) or 'All Meetings' (Meeting). String[] String[] - All Machines + None Search - Limit results with search pattern. + Filter text, as typed in the web UI's search box. String @@ -1908,7 +1904,7 @@ open $Url # macOS FindSessionID - Session ID to locate in the results, so the session is included even when -Limit would cut it off. + Session ID to locate, so it is included even when -Limit would cut it off. String @@ -1920,7 +1916,7 @@ open $Url # macOS Limit - Limit the number of results returned. + Maximum number of sessions to return. Int32 @@ -1934,7 +1930,7 @@ open $Url # macOS - ConnectWise ScreenConnect session objects + ScreenConnect session objects. @@ -1943,19 +1939,24 @@ open $Url # macOS - Version: 1.0 Author: Chris Taylor Creation Date: 10/10/2018 Purpose/Change: Initial script development + Requires Connect-CWC -Credentials. Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - Get-CWCSessions -Type 'Access' -Search 'server1' -Limit 10 + Get-CWCSession -Type Access -Search 'DESKTOP-01' -Limit 1 - Will return the first 10 access sessions that match 'server1'. + Returns the first Access session that matches DESKTOP-01. Its SessionID is the -GUID the other session commands take. - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -1963,11 +1964,12 @@ open $Url # macOS Get CWCSessionDetail - Will return information about a session. + Returns the details of a session: session info, events, connections and guest screenshot. - Displays more information about a session. + Credentials connections: PageService.GetSessionDetails. Event Time values are milliseconds elapsed since the event, relative to the response's BaseTime. The call is rate limited by the server. + API secret connections: the RESTful API Manager extension's GetSessionDetailsBySessionID, which returns the server's raw session details; -Group and -Include are ignored. @@ -1975,7 +1977,7 @@ open $Url # macOS Group - Name of session group to use. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -1987,7 +1989,7 @@ open $Url # macOS GUID - GUID of the machine to retrieve session details. + Session ID. Guid @@ -1999,7 +2001,7 @@ open $Url # macOS Include - Parts of the session details to return: SessionInfo, GuestScreenshotContent, Events, Connections. Omit to return everything, including the guest screenshot. Ignored on -ApiSecret connections. + Parts to return: SessionInfo, GuestScreenshotContent, Events, Connections. Omit for everything, including the guest screenshot. Request only what you need when polling. Ignored on API secret connections. String[] @@ -2014,7 +2016,7 @@ open $Url # macOS Group - Name of session group to use. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -2026,7 +2028,7 @@ open $Url # macOS GUID - GUID of the machine to retrieve session details. + Session ID. Guid @@ -2038,7 +2040,7 @@ open $Url # macOS Include - Parts of the session details to return: SessionInfo, GuestScreenshotContent, Events, Connections. Omit to return everything, including the guest screenshot. Ignored on -ApiSecret connections. + Parts to return: SessionInfo, GuestScreenshotContent, Events, Connections. Omit for everything, including the guest screenshot. Request only what you need when polling. Ignored on API secret connections. String[] @@ -2052,7 +2054,7 @@ open $Url # macOS - ConnectWise ScreenConnect session objects + The session details object the server returns. @@ -2061,19 +2063,24 @@ open $Url # macOS - Version: 1.0 Author: Chris Taylor Creation Date: 1/15/2019 Purpose/Change: Initial script development + Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - Get-CWCSessionDetail -Group 'All Sessions' -GUID $Session.SessionID + (Get-CWCSessionDetail -GUID $SessionID -Include Events).Events | Where-Object EventType -eq 32 - Will return details of the requested session. + Returns the note events of the session (event type 32 is AddedNote), without downloading the screenshot. A deleted note stays in the list; a later event whose CorrelationEventID is the note's EventID marks it as deleted. - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -2081,11 +2088,11 @@ open $Url # macOS Get CWCSessionGroup - Returns details of all session groups. + Returns all session groups. - Returns details of all session groups. + Calls SessionGroupService.GetSessionGroups. Requires the ManageSessionGroups permission. @@ -2093,41 +2100,28 @@ open $Url # macOS - - - - None - - - - - - - - - - System.Object - - - - - - + + - + Author: Chris Taylor - -------------------------- Example 1 -------------------------- - PS C:\> Get-CWCSessionGroup + -------------------------- EXAMPLE 1 -------------------------- + Get-CWCSessionGroup | Select-Object Name, SessionType - Returns details of all session groups. + - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -2199,7 +2193,7 @@ open $Url # macOS - Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor + Requires Connect-CWC -Credentials. Requires the Remote Workforce extension (2c4f522f-b39a-413a-8807-dc52a2fce13e), ScreenConnect 23.6+. Author: Chris Taylor @@ -2224,11 +2218,12 @@ open $Url # macOS Invoke CWCCommand - Will issue a command against a given machine and return the results. + Runs a command on a session's machine and returns its output. - Will issue a command against a given machine and return the results. + Queues a QueuedCommand event (44) and polls the session's events until the matching RanCommand output (70) arrives or -TimeOut passes. + API secret connections queue the command through the RESTful API Manager extension; the output is not retrieved (a warning says so unless -NoWait is used). @@ -2236,7 +2231,7 @@ open $Url # macOS GUID - The GUID identifier for the machine you wish to connect to. You can retrieve session info with the 'Get-CWCSessions' cmdlets + Session ID. Guid @@ -2248,7 +2243,7 @@ open $Url # macOS Command - The command you wish to issue to the machine. + Command line to run (cmd.exe unless -PowerShell is used). String @@ -2260,7 +2255,7 @@ open $Url # macOS TimeOut - The amount of time in milliseconds that a command can execute. The default is 10000 milliseconds. + Milliseconds the command may run, and how long to wait for its output. Defaults to 10000. Int32 @@ -2272,19 +2267,19 @@ open $Url # macOS MaxLength - Maximum number of characters of command output to return. Defaults to 10000. + Maximum number of characters of output to return. Defaults to 10000. Int32 Int32 - None + 10000 Group - Name of session group to use. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -2296,7 +2291,7 @@ open $Url # macOS PowerShell - Issues the command in a powershell session. + Run the command in PowerShell. SwitchParameter @@ -2307,7 +2302,7 @@ open $Url # macOS NoWait - Will not wait for the output of the command. + Queue the command and return without waiting for output. SwitchParameter @@ -2321,7 +2316,7 @@ open $Url # macOS GUID - The GUID identifier for the machine you wish to connect to. You can retrieve session info with the 'Get-CWCSessions' cmdlets + Session ID. Guid @@ -2333,7 +2328,7 @@ open $Url # macOS Command - The command you wish to issue to the machine. + Command line to run (cmd.exe unless -PowerShell is used). String @@ -2345,7 +2340,7 @@ open $Url # macOS TimeOut - The amount of time in milliseconds that a command can execute. The default is 10000 milliseconds. + Milliseconds the command may run, and how long to wait for its output. Defaults to 10000. Int32 @@ -2357,19 +2352,19 @@ open $Url # macOS MaxLength - Maximum number of characters of command output to return. Defaults to 10000. + Maximum number of characters of output to return. Defaults to 10000. Int32 Int32 - None + 10000 PowerShell - Issues the command in a powershell session. + Run the command in PowerShell. SwitchParameter @@ -2381,7 +2376,7 @@ open $Url # macOS Group - Name of session group to use. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -2393,7 +2388,7 @@ open $Url # macOS NoWait - Will not wait for the output of the command. + Queue the command and return without waiting for output. SwitchParameter @@ -2407,7 +2402,7 @@ open $Url # macOS - The output of the Command provided. + The output of the command, as text. Nothing with -NoWait or on an API secret connection. @@ -2416,29 +2411,31 @@ open $Url # macOS - Version: 1.0 - Author: Chris Taylor - Creation Date: 1/20/2016 - Purpose/Change: Initial script development + Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - Invoke-CWCCommand -GUID $GUID -Command 'hostname' + Invoke-CWCCommand -GUID $SessionID -Command 'hostname' - Will return the hostname of the machine. + Runs hostname in cmd.exe on the machine and returns its output. -------------------------- EXAMPLE 2 -------------------------- - Invoke-CWCCommand -GUID $GUID -TimeOut 120000 -Command 'iwr -UseBasicParsing "https://bit.ly/ltposh" | iex; Restart-LTService' -PowerShell + Invoke-CWCCommand -GUID $SessionID -Command 'Get-Service Spooler' -PowerShell -TimeOut 30000 - Will restart the Automate agent on the target machine. + Runs a PowerShell command and waits up to 30 seconds for its output. - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -2446,11 +2443,11 @@ open $Url # macOS Invoke CWCWake - Will issue a wake command to a given session. + Sends a wake (Wake-on-LAN) request to sessions. - Will issue a wake command to a given access or support session. + Queues a QueuedWake event (43) for each session, in the built-in group for -Type. @@ -2458,7 +2455,7 @@ open $Url # macOS GUID - The GUID identifier for the session you wish to end. Accepts an array of GUIDs + One or more session IDs. Guid[] @@ -2470,7 +2467,7 @@ open $Url # macOS Type - The type of session Support/Access + Session type: Support or Access. String @@ -2485,7 +2482,7 @@ open $Url # macOS GUID - The GUID identifier for the session you wish to end. Accepts an array of GUIDs + One or more session IDs. Guid[] @@ -2497,7 +2494,7 @@ open $Url # macOS Type - The type of session Support/Access + Session type: Support or Access. String @@ -2511,19 +2508,24 @@ open $Url # macOS - Version: 1.0 Author: Chris Taylor Creation Date: 12/7/2018 Purpose/Change: Initial script development + Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - End-CWWake -GUID $GUID + Invoke-CWCWake -GUID $SessionID -Type Access - Will issue a wake command to a given session. + - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -2543,7 +2545,7 @@ open $Url # macOS Group - Session group containing the session. Defaults to 'All Machines'. + Session group containing the session: a name, or the path parts of a nested group (e.g. 'Clients','Acme'). Defaults to 'All Machines'. String[] @@ -2570,7 +2572,7 @@ open $Url # macOS Group - Session group containing the session. Defaults to 'All Machines'. + Session group containing the session: a name, or the path parts of a nested group (e.g. 'Clients','Acme'). Defaults to 'All Machines'. String[] @@ -2634,7 +2636,7 @@ open $Url # macOS DisplayName - Label the authenticator app shows for the entry. + Label the authenticator app shows for the entry. Defaults to 'ScreenConnect'. Object @@ -2646,7 +2648,7 @@ open $Url # macOS UserAccount - User account to display in OTP app. + Account name the authenticator app shows for the entry. Object @@ -2683,7 +2685,7 @@ open $Url # macOS DisplayName - Label the authenticator app shows for the entry. + Label the authenticator app shows for the entry. Defaults to 'ScreenConnect'. Object @@ -2695,7 +2697,7 @@ open $Url # macOS UserAccount - User account to display in OTP app. + Account name the authenticator app shows for the entry. Object @@ -2729,20 +2731,11 @@ open $Url # macOS False - - - - None - - - - - - + - System.Object + PSCustomObject with QR (URL of the QR code image) and OTP ("ms:" followed by the secret). @@ -2751,19 +2744,25 @@ open $Url # macOS - + Works without a connection. Author: Chris Taylor - -------------------------- Example 1 -------------------------- - PS C:\> New-CWCMFA -DisplayName 'My ScreenConnect Server' -UserAccount 'CTaylor' + -------------------------- EXAMPLE 1 -------------------------- + $Mfa = New-CWCMFA -UserAccount 'jdoe' +$Mfa.OTP - Creates an MFA OTP code and QR URL with the provided information. + Creates a secret for jdoe and shows the value to store on the account. - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -2771,11 +2770,11 @@ open $Url # macOS New CWCRemoteWorkforceAssignment - Assign a user to machines. + Assigns machines to a Remote Workforce user. - Uses the remote workforce extension to assign a user to machines + Calls the Remote Workforce extension's AddAssignmentNoteToSession, which adds an assignment note (AddedNote) to each session. The user can then launch the machine from the Remote Workforce page. @@ -2783,7 +2782,7 @@ open $Url # macOS GUID - GUID of the session you want to assign the user access to. + One or more session IDs. Guid[] @@ -2795,7 +2794,7 @@ open $Url # macOS Username - Username of the account you want to assign remote workforce access to. + ScreenConnect user name of the assignee. String @@ -2807,7 +2806,7 @@ open $Url # macOS DisplayName - Name that is displayed when user is connected to a session. + Display name of the assignee. String @@ -2819,14 +2818,14 @@ open $Url # macOS Group - Session group containing the session(s). Defaults to 'All Machines' where a default exists. + Session group containing the sessions: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] String[] - None + All Machines WhatIf @@ -2856,7 +2855,7 @@ open $Url # macOS GUID - GUID of the session you want to assign the user access to. + One or more session IDs. Guid[] @@ -2868,7 +2867,7 @@ open $Url # macOS Username - Username of the account you want to assign remote workforce access to. + ScreenConnect user name of the assignee. String @@ -2880,7 +2879,7 @@ open $Url # macOS DisplayName - Name that is displayed when user is connected to a session. + Display name of the assignee. String @@ -2892,14 +2891,14 @@ open $Url # macOS Group - Session group containing the session(s). Defaults to 'All Machines' where a default exists. + Session group containing the sessions: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] String[] - None + All Machines WhatIf @@ -2930,22 +2929,24 @@ open $Url # macOS - Version: 1.1 - Author: Chris Taylor - Creation Date: 10/25/2018 - Purpose/Change: Initial script development + Requires Connect-CWC -Credentials and the Remote Workforce extension. Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - PS C:\> New-CWCRemoteWorkforceAssignment -GUID $GUID -Username 'CTaylor' -DisplayName 'Chris Taylor' + New-CWCRemoteWorkforceAssignment -GUID $SessionID -Username 'jdoe' -DisplayName 'Jane Doe' - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -3171,11 +3172,11 @@ open $Url # macOS New CWCUser - Creates a user. + Creates an internal user. - Creates a new local user. + Calls SecurityService.SaveUser. The password is never written to verbose or debug output. @@ -3183,7 +3184,7 @@ open $Url # macOS Credentials - PSCredential object for the new user you want to create. + User name and password of the new user. PSCredential @@ -3195,7 +3196,7 @@ open $Url # macOS OTP - The OTP key used for MFA. Can be generated with `New-CWCMFA` + The OTP key used for MFA. Can be generated with New-CWCMFA. String @@ -3207,7 +3208,7 @@ open $Url # macOS DisplayName - The display name of the new user + Display name. String @@ -3219,7 +3220,7 @@ open $Url # macOS Email - Email address of the user + Email address. String @@ -3231,19 +3232,19 @@ open $Url # macOS SecurityGroups - An array of security groups the user is a part of + Roles the user is a member of. String[] String[] - None + @() ForcePassChange - Force the user to change their password at next login + Force the user to change their password at next login. Defaults to $true. Boolean @@ -3280,7 +3281,7 @@ open $Url # macOS Credentials - PSCredential object for the new user you want to create. + User name and password of the new user. PSCredential @@ -3292,7 +3293,7 @@ open $Url # macOS OTP - The OTP key used for MFA. Can be generated with `New-CWCMFA` + The OTP key used for MFA. Can be generated with New-CWCMFA. String @@ -3304,7 +3305,7 @@ open $Url # macOS DisplayName - The display name of the new user + Display name. String @@ -3316,7 +3317,7 @@ open $Url # macOS Email - Email address of the user + Email address. String @@ -3328,19 +3329,19 @@ open $Url # macOS SecurityGroups - An array of security groups the user is a part of + Roles the user is a member of. String[] String[] - None + @() ForcePassChange - Force the user to change their password at next login + Force the user to change their password at next login. Defaults to $true. Boolean @@ -3378,27 +3379,33 @@ open $Url # macOS - Version: 1.1 Author: Chris Taylor Creation Date: 4/2/2020 Purpose/Change: Initial script development + Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - $NewUserParams = @{ - Credentials = $PSCredentials - OTP = $(New-CWCMFA).OTP - DisplayName = 'Chris Taylor' - Email = 'dont@bug.me' - SecurityGroups = 'MySecurityGroup' - ForcePassChange = $true -} -New-CWCUser @NewUserParams + $Credentials = Get-Credential -UserName 'jdoe' -Message 'Password for the new user' +New-CWCUser -Credentials $Credentials -Email 'jdoe@example.com' -SecurityGroups 'Technicians' - + Creates the user jdoe in the Technicians role. The user must change the password at first login. + + + + -------------------------- EXAMPLE 2 -------------------------- + $Mfa = New-CWCMFA -UserAccount 'jdoe' +New-CWCUser -Credentials $Credentials -OTP $Mfa.OTP -SecurityGroups 'Technicians' -ForcePassChange $false + + Creates the user with an authenticator-app secret and without a forced password change. - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -3568,11 +3575,11 @@ Remove-CWCHostFromSession -SessionID $SessionID -ConnectionID $HostConnection.Co Remove CWCSession - Will end a given session. + Deletes sessions, optionally uninstalling the Access client first. - Will end a given access or support session. + Queues a DeletedSession event (21) per session, or QueuedUninstallAndDelete (100) with -Uninstall. Prompts for each session by default (ConfirmImpact High); use -Confirm:$false in unattended scripts. @@ -3580,7 +3587,7 @@ Remove-CWCHostFromSession -SessionID $SessionID -ConnectionID $HostConnection.Co GUID - The GUID identifier for the session you wish to end. Accepts an array of GUIDs. + One or more session IDs. Guid[] @@ -3592,7 +3599,7 @@ Remove-CWCHostFromSession -SessionID $SessionID -ConnectionID $HostConnection.Co Group - Session group containing the session(s). Defaults to 'All Machines' where a default exists. + Session group containing the sessions: a name, or the path parts of a nested group. String[] @@ -3604,7 +3611,7 @@ Remove-CWCHostFromSession -SessionID $SessionID -ConnectionID $HostConnection.Co Uninstall - Queue an uninstall of the Access client and delete the session (QueuedUninstallAndDelete) instead of only deleting the session record. + Uninstall the Access client from the machine and delete the session, instead of only deleting the session record. SwitchParameter @@ -3640,7 +3647,7 @@ Remove-CWCHostFromSession -SessionID $SessionID -ConnectionID $HostConnection.Co GUID - The GUID identifier for the session you wish to end. Accepts an array of GUIDs. + One or more session IDs. Guid[] @@ -3652,7 +3659,7 @@ Remove-CWCHostFromSession -SessionID $SessionID -ConnectionID $HostConnection.Co Group - Session group containing the session(s). Defaults to 'All Machines' where a default exists. + Session group containing the sessions: a name, or the path parts of a nested group. String[] @@ -3664,7 +3671,7 @@ Remove-CWCHostFromSession -SessionID $SessionID -ConnectionID $HostConnection.Co Uninstall - Queue an uninstall of the Access client and delete the session (QueuedUninstallAndDelete) instead of only deleting the session record. + Uninstall the Access client from the machine and delete the session, instead of only deleting the session record. SwitchParameter @@ -3702,19 +3709,24 @@ Remove-CWCHostFromSession -SessionID $SessionID -ConnectionID $HostConnection.Co - Version: 1.0 Author: Chris Taylor Creation Date: 10/10/2018 Purpose/Change: Initial script development + Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - Remove-CWCAccessSession -GUID $GUID + Remove-CWCSession -GUID $SessionID -Group 'All Machines' -Uninstall -Confirm:$false - Will remove the given access session + - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -3727,7 +3739,7 @@ Remove-CWCHostFromSession -SessionID $SessionID -ConnectionID $HostConnection.Co Deletes notes (AddedNote events) by adding a DeletedEvent correlated to each note, the same way the ScreenConnect web UI removes a note. The user needs the RemoveNote permission in -Group. - -NoteEventID removes specific notes; -All removes every note still on the session. Notes that are already deleted are skipped. + -NoteEventID removes the given notes (without checking them first). -All reads the session and removes every note still on it, skipping notes that are already deleted. @@ -3965,11 +3977,11 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Remove CWCUser - Removes an internal user. + Deletes an internal user. - Removes the provided internal user. + Calls SecurityService.DeleteUser. @@ -3977,7 +3989,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { User - The user to remove. + User name of the account to delete. String @@ -4014,7 +4026,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { User - The user to remove. + User name of the account to delete. String @@ -4048,41 +4060,28 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { False - - - - None - - - - - - - - - - System.Object - - - - - - + + - + Author: Chris Taylor - -------------------------- Example 1 -------------------------- - PS C:\> Remove-CWCUser -User 'ctaylor' + -------------------------- EXAMPLE 1 -------------------------- + Remove-CWCUser -User 'jdoe' - Removes the 'ctaylor' user from ScreenConnect. + - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -4128,7 +4127,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { From - Sender name shown to the guest (API secret connections only). + Sender name shown to the guest (API secret connections only). Defaults to 'RESTful API', the extension's default RESTfulUserName. The extension uses this value, not its RESTfulUserName setting, so pass -From to match a renamed setting (or any name you want the guest to see). String @@ -4201,7 +4200,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { From - Sender name shown to the guest (API secret connections only). + Sender name shown to the guest (API secret connections only). Defaults to 'RESTful API', the extension's default RESTfulUserName. The extension uses this value, not its RESTfulUserName setting, so pass -From to match a renamed setting (or any name you want the guest to see). String @@ -4282,7 +4281,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Queues a QueuedTool session event naming the Toolbox item. Credentials connections: PageService.AddSessionEvents; the user needs the RunSharedTool permission in -Group. - API secret connections: the RESTful API Manager extension's SendToolboxItemToSession; -Group is ignored. + API secret connections: the RESTful API Manager extension's SendToolboxItemToSession. The event is attributed to the extension's RESTfulUserName setting ("RESTful API" unless renamed); -Group is ignored. @@ -4438,11 +4437,11 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Update CWCCustomProperty - Will update a custom property for a session. + Sets one custom property of a session. - Will update a custom property for a session. + Calls PageService.UpdateSessionCustomPropertyValue. @@ -4450,8 +4449,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { GUID - The GUID/SessionID for the machine you wish to connect to. You can retrieve session info with the 'Get-CWCSessions' cmdlets - On Windows clients, the launch parameters are located in the registry at: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ScreenConnect Client (xxxxxxxxxxxxxxxx)\ImagePath On Linux and Mac clients, it's found in the ClientLaunchParameters.txt file in the client installation folder: /opt/screenconnect-xxxxxxxxxxxxxxxx/ClientLaunchParameters.txt + Session ID. Guid @@ -4463,19 +4461,19 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Property - The property number of the property you want to change. + The property number of the property to change. Int32 Int32 - None + 0 Value - The value you want to set the property to. + New value. String @@ -4487,7 +4485,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Group - Look for the session in these groups. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -4524,8 +4522,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { GUID - The GUID/SessionID for the machine you wish to connect to. You can retrieve session info with the 'Get-CWCSessions' cmdlets - On Windows clients, the launch parameters are located in the registry at: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ScreenConnect Client (xxxxxxxxxxxxxxxx)\ImagePath On Linux and Mac clients, it's found in the ClientLaunchParameters.txt file in the client installation folder: /opt/screenconnect-xxxxxxxxxxxxxxxx/ClientLaunchParameters.txt + Session ID. Guid @@ -4537,19 +4534,19 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Property - The property number of the property you want to change. + The property number of the property to change. Int32 Int32 - None + 0 Value - The value you want to set the property to. + New value. String @@ -4561,7 +4558,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Group - Look for the session in these groups. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -4599,22 +4596,24 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { - Version: 1.1 - Author: Chris Taylor - Creation Date: 10/25/2018 - Purpose/Change: Initial script development + Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - Update-CWCCustomProperty -GUID $GUID -Property 2 -Value 'New Department' + Update-CWCCustomProperty -GUID $SessionID -Property 1 -Value 'Acme' - Will update the sessions department to 'New Department' + - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -4622,11 +4621,11 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Update CWCSessionName - Updates the name of a session. + Renames a session. - Updates the name of a session on the ScreenConnect server. + Credentials connections: PageService.UpdateSessionName. API secret connections: the RESTful API Manager extension's UpdateSessionName (-Group is ignored). @@ -4634,8 +4633,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { GUID - The GUID/SessionID for the machine you wish to connect to. You can retrieve session info with the 'Get-CWCSessions' cmdlets - On Windows clients, the launch parameters are located in the registry at: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ScreenConnect Client (xxxxxxxxxxxxxxxx)\ImagePath On Linux and Mac clients, it's found in the ClientLaunchParameters.txt file in the client installation folder: /opt/screenconnect-xxxxxxxxxxxxxxxx/ClientLaunchParameters.txt + Session ID. Guid @@ -4647,7 +4645,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { NewName - The new name for the session. + New session name. String @@ -4659,7 +4657,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Group - Group to look for the session in. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -4696,8 +4694,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { GUID - The GUID/SessionID for the machine you wish to connect to. You can retrieve session info with the 'Get-CWCSessions' cmdlets - On Windows clients, the launch parameters are located in the registry at: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ScreenConnect Client (xxxxxxxxxxxxxxxx)\ImagePath On Linux and Mac clients, it's found in the ClientLaunchParameters.txt file in the client installation folder: /opt/screenconnect-xxxxxxxxxxxxxxxx/ClientLaunchParameters.txt + Session ID. Guid @@ -4709,7 +4706,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { NewName - The new name for the session. + New session name. String @@ -4721,7 +4718,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Group - Group to look for the session in. + Session group containing the session: a name, or the path parts of a nested group. Defaults to 'All Machines'. String[] @@ -4759,19 +4756,24 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { - Version: 1.1 Author: Chris Taylor Creation Date: 10/25/2018 Purpose/Change: Initial script development + Author: Chris Taylor -------------------------- EXAMPLE 1 -------------------------- - Update-CWCSessionName -GUID $GUID -NewName 'Session1' + Update-CWCSessionName -GUID $SessionID -NewName 'ACME-FrontDesk' - Will rename the session to Session1 + - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + @@ -4779,11 +4781,11 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Update CWCUser - Update properties of an internal user. + Updates an internal user. - Will update an internal user. Only the properties given will update. + Reads the user, applies the given changes and saves it (SecurityService.SaveUser). Parameters not given keep their current values, with one exception: "change password at next login" is switched off unless -ForcePassChange is given. The password is never written to verbose or debug output. @@ -4791,7 +4793,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { UserToUpdate - The user account you want to update. + User name of the account to update. String @@ -4803,7 +4805,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { NewUserName - The new username of the user you are updating. + New user name. String @@ -4815,7 +4817,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Password - The wanted password of the user. + New password. SecureString @@ -4827,7 +4829,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { OTP - The wanted MFA option for the user. + The OTP key used for MFA. Can be generated with New-CWCMFA. String @@ -4839,7 +4841,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { DisplayName - The wanted display name for the user. + New display name. String @@ -4851,7 +4853,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Email - The wanted email address for the user. + New email address. String @@ -4863,7 +4865,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { SecurityGroups - The wanted security groups the user should be a member of. + Roles the user should be a member of. Replaces the current list. An empty list is ignored, so this cannot remove every role. String[] @@ -4875,14 +4877,14 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { ForcePassChange - Force the user to change their password at next logon. + Force the user to change their password at next login. Without it the setting is switched off, even when it was on before. Boolean Boolean - None + False WhatIf @@ -4912,7 +4914,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { UserToUpdate - The user account you want to update. + User name of the account to update. String @@ -4924,7 +4926,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { NewUserName - The new username of the user you are updating. + New user name. String @@ -4936,7 +4938,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Password - The wanted password of the user. + New password. SecureString @@ -4948,7 +4950,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { OTP - The wanted MFA option for the user. + The OTP key used for MFA. Can be generated with New-CWCMFA. String @@ -4960,7 +4962,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { DisplayName - The wanted display name for the user. + New display name. String @@ -4972,7 +4974,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { Email - The wanted email address for the user. + New email address. String @@ -4984,7 +4986,7 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { SecurityGroups - The wanted security groups the user should be a member of. + Roles the user should be a member of. Replaces the current list. An empty list is ignored, so this cannot remove every role. String[] @@ -4996,14 +4998,14 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { ForcePassChange - Force the user to change their password at next logon. + Force the user to change their password at next login. Without it the setting is switched off, even when it was on before. Boolean Boolean - None + False WhatIf @@ -5030,40 +5032,27 @@ $Notes | Where-Object Data -like 'Rebooted*' | ForEach-Object { False - - - - None - - - - - - - - - - System.Object - - - - - - + + - + Author: Chris Taylor - -------------------------- Example 1 -------------------------- - PS C:\> Update-CWCUser -UserToUpdate 'ctaylor' -Password $SecureString -ForcePassChange $True + -------------------------- EXAMPLE 1 -------------------------- + Update-CWCUser -UserToUpdate 'jdoe' -Password (Read-Host -AsSecureString) -ForcePassChange $True - Updates the password for 'ctaylor' and forces a password change at next logon. + Sets a new password for jdoe and makes them change it at the next login. - + + + https://github.com/christaylorcodes/ConnectWiseControlAPI + https://github.com/christaylorcodes/ConnectWiseControlAPI + + \ No newline at end of file diff --git a/source/en-US/about_ConnectWiseControlAPI.help.txt b/source/en-US/about_ConnectWiseControlAPI.help.txt index 477e319..cee8559 100644 --- a/source/en-US/about_ConnectWiseControlAPI.help.txt +++ b/source/en-US/about_ConnectWiseControlAPI.help.txt @@ -8,8 +8,8 @@ SHORT DESCRIPTION LONG DESCRIPTION The module wraps the ScreenConnect web API: sessions, session groups, commands, notes, messages, users, the audit log and the Remote Workforce - extension. It runs on Windows PowerShell 5.1 and PowerShell 7. The server - must use https. + extension. It is tested on Windows PowerShell 5.1 and PowerShell 7. The + server must use https. ConnectWise renamed Control back to ScreenConnect. The module keeps the name ConnectWiseControlAPI and the CWC prefix on its commands.