### ImmyBot Chrome Deployment Flowchart

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/GettingStarted/quick-start-guide.md

Illustrates a specific deployment example for Google Chrome, detailing the desired state (installed) and the target group (all computers).

```mermaid
graph LR
subgraph "Chrome Deployment"
    Input1["Google Chrome"] --> |"Should Be"| DesiredState1["Installed"] --> |on| Group1["All Computers"]
end
```

--------------------------------

### Download ImmyAgent PPKG/ISO

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/GettingStarted/quick-start-guide.md

This section details how to download the ImmyBot provisioning package (PPKG) to a USB drive for physical machines or an ISO for virtual machines. This package is essential for the initial setup and onboarding of a new computer.

```ImmyBot CLI
Download PPKG to Flash Drive
Downlaod ISO to Flash Drive
```

--------------------------------

### Simplify Getting Started Wizard

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2021.md

The 'Getting Started Wizard' has been simplified for a more user-friendly experience. Unnecessary padding has also been removed.

```PowerShell
Simplified the "Getting Started Wizard"
Removed unnecessary padding in the "Getting Started Wizard"
```

--------------------------------

### Install VitePress and Yarn

Source: https://github.com/immense/immybot-documentation/blob/main/README.md

Commands to install VitePress as a development dependency and Yarn globally. These are prerequisites for running the ImmyBot documentation locally.

```bash
npm install -D vitepress
npm install --global yarn
```

--------------------------------

### Start ImmyBot Documentation Locally

Source: https://github.com/immense/immybot-documentation/blob/main/README.md

Command to start the local development server for the ImmyBot documentation. This command should be run from the root directory of the cloned repository.

```bash
yarn docs:dev
```

--------------------------------

### PowerShell Script for Software Installation

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/HowToGuides/managing-software.md

Provides an example of writing a PowerShell script for software installation within ImmyBot. It emphasizes using silent install parameters and ImmyBot helper functions.

```PowerShell
# Example PowerShell script for software installation
# Ensure to use silent install parameters provided by the vendor.
# Utilize ImmyBot helper functions as needed.
# Example: Install-Application -Name "ExampleApp" -Silent

# Placeholder for actual installation logic
Write-Host "Installing software..."
```

--------------------------------

### Getting Started Wizard Improvements

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2022.md

Implements minor improvements to the getting started wizard to enhance the initial user experience.

```text
Made minor improvements to the getting started wizard
```

--------------------------------

### Install Provisioning Package via PowerShell

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/HowToGuides/onboarding.md

This snippet demonstrates how to install an ImmyBot provisioning package (PPKG) on a virtual machine using PowerShell. It requires specifying the path to the PPKG file.

```PowerShell
Install-ProvisioningPackage -PackagePath {Path to PPKG}
```

--------------------------------

### ImmyBot Deployment Flowchart

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/GettingStarted/quick-start-guide.md

Visualizes the core building blocks of ImmyBot deployments, showing how software or tasks define a desired state for one or more computers.

```mermaid
graph LR
subgraph "Deployment"
    Input["Software or Task"] --> |"Should Be"| DesiredState["Desired State"] --> |on| Group["One or More Computers"]
end
```

--------------------------------

### Physical Computer Onboarding with USB

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/HowToGuides/old-onboarding.md

Instructions for onboarding a physical computer using the ImmyBot USB drive. This process involves booting the computer, inserting the USB at the Windows setup screen, and allowing the automatic detection and application of the provisioning package.

```Physical Computer Setup
1. Unbox the new computer and power it on
2. When you reach the Windows setup screen (region selection), insert your ImmyBot USB drive
3. The computer will automatically detect the ImmyBot provisioning package (PPKG)
4. Follow any on-screen prompts to apply the package
```

--------------------------------

### Install ImmyBot Agent via PowerShell

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/HowToGuides/agent-installation.md

This method is suitable for already set up computers where PowerShell can be executed remotely. It allows for enabling Automatic Onboarding and mass deployment.

```powershell
# Example PowerShell command to install ImmyBot agent
# Replace with actual deployment script or command
# Invoke-WebRequest -Uri 'YOUR_IMMYBOT_INSTALL_URL' -OutFile 'immybot_installer.exe'
# Start-Process -FilePath 'immybot_installer.exe' -ArgumentList '/install' -Wait
```

--------------------------------

### Virtual Machine Onboarding with ISO

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/HowToGuides/old-onboarding.md

Steps for onboarding a virtual machine using the ImmyBot ISO. This includes mounting the ISO, triggering the provisioning package application via keyboard shortcut or direct file execution.

```Virtual Machine Setup
1. Mount the ISO from Step 1 to your virtual machine
2. At the Windows region selection screen, press the Windows key 5 times
3. Alternatively, double-click the PPKG file from the mounted disk
```

--------------------------------

### Install Adobe Reader

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/GettingStarted/recommended-deployments.md

This deployment installs and configures the latest version of Adobe Reader. It can be managed alongside alternative PDF readers by creating exception deployments to uninstall Adobe Reader and install the preferred alternative for specific targets.

```PowerShell
# Example PowerShell snippet for installing Adobe Reader (conceptual)
# This is a placeholder and would involve specific ImmyBot cmdlets or logic.
Install-ImmyApplication -ApplicationName "Adobe Reader"
# To handle exceptions, you might have a separate deployment that uninstalls Adobe Reader:
# Uninstall-ImmyApplication -ApplicationName "Adobe Reader"
```

--------------------------------

### Software Detection Script Example (PowerShell)

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/AdvancedTopics/scripts.md

This PowerShell script demonstrates how to detect the version of installed software by checking an executable file. It retrieves the version string from the specified executable and returns it. This is useful when software does not create a standard Add/Remove Programs entry.

```powershell
Get-Command "C:\Program Files*\<softwarename>\mysoftware.exe" -ErrorAction SilentlyContinue | %{ $_.Version.ToString() }
```

--------------------------------

### Software Install Maintenance Action Flow

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/CoreFeatures/maintenance-sessions.md

Illustrates the typical workflow for a software installation maintenance action, including checking if the software is already installed, handling configuration tasks, running test scripts, and determining the final compliance status.

```mermaid
flowchart TD
 A[Software Install] --> Detect{Software Installed?}
 Detect --> |No| Install
 Detect --> |Yes| HasConfigurationTask{Has Configuration Task?}
 Install --> PostInstallDetect{Software Installed?}
 PostInstallDetect --> |Yes|HasConfigurationTask
 HasConfigurationTask --> |Yes| MaintenanceTaskTest{Run Test Script}
 MaintenanceTaskTest --> |return $true| Compliant
 MaintenanceTaskTest --> |return $false| RunSetScript(Run Set Script)
 RunSetScript --> PostMaintenanceTaskTest{Run Test Script}
 PostMaintenanceTaskTest --> |return $true| Compliant
 PostMaintenanceTaskTest --> |return $false| Non-Compliant
 PostInstallDetect --> |No| Non-Compliant
```

--------------------------------

### Normal ImmyBot Agent Log Example

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Troubleshooting/troubleshooting.md

Example log output from a normally functioning ImmyBot Agent, showing successful process execution and connection.

```log
2022-06-14 00:02:25.560 -05:00 [DBG] Hosting starting
2022-06-14 00:02:25.799 -05:00 [INF] Starting Immybot Agent
2022-06-14 00:02:25.943 -05:00 [INF] Using configuration file stored at: C:\ProgramData\ImmyBotAgentService\config.json
2022-06-14 00:02:26.875 -05:00 [DBG] Initializing IoT Hub connection
2022-06-14 00:02:35.023 -05:00 [INF] Application started. Hosting environment: Production; Content root path: C:\WINDOWS\TEMP\.net\Immybot.Agent.Service\lreaszzz.wwx\
2022-06-14 00:02:35.024 -05:00 [DBG] Hosting started
2022-06-14 00:02:40.552 -05:00 [WRN] IoT Hub connection status Changed Status => [Connected] Reason => [Connection_Ok]
2022-06-14 02:06:32.159 -05:00 [DBG] Process started; ID: 12724
2022-06-14 02:06:37.358 -05:00 [DBG] Running C:\ProgramData\ImmyBot\Scripts\840290f2bd2142e2bd2c612542436763\Immybot.Agent.Ephemeral.exe --ImmyScriptPath C:\ProgramData\ImmyBot\Scripts\840290f2bd2142e2bd2c612542436763 --BackendAddress wss://immense.immy.bot/ --SessionID c946e1d1-f5fd-d36d-0489-d2a9ad9084e0
2022-06-14 02:06:38.335 -05:00 [DBG] PID 16184 <----- Indicates successful execution
2022-06-14 02:06:38.372 -05:00 [DBG] Process exited; Code: 0
```

--------------------------------

### Install Manufacturer Updates (Dell/Lenovo/HP)

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/GettingStarted/recommended-deployments.md

This deployment installs the latest driver, BIOS/firmware updates, and hardware-specific utilities from major manufacturers like Dell, Lenovo, and HP. It uses manufacturer-specific targeting scripts to ensure updates are only applied to the correct hardware.

```PowerShell
# Example PowerShell snippet for detecting manufacturer and applying updates (conceptual)
# This is a placeholder and would involve specific ImmyBot cmdlets or logic.
$manufacturer = Get-ImmyComputerManufacturer
if ($manufacturer -eq "Dell") {
    Install-ImmyManufacturerUpdates -Manufacturer "Dell"
} elseif ($manufacturer -eq "HP") {
    Install-ImmyManufacturerUpdates -Manufacturer "HP"
} # ... and so on for other manufacturers
```

--------------------------------

### Install Licensed Microsoft 365 Apps

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/GettingStarted/recommended-deployments.md

ImmyBot intelligently installs Microsoft 365 applications based on user license entitlements. It uses a Metascript filter that connects to the Microsoft Graph API to check user licenses before installing specific products like Microsoft 365 Apps for Business/Enterprise, Project, or Visio.

```PowerShell
# Example PowerShell snippet for checking license and installing M365 Apps (conceptual)
# This is a placeholder and would involve specific ImmyBot cmdlets or logic.
$userHasLicense = Test-ImmyM365License -UserIdentifier $userId -Product "Microsoft 365 Apps for enterprise"
if ($userHasLicense) {
    Install-ImmyApplication -ApplicationName "Microsoft 365 Apps for enterprise" -UserIdentifier $userId
}
```

--------------------------------

### Install ImmyBot Agent via PowerShell

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/HowToGuides/old-agent-installation.md

This method is ideal for already set up computers where you can remotely execute PowerShell commands. It allows for enabling automatic onboarding, setting the primary user, and deploying the Immy Agent using RMM scripting.

```PowerShell
# Example PowerShell command to deploy Immy Agent
# Replace with actual deployment script or command
Invoke-WebRequest -Uri "https://example.com/immyagent.ps1" -OutFile "C:\Temp\immyagent.ps1"
Start-Process powershell.exe -ArgumentList "-File C:\Temp\immyagent.ps1" -Verb RunAs
```

--------------------------------

### Create Software Deployment in ImmyBot

Source: https://github.com/immense/immybot-documentation/blob/main/creating-deployments.md

This guide outlines the steps to create a software deployment in ImmyBot, including selecting software, version, deployment mode (Enforced, Available, Removed), installation context, and defining target computers, groups, or users.

```ImmyBot
1. Navigate to Deployments > Create Deployment
2. Select Type: Software
3. Select Software and Version (e.g., "Latest")
4. Configure Options: Deployment Mode (Enforced, Available, Removed), Installation Context (System, User)
5. Define Targets: Computers, Computer Groups, Users, User Groups, or Filter Script
6. Save Deployment
```

--------------------------------

### Install Software on Selected Computers

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Integrations/build-your-own-integration.md

This script demonstrates a full workflow for installing software using ImmyBot. It first retrieves a list of available software, allows the user to select one, then retrieves a list of computers, allows the user to select one or more, and finally triggers a maintenance session to install the selected software. It uses `Out-GridView` for user selection and `Invoke-ImmyBotRestMethod` for API interactions.

```PowerShell
# Step 1: Get available software
Write-Host "Retrieving available software..." -ForegroundColor Cyan
$Software = Invoke-ImmyBotRestMethod -Endpoint "/api/v1/software/global"
$SelectedSoftware = $Software | Select-Object Id, Name | Out-GridView -OutputMode Single -Title "Select Software to Install"

if (-not $SelectedSoftware) {
    Write-Error "No software selected. Exiting."
    return
}

Write-Host "Selected software: $($SelectedSoftware.Name)" -ForegroundColor Green

# Step 2: Get target computers
Write-Host "Retrieving computers..." -ForegroundColor Cyan

# Optional: Filter computers by primary user email
$email = ''
if ($email) {
    $SelectedComputers = Invoke-ImmyBotRestMethod -Endpoint "/api/v1/computers/dx?filter=['primaryUserEmail','=','$Email']" | ForEach-Object { $_.data }
}
else {
    $Computers = Invoke-ImmyBotRestMethod -Endpoint "/api/v1/computers"
    $SelectedComputers = $Computers | Out-GridView -OutputMode Multiple -Title "Select Computer(s) to Install $($SelectedSoftware.Name)"
}

if (-not $SelectedComputers -or $SelectedComputers.Count -eq 0) {
    Write-Error "No computers selected. Exiting."
    return
}

Write-Host "Selected $($SelectedComputers.Count) computer(s)" -ForegroundColor Green

# Step 3: Trigger maintenance session to install software
Write-Host "Triggering maintenance session..." -ForegroundColor Cyan

$MaintenanceParams = @{
    fullMaintenance = $false  # When true, applies all deployments to the machine
    maintenanceParams = @{
        maintenanceIdentifier = "$($SelectedSoftware.Id)"
        maintenanceType = 0    # 0 = Software
        repair = $false
        desiredSoftwareState = 5  # 5 = NewerOrEqualVersion
    }
    skipBackgroundJob = $true  # Bypasses concurrent session limit
    rebootPreference = 1       # 1 = Suppress
    offlineBehavior = 2        # 2 = ApplyOnConnect
    computers = @($SelectedComputers | ForEach-Object { @{ computerId = $_.id } })
}

# Trigger the maintenance session
$Result = Invoke-ImmyBotRestMethod -Endpoint "/api/v1/run-immy-service" -Method "POST" -Body $MaintenanceParams

Write-Host "Maintenance session created successfully!" -ForegroundColor Green
Write-Host "Session ID: $($Result.id)" -ForegroundColor Cyan

# Optional: Detailed parameter explanation
<#
Maintenance Parameters Reference:
--------------------------------
fullMaintenance: When true, applies all deployments to the machine
resolutionOnly: Determines if software should be installed based on deployments (computer can be offline)
detectionOnly: Detects current software version (computer must be online)
inventoryOnly: Session ends after inventory scripts run
useWinningDeployment: When true, ignores desiredSoftwareState in maintenanceParams
deploymentId: Specify a deployment (when useWinningDeployment is false)
deploymentType: 0 = Global Database, 1 = Local

Desired Software States:
----------------------
0 = NoAction
1 = NotPresent (uninstall)
2 = ThisVersion (specific version)
3 = OlderOrEqualVersion
4 = LatestVersion (from database)
5 = NewerOrEqualVersion (default)
6 = AnyVersion

Reboot Preferences:
-----------------
-1 = Force
0 = Normal
1 = Suppress
#>
```

--------------------------------

### ImmyBot Software Version Components

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/terminology.md

This Mermaid diagram outlines the key components and actions related to a Software Version within ImmyBot, such as installation, uninstallation, upgrades, and testing.

```mermaid
graph TD
    C[Software Version] --> Install
    C --> Uninstall
    C --> Upgrade
    C --> Test
```

--------------------------------

### Windows Defender ImmyBot Agent Log Example

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Troubleshooting/troubleshooting.md

Example log output from an ImmyBot Agent when Windows Defender interferes, showing a 'Dirty-Shutdown' and WMI errors.

```log
2022-11-17 13:13:36.604 +11:00 [DBG] Hosting starting
2022-11-17 13:13:36.817 +11:00 [INF] Starting Immybot Agent
2022-11-17 13:13:36.840 +11:00 [INF] Using configuration file stored at: C:\ProgramData\ImmyBotAgentService\config.json
2022-11-17 13:13:37.590 +11:00 [DBG] Initializing IoT Hub connection
2022-11-17 13:13:37.860 +11:00 [DBG] Hosting started
2022-11-17 13:13:38.598 +11:00 [WRN] IoT Hub connection status Changed Status => [Connected] Reason => [Connection_Ok]
2022-11-17 13:13:39.157 +11:00 [WRN] Dirty-Shutdown detected! Dirty-File created at: "2022-11-07T04:11:59.3975026Z" UTC
2022-11-17 13:13:41.686 +11:00 [DBG] Process started; ID: 5660
2022-11-17 13:13:44.674 +11:00 [DBG] Running C:\ProgramData\ImmyBot\Scripts\4303da9b790b41c6978b50b872fe17cb\Immybot.Agent.Ephemeral.exe --ImmyScriptPath C:\ProgramData\ImmyBot\Scripts\4303da9b790b41c6978b50b872fe17cb --BackendAddress wss://ericom.immy.bot/ --SessionID a92c0ed1-ea3b-7f8a-d9c6-946d9b44ccc5
2022-11-17 13:13:49.577 +11:00 [DBG] WMI Error 2
```

--------------------------------

### ImmyBot Script Flow

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/AdvancedTopics/scripts.md

Visualizes the execution order of different script types in ImmyBot, including detection, dynamic versions, download, installation, and post-installation scripts.

```mermaid
flowchart TD
    A[Detection Script] --> |"Test Script (Optional)"| B(Dynamic Versions Script)
    B --> C{Default Download Script}
    B --> D{"Custom Download Script (Optional)"}
    C --> E(Install Script)
    D --> E
    E --> F("Post-Installation Script (Optional)")
```

--------------------------------

### ImmyBot API Request with PowerShell

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Integrations/custom-integrations.md

Demonstrates how to make a GET request to the ImmyBot API to retrieve computer information. It requires an API key for authentication and specifies the base URL and headers.

```PowerShell
$apiKey = "YOUR_API_KEY"
$baseUrl = "https://yourdomain.immy.bot/api/v1"

$headers = @{
    "Authorization" = "Bearer $apiKey"
}

$response = Invoke-RestMethod -Uri "$baseUrl/computers" -Headers $headers -Method Get
```

--------------------------------

### ImmyBot Scripting - Error Handling Example

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/AdvancedTopics/scripts.md

Demonstrates how to implement proper error handling in ImmyBot scripts using the 'throw' keyword to provide user-friendly error messages and prevent cascading failures.

```powershell
throw "The bad thing that happened, what user should do"
```

--------------------------------

### Detect-Software Command Example

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/HowToGuides/managing-software.md

Demonstrates how to use the Detect-Software command from the Metascript context in the ImmyBot terminal to check software detection details.

```PowerShell
Detect-Software
```

--------------------------------

### Software Detection Script Version Return Example (PowerShell)

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/AdvancedTopics/scripts.md

This PowerShell script shows the correct way to return a version string for software detection in ImmyBot. The script explicitly casts the version to a string, as returning a System.Version object directly is not supported.

```powershell
$version = [String]"1.2.3"
return $version
```

--------------------------------

### Start Endpoint Trace Log (WPR)

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Troubleshooting/troubleshooting.md

Starts the collection of detailed endpoint activity logs using Windows Performance Recorder (WPR). This includes CPU, Minifilter, FileIO, and Registry tracing to help diagnose environmental issues affecting the ImmyBot Agent.

```Batch
wpr.exe -start CPU -start Minifilter -start FileIO -start Registry
```

--------------------------------

### ImmyBot Software Selection in Prerequisites

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2024.md

Any software can now be selected for installation or uninstallation within the 'Installation Prerequisites' feature, offering greater flexibility in defining software dependencies.

--------------------------------

### Custom RMM Integration - Get RMM Customers with PowerShell

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Integrations/custom-integrations.md

Illustrates the initial steps for a custom RMM integration using PowerShell. It shows how to set up API keys and URLs for both ImmyBot and the RMM provider, and then retrieve customer data from the RMM.

```PowerShell
# Configuration
$immyApiKey = "YOUR_IMMY_API_KEY"
$immyBaseUrl = "https://yourdomain.immy.bot/api/v1"
$rmmApiKey = "YOUR_RMM_API_KEY"
$rmmBaseUrl = "https://your-rmm-provider.com/api"

# Set up headers
$immyHeaders = @{
    "Authorization" = "Bearer $immyApiKey"
    "Content-Type" = "application/json"
}
$rmmHeaders = @{
    "Authorization" = "Bearer $rmmApiKey"
    "Content-Type" = "application/json"
}

# Get customers from RMM
$rmmCustomers = Invoke-RestMethod -Uri "$rmmBaseUrl/customers" -Headers $rmmHeaders -Method Get
```

--------------------------------

### ImmyBot Task Execution Methods

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/terminology.md

This Mermaid diagram illustrates the different ways a Task can be executed in ImmyBot, either through specific 'get', 'set', or 'test' methods, or a combined script that accepts a '$method' parameter.

```mermaid
graph TD
    C[Task]
    C --> Get
    C --> Set
    C --> Test

or

graph TD
    C[Task]
    C --> S[Combined Script with $method parameter containing 'get','set', or 'test']
```

--------------------------------

### ImmyBot Ephemeral Agent Troubleshooting Flowchart

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Troubleshooting/troubleshooting.md

A flowchart detailing the steps to diagnose why the ImmyBot Ephemeral Agent might not be starting or connecting, including log checks and potential solutions.

```mermaid
graph TD
    CheckImmyAgentLogs[Check ImmyAgent Logs in C:\ProgramData\ImmyBot\Logs] --> DidEphemeralAgentStart[Immybot.Agent.Ephemeral.exe start?]
    DidEphemeralAgentStart --> |Yes|CheckEphemeralAgentLogs[Check Ephemeral Agent logs in C:\ProgramData\ImmyBot\Scripts\*\*.log]
    DidEphemeralAgentStart --> |No|BlockedBySecuritySoftware[Exclude Script Path from Security Software]
    CheckEphemeralAgentLogs --> EphemeralAgentConnect[Did Ephemeral Agent Websocket Connect?]
    EphemeralAgentConnect -->|Yes|DidSuccessfullyIdentifyAfterFix
    EphemeralAgentConnect --> |No|TryNoSSLInspect[Put on network without SSL Inspection]
    TryNoSSLInspect --> DidSuccessfullyIdentifyAfterFix[Ephemeral Agent Connect After Fix?]
    DidSuccessfullyIdentifyAfterFix[Machine Identify Successfully?] --> |No|EmailSupport
    DidSuccessfullyIdentifyAfterFix[Machine Identify Successfully?] --> |Yes|Done
    EmailSupport["Email logs from C:\ProgramData\ImmyBot\Logs and C:\ProgramData\ImmyBot\Scripts\*\*.logs to support@immy.bot"]
```

--------------------------------

### Authenticate and Install Software with ImmyBot API (PowerShell)

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Integrations/build-your-own-integration.md

This PowerShell script demonstrates how to authenticate with the ImmyBot API using OAuth 2.0 client credentials flow, retrieve available software, select target computers, and initiate a software installation via a maintenance session. It requires configuration variables for Azure domain, client ID, client secret, and ImmyBot instance subdomain.

```PowerShell
# Configuration Variables\n$AzureDomain = ''          # Your domain, e.g., contoso.com\n$ClientID = ''             # Application (Client) ID from App Registration\n$Secret = ''               # Client Secret value from App Registration\n$InstanceSubdomain = ''    # Your ImmyBot instance subdomain name (without .immy.bot)\n\n# Authentication Setup\n$TokenEndpointUri = [uri](Invoke-RestMethod "https://login.windows.net/$AzureDomain/.well-known/openid-configuration").token_endpoint\n$TenantID = ($TokenEndpointUri.Segments | Select-Object -Skip 1 -First 1).Replace("/\", "")\n$Script:BaseURL = "https://$($InstanceSubdomain).immy.bot"\n\nFunction Get-ImmyBotApiAuthToken {\n    [CmdletBinding()]\n    Param (\n        [Parameter(Mandatory)]\n        [string]$TenantId,\n        [Parameter(Mandatory)]\n        [string]$ApplicationId,\n        [Parameter(Mandatory)]\n        [string]$Secret,\n        [Parameter(Mandatory)]\n        [string]$ApiEndpointUri\n    )\n\n    $RequestAccessTokenUri = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"\n    $body = "grant_type=client_credentials&client_id=$applicationId&client_secret=$Secret&scope=$($ApiEndpointUri)/.default"\n    $contentType = 'application/x-www-form-urlencoded'\n\n    try {\n        $Token = Invoke-RestMethod -Method Post -Uri $RequestAccessTokenUri -Body $body -ContentType $contentType\n        return $Token\n    }\n    catch {\n        Write-Error "Failed to obtain authentication token: $_"\n        throw\n    }\n}\n\n# Get authentication token\n$Token = Get-ImmyBotApiAuthToken -ApplicationId $ClientId -TenantId $TenantID -Secret $Secret -ApiEndpointUri $BaseURL\n$Script:ImmyBotApiAuthHeader = @{\n    "authorization" = "Bearer $($Token.access_token)"\n}\n
```

--------------------------------

### ThreatLocker Configuration for ImmyBot

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Troubleshooting/troubleshooting.md

Step-by-step guide for configuring ThreatLocker to allow ImmyBot. This involves adding ImmyBot's code-signing certificates and the instance's script path to ThreatLocker's application control policies.

```text
1. Application Control-> Applications
2. Create New Application
3. Put the following value into Certificate and click Add

New Certificate on Feb. 11th, 2025:
CN=ImmyBot LLC, O=ImmyBot LLC, L=Baton Rouge, S=Louisiana, C=US

Existing Certificate:
CN=Immense Networks, O=Immense Networks, L=Baton Rouge, S=Louisiana, C=US

1. Add your instance’s [script path](#script-path-exclusion)
1. Create a New Application Policy
```

--------------------------------

### Update ImmyBot Dynamic Version Script Example

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2022.md

Provides an updated example script for managing dynamic versions within ImmyBot. This script is likely used for version control and deployment strategies.

```PowerShell
New-DynamicVersion
```

--------------------------------

### Maintenance Session Workflow

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/CoreFeatures/maintenance-sessions.md

Visualizes the sequence of steps in an ImmyBot maintenance session, from starting the process to reporting the results. It outlines the identification of deployments, state checking, plan creation, action execution, and final reporting.

```mermaid
graph LR
    A[Start Maintenance] --> B[Identify Deployments]
    B --> C[Check Current State]
    C --> D[Create Plan]
    D --> E[Execute Actions]
    E --> F[Check Current State]
    F --> G[Report Results]
```

--------------------------------

### Add Installer Download URL to Session Log

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2023.md

The installer download URL is now included in the session log when attempting a BITS or basic download.

```PowerShell
Added the installer download url to the session log when attempting a BITS or basic download
```

--------------------------------

### Package Analyzer Fallback for EXE Installers

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2023.md

The Package Analyzer will now use `FileVersion` as a fallback when `ProductVersion` is missing for EXE installers. This improves the analysis of installers where version information might be incomplete.

```PowerShell
FileVersion
```

--------------------------------

### ImmyBot Agent Execution Flow

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Troubleshooting/troubleshooting.md

Visualizes the process of how the ImmyBot Agent initiates the Ephemeral Agent through various RMMs and the subsequent PowerShell execution chain.

```mermaid
graph LR
    ImmyBot --> |Parallel|Automate[Run script to download and run Ephemeral Agent via Automate]
    ImmyBot --> |Parallel|Control[Run script to download and run Ephemeral Agent via Control]
    ImmyBot --> |Parallel|ImmyAgent[Run script to download and run Ephemeral Agent via ImmyAgent]
    ImmyBot --> |Parallel|N-Central[Run script to download and run Ephemeral Agent via N-Central]
    Automate --> Immybot.Agent.Ephemeral.exe
    Control --> Immybot.Agent.Ephemeral.exe
    ImmyAgent --> Immybot.Agent.Ephemeral.exe
    N-Central --> Immybot.Agent.Ephemeral.exe
    Immybot.Agent.Ephemeral.exe --> cmd.exe --> powershell.exe --> Invoke-PSPipeHost.ps1
```

--------------------------------

### Software Auto Update Script Example (PowerShell)

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/AdvancedTopics/scripts.md

This PowerShell script is used for automatically adding new software versions. It should return a `$SoftwareVersion` object containing the URL for the latest package and its display version. This functionality is now deprecated in favor of dynamic versions.

```powershell
$SoftwareVersion = @{}
$SoftwareVersion.url = $LatestPackage.OriginFile.OriginUri
$SoftwareVersion.displayVersion = $VersionFromMsi
return $SoftwareVersion
```

--------------------------------

### ImmyBot Deployment Diagram

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/terminology.md

This Mermaid diagram illustrates the relationship between a Deployment, Software/Task, and Target, showing how Deployments assign maintenance items to computers, users, or tenants.

```mermaid
graph TD
    A[Deployment] --> B[Software or Task]
    A --> C[Target]
    C --> D[Computers]
    C --> E[Users]
    C --> F[Tenants]
```

--------------------------------

### ImmyBot Audit Log for Application Startup

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2024.md

An audit log has been implemented to record when the ImmyBot application starts up, providing better traceability.

--------------------------------

### GDAP Role Assignment Example for ImmyBot

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Integrations/azure-graph-permissions-setup.md

This example outlines the steps to configure GDAP role assignments for ImmyBot, involving the creation of security groups and the assignment of specific Entra roles to these groups within a partner tenant. It also details adding partner users to these groups for Partner Center API access.

```text
1. Create security group in the partner tenant named `Application Administrators`
2. Create security group in the partner tenant named `Privileged Role Administrators`
3. Assign the `Application administrator` Entra role to the `Application Administrators` security group on the customer's admin relationship
4. Assign the `Privileged role administrator` Entra role to the `Privileged Role Administrators` security group on the customer's admin relationship
5. Add the partner user that you wish to sign-in to the Partner Center API with to `AdminAgents`, `Application Administrators` and `Privileged Role Administrators` security groups
```

--------------------------------

### Download ImmyAgent for Onboarding

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/HowToGuides/old-onboarding.md

Steps to download the ImmyAgent provisioning package (PPKG) or ISO for computer onboarding. This involves navigating the ImmyBot dashboard, selecting the onboarding tenant, and choosing the appropriate download option.

```ImmyBot Dashboard
1. Insert a USB drive into your computer
2. From the ImmyBot dashboard, click on **Download ImmyAgent** in the left navigation
3. Select the **Onboarding** tenant
4. Choose **New Computer Flash Drive**
5. Check **Enable Automatic Onboarding**
6. Check and set **Set Primary User**
7. Click **Download PPKG to Flash Drive**
   1. Note: If you're testing with a virtual machine, please select **Downlaod ISO to Flash Drive** and proceed to Step 2.
8. Place file on the root of your flashdrive
```

--------------------------------

### Apply Provisioning Package (PPKG) for Windows Reset

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/FAQ.md

This snippet outlines the process of creating a provisioning package (PPKG) with the Windows Reset option selected and deploying it to a specified machine using ImmyBot. It involves downloading the ImmyAgent to create the PPKG and then creating a deployment for 'Apply Provisioning Package (PPKG)'.

```ImmyBot
Download ImmyAgent
Create a Deployment for "Apply Provisioning Package (PPKG)"
```

--------------------------------

### Get Rmm Install Script for ImmyBot Agent Update

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2021.md

This metascript retrieves the PowerShell install script for a specified RMM link, facilitating quick updates of the ImmyBot Agent. It's designed to streamline the agent update process, with future plans for automated updates.

```PowerShell
$RmmInfo = Get-RmmInfo -ProviderType ImmybotAgent
$ScriptBlock = Get-RmmInstallScript -RmmLinkId $RmmInfo.RmmLinkId
Invoke-ImmyCommand $ScriptBlock
```

--------------------------------

### Assign Customer and User in ImmyBot

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/HowToGuides/old-onboarding.md

Guidance on assigning a customer and primary user to a newly onboarded computer within the ImmyBot dashboard. This step is crucial for proper configuration and deployment.

```ImmyBot Dashboard
1. Go to **New Computers** in the ImmyBot dashboard
2. Locate your newly connected computer in the list
3. Click on the computer to begin the onboarding process
4. **Customer (Required)**: The organization that owns the computer
5. **Primary User (Recommended)**: The person who will primarily use this computer
6. Click **Save and onboard now**
```

--------------------------------

### Create Primary User Profile

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/GettingStarted/recommended-deployments.md

This deployment creates a user profile for the primary user, enabling ImmyBot to configure user-specific settings like default browser and PDF editors. It fetches the user's SID from Azure AD or Active Directory to create the profile without requiring the user's password and handles the UserChoice hash.

```PowerShell
# Example PowerShell snippet for fetching SID and creating profile (conceptual)
# This is a placeholder and would involve specific ImmyBot cmdlets or logic.
$userSid = Get-ImmyUserSid -UserIdentifier $userId
New-ImmyUserProfile -UserSid $userSid -UserIdentifier $userId
# Further configuration steps would follow...
```

--------------------------------

### Get Registry Value and Compare with PowerShell

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/AdvancedTopics/scripts.md

Fetches a Windows registry value and compares it using RegistryShould-Be. This function simplifies registry operations and improves code readability. It assumes the existence of a 'ServerAddress' parameter.

```PowerShell
Get-WindowsRegistryValue -Path "HKLM:\Software\MySoftware" -Name "ServerAddress" | RegistryShould-Be -Value $ServerAddress
```

--------------------------------

### Set Computer Name and Domain Join

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/GettingStarted/recommended-deployments.md

This deployment allows setting computer names according to a convention and joining computers to an Active Directory domain. It requires an ImmyBot agent on a Domain Controller to create an offline domain join blob file, enabling domain join without direct line of sight.

```PowerShell
# Example PowerShell snippet for setting computer name and domain join (conceptual)
# This is a placeholder and would involve specific ImmyBot cmdlets or logic.
$computerName = "NEWPC" + (Get-Random -Minimum 1000 -Maximum 9999)
$domainName = "yourdomain.local"
$credential = Get-ImmyDomainJoinCredential

Set-ImmyComputerName -Name $computerName
Join-ImmyDomain -Domain $domainName -Credential $credential
```

--------------------------------

### ImmyBot Webhook Receiver in C#

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Integrations/custom-integrations.md

Provides an example of an ASP.NET Core controller endpoint designed to receive and process webhook data from ImmyBot. It handles different event types like 'session.completed' and 'computer.added'.

```C#
// Example ASP.NET Core controller
[ApiController]
[Route("api/webhooks/immybot")]
public class ImmyBotWebhookController : ControllerBase
{
    [HttpPost]
    public IActionResult ReceiveWebhook([FromBody] WebhookPayload payload)
    {
        // Process the webhook data
        switch (payload.EventType)
        {
            case "session.completed":
                ProcessCompletedSession(payload.Data);
                break;
            case "computer.added":
                ProcessNewComputer(payload.Data);
                break;
            // Handle other event types
        }

        return Ok();
    }
}
```

--------------------------------

### ImmyBot Certificate Details for Security Exclusions

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Troubleshooting/troubleshooting.md

Provides the details of ImmyBot's current and upcoming code-signing certificates. These details are crucial for configuring exclusions in security software to ensure ImmyBot's agents and installers are not blocked.

```text
New Certificate on Feb. 11th, 2025:
CN=ImmyBot LLC, O=ImmyBot LLC, L=Baton Rouge, S=Louisiana, C=US

Existing Certificate:
CN=Immense Networks, O=Immense Networks, L=Baton Rouge, S=Louisiana, C=US
```

--------------------------------

### Sophos Central Configuration for ImmyBot

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Troubleshooting/troubleshooting.md

Instructions for configuring Sophos Central to allow ImmyBot, covering both tenant-specific manual additions and partner global templates. It details how to add certificates and utilize the event log method for allowing ImmyBot processes.

```text
Tenant Specific Manual Addition:
1. Launch Client Shell
2. Navigate to Global Settings - Allowed Applications
3. Select "Add apps"
4. In the "allow by:" dropdown, select certificate and add the following

New Certificate on Feb. 11th, 2025:
CN=ImmyBot LLC, O=ImmyBot LLC, L=Baton Rouge, S=Louisiana, C=US

Existing Certificate:
CN=Immense Networks, O=Immense Networks, L=Baton Rouge, S=Louisiana, C=US

Partner Global Templates:
1. Navigate to Settings & Policies - Global Templates and select the template you would like to modify
2. Once in the template, navigate to Global Settings - Allowed Applications
3. Follow steps 3 and 4 listed in the **Tenant Specific** section above
```

--------------------------------

### Dynamic Parameter for OAuth Consent

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/AdvancedTopics/scripts.md

This example shows how to define a dynamic parameter for OAuth consent using New-OAuthConsentParameter. It's used within a dynamicparam block to configure authentication endpoints, client IDs, scopes, and response types for interacting with third-party services.

```powershell
dynamicparam
    {
        New-ParameterCollection @(
            # The variable $RefreshToken now contains the OAuth response
            New-OAuthConsentParameter -Name RefreshToken -ResponseType code -AuthorizationEndpoint "<AUTH_ENDPOINT>" -TokenEndpoint "<TOKEN_ENDPOINT>" -ClientID '<CLIENT_ID>' -ClientSecret '<CLIENT_SECRET>'  -Scope "<SCOPE>" -Mandatory
        )
    }
```

--------------------------------

### Modify XML Configuration with XPath

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/AdvancedTopics/scripts.md

This example demonstrates how to modify a specific value within an XML file using XPath. It reads the configuration file, updates the value at the specified XPath, and then saves the changes back to the file. It assumes a parameter $ServerAddress is available.

```powershell
$ConfigFilePath = "C:\ProgramData\MySoftware\configuration.xml"
$XML = Get-Content $ConfigFilePath
$XML = $XML | XMLShould-Be -XPath "/ServerAddress" -Value $ServerAddress
$XML | Set-Content $ConfigFilePath
```

--------------------------------

### Package Analyzer Relative Path in ZIP Archives

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2023.md

The Package Analyzer now returns the relative path to an installer nested within multiple directories inside a ZIP archive. For example, if a package is structured as `(MyInstallerPackage.zip) => [MyInstallerPackage] -> [InnerFolder] -> Setup.exe`, the FileName will be `InnerFolder\Setup.exe` instead of just `Setup.exe`.

```PowerShell
InnerFolder\Setup.exe
```

--------------------------------

### Get Computer UUID for Identification

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/terminology.md

This PowerShell script retrieves the universally unique identifier (UUID) from a Windows machine's system information. This UUID is used by ImmyBot to uniquely identify computers, even after reinstallation or hardware changes, as it persists across system wipes.

```powershell
gwmi Win32_ComputerSystemProduct | select -expand UUID
```

--------------------------------

### Download ImmyBot RunScript Automation Policy

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Integrations/ncentral-integration-setup.md

This section provides a direct link to download the ImmyBot RunScript Automation Policy file (.amp) required for the N-Central integration. This policy enables ImmyBot to execute scripts on managed machines via N-Central.

```HTML
<a href="https://docs.immy.bot/ImmyBotRunScriptV2.amp" target="_self">download the ImmyBot RunScript Automation Policy</a>
```

--------------------------------

### Fix Memory Leak in Agent Installers

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2021.md

Addresses a memory leak issue that scaled with the number of ImmyBot agent installers. This fix improves the stability and performance of the agent installation process.

```PowerShell
Fixed an issue that was causing a memory leak that scaled with the number of ImmyBot agent installers
```

--------------------------------

### Syntax Highlighting with Line Highlighting (JavaScript)

Source: https://github.com/immense/immybot-documentation/blob/main/markdown-examples.md

Demonstrates syntax highlighting for JavaScript code using Shiki, with a specific line (line 4) highlighted. This feature enhances code readability in documentation.

```javascript
export default {
  data () {
    return {
      msg: 'Highlighted!'
    }
  }
}
```

--------------------------------

### ImmyBot Workflow Visualization (Mermaid)

Source: https://github.com/immense/immybot-documentation/blob/main/immybot-overview.md

Illustrates the operational workflow of ImmyBot, from discovering computers and defining standards to executing maintenance, verifying results, and reviewing reports.

```mermaid
graph LR
    A[Discover Computers] --> B[Define Standards]
    B --> C[Execute Maintenance]
    C --> D[Verify Results]
    D --> E[Review Reports]
    E --> B
```

--------------------------------

### Download ImmyBot Agent Installer

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2021.md

The interface for downloading ImmyBot agent installers has been updated to allow assigning default behavior to installation methods. The 'Deploy' tab now automatically updates with computer information.

```ImmyBot Feature
Updated the interface for downloading an immy agent installer. You can now assign default behavior to any of the installation methods. The `Deploy` tab will now automatically update when your computer shows up in ImmyBot.
```

--------------------------------

### Expose Agent Installer Version in Get-RmmInfo

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2021.md

This snippet shows how to access the current agent installer version via 'ExtraData.AgentInstallerVersion' in the Get-RmmInfo call for ImmyAgent RMM Links. This provides visibility into the agent's installation status.

```PowerShell
Get-RmmInfo -ImmyAgent -ExtraData.AgentInstallerVersion
```

--------------------------------

### Reduce ImmyAgent MSI Size

Source: https://github.com/immense/immybot-documentation/blob/main/Documentation/Reference/releases-2021.md

Significantly reduces the ImmyAgent install MSI size from 41MB to 14MB, improving download and installation times.

```N/A
Reduced agent install MSI from 41MB to 14MB
```