ImmyBot

https://www.immy.bot/documentation
Admin
ImmyBot is a Remote Monitoring and Management (RMM) platform that automates IT management tasks...
Tokens:105,937
Snippets:1,084
Trust Score:8.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### HKCUShould-Be Example

Source: https://www.immy.bot/documentation/advanced-topics/scripts

Sets or tests a registry value under HKCU. The example sets EnableADAL to 1 for OneDrive policies.

```powershell
Get-WindowsRegistryValue -Path "HKCU:\Software\Policies\OneDrive" -Name EnableADAL | HKCUShould-Be 1

```

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

### Implement ISupportsListingAgents with mock agent data

Source: https://www.immy.bot/documentation/integrations/build-your-own-integration

PowerShell example showing how to implement the ISupportsListingAgents interface. It uses mock data for agents and creates agent objects with New-IntegrationAgent. The example includes a parameter for client IDs and demonstrates the expected structure for retrieving agents from an external system.

```powershell
$Integration | Add-DynamicIntegrationCapability -Interface ISupportsListingAgents -GetAgents {
    [CmdletBinding()]
    [OutputType([Immybot.Backend.Domain.Providers.IProviderAgentDetails[]])]
    param(
        [Parameter()]
        [string[]]$ClientIds = $null  # IDs of clients mapped in the UI
    )

    # Retrieve agents from your external system, remove this array initialization and implement real logic to pull your agent data.
    # This example uses mock data.
    $ClientIds = @(
        [PSCustomObject]@{ Name = 'Computer 1'; ID = 101 }
        [PSCustomObject]@{ Name = 'Computer 2'; ID = 102 }
        [PSCustomObject]@{ Name = 'Computer 3'; ID = 103 }
        [PSCustomObject]@{ Name = 'Computer 4'; ID = 104 }
        [PSCustomObject]@{ Name = 'Computer 5'; ID = 105 }
    )
    # End mock data

    foreach ($clientId in $ClientIds) {
        Write-Verbose "Retrieving agents for client: $($clientId.Name)"

        # Create an agent object for each agent
        New-IntegrationAgent -AgentId $clientId.ID -Name $clientId.Name -ClientId $clientId.ID
    }
}
```

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

### PowerShell script to select and install software on computers

Source: https://www.immy.bot/documentation/integrations/build-your-own-integration

This script retrieves available software from the ImmyBot API, lets the user select one via a grid view, then retrieves computers (optionally filtered by primary user email) and selects one or more via grid view. It then installs the selected software on the selected computers.

```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
```

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

### FileShould-Be - Config File Example

Source: https://www.immy.bot/documentation/advanced-topics/scripts

Verifies a file exists at the destination path, overwriting if hashes don't match. Assumes a parameter named ConfigFile.

```powershell
$ConfigFile | FileShould-Be -in "C:\ProgramData\MySoftware"

```

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

### Get-ImmyAzureAuthHeader example with Microsoft Graph

Source: https://www.immy.bot/documentation/advanced-topics/immy-commands

Gets an authentication header for Microsoft Graph and uses it to retrieve groups.

```powershell
# Get authentication header for Microsoft Graph API
$Header = Get-ImmyAzureAuthHeader -Endpoint "MSGraph" -ErrorAction Stop

# Use the header to make a Graph API request
$Groups = Invoke-RestMethod "https://graph.microsoft.com/v1.0/groups/" -Headers $Header
Write-Host "Found $($Groups.value.Count) groups in Azure AD"
```

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

### Mount ISO, run setup.exe, and dismount

Source: https://www.immy.bot/documentation/basic-instance-management/managing-software

Mounts a staged ISO, runs the setup.exe silently, and dismounts the ISO in a finally block. Requires $InstallerFile to be the full path to the staged .iso provided by ImbyBot.

```powershell
# $InstallerFile is the full path to the staged .iso, provided by ImbyBot
$mountResult = Mount-DiskImage -ImagePath $InstallerFile -PassThru
$driveLetter = ($mountResult | Get-Volume).DriveLetter

try {
    $setupPath = "${driveLetter}:\setup.exe"
    Start-Process -FilePath $setupPath -ArgumentList "/quiet" -Wait
}
finally {
    Dismount-DiskImage -ImagePath $InstallerFile
}
```

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

### Install Provisioning Package via PowerShell

Source: https://www.immy.bot/documentation/basic-instance-management/onboarding

Run this command at the Windows region selection screen (Shift+F10) to apply the provisioning package on a virtual machine. Replace {Path to PPKG} with the actual path to the PPKG file.

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

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

### PowerShell: Create Support Override Integration Script

Source: https://www.immy.bot/documentation/other-integrations/support-override-integration-setup

Example script that creates a dynamic integration with the ISupportsSupportTicketDetailOverride capability. It defines a -CreateTicket parameter that receives support request details and returns a SupportTicketCreationResult. Use this as a starting point for your own integration script.

```powershell
$Integration = New-DynamicIntegration -Init {
param(
)
[OpResult]::Ok()
} -HealthCheck {
New-HealthyResult
}
$Integration | Add-DynamicIntegrationCapability -Interface ISupportsSupportTicketDetailOverride -CreateTicket {
[CmdletBinding()]
[OutputType([SupportTicketCreationResult])]
param(
[Parameter(Mandatory)]
[string]$requesterEmail,
[Parameter(Mandatory)]
[string]$subject,
[Parameter(Mandatory)]
[string]$notes,
[string[]]$blobUrls,
[string]$sessionUrl,
[Parameter(Mandatory)]
[Immybot.Backend.Models.User]$user
)
try {
Write-Verbose "Creating support ticket with subject: $subject"
Write-Verbose "Requester email: $requesterEmail"
$ticketData = @{
email = $requesterEmail
subject = $subject
description = $notes
attachments = $attachmentUrls
userId = $user.Id
userName = "$($user.FirstName) $($user.LastName)"

```

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

### Error Response JSON Example

Source: https://www.immy.bot/documentation/reference/api-documentation

Example of the JSON body returned in an error response. Contains an 'error' object with 'code', 'message', and 'details' fields.

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'deployment_id' is invalid",
    "details": "Deployment with ID 'd999' not found"
  }
}
```

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

### Get-ImmyComputer: Get all computers and filter by inventory

Source: https://www.immy.bot/documentation/advanced-topics/immy-commands

Retrieves all computers in the current tenant and filters by inventory values. Use -InventoryKeys to filter by specific key-value pairs, e.g., OsName=Windows 10*.

```powershell
# Get all computers in the current tenant
$Computers = Get-ImmyComputer
Write-Host "Found $($Computers.Count) computers in the tenant"

# Get computers with specific inventory values
$WindowsComputers = Get-ImmyComputer -InventoryKeys @("OsName=Windows 10*")
```

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

### XMLShould-Be Example

Source: https://www.immy.bot/documentation/advanced-topics/scripts

Modifies an XML file by setting a value at a specified XPath. Assumes a parameter named ServerAddress. The example reads the file, applies the change, and writes it back.

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

```

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

### Initialize Dynamic Integration with SentinelOne Parameters

Source: https://www.immy.bot/documentation/integrations/build-your-own-integration

Creates a new dynamic integration with initialization parameters for SentinelOne URI and API key. The Init block generates the form on the New/Edit Integration page and stores connection context values.

```powershell
$Integration = New-DynamicIntegration -Init { # These parameters generate the form on the New/Edit Integration page param( [Parameter(Mandatory)] [Uri]$S1Uri, [Parameter(Mandatory)] # [DisplayName("API Key")] [Password(StripValue = $true)] $S1ApiKey ) $providerTypeFormData | Write-Variable # Note: The SentinelOne module is a Module script in Global Import-Module SentinelOne Get-Command -Module SentinelOne | Out-String | Write-Host $S1AuthHeader = Connect-S1API -S1Uri $S1Uri -S1APIToken $S1ApiKey # The SentinelOne module in Global will automatically use the following $IntegrationContext values if present $IntegrationContext.S1Uri = $S1Uri $IntegrationContext.S1ApiKey = $S1ApiKey $IntegrationContext.AuthHeader = $S1AuthHeader [OpResult]::Ok() } -HealthCheck { [CmdletBinding()] [OutputType([HealthCheckResult])] param( ) # todo: implement health check return New-HealthyResult }
```

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

### Get Signed In User's UPN with Invoke-ImmyCommand -Context User

Source: https://www.immy.bot/documentation/basic-instance-management/working-with-tasks

PowerShell metascript that runs a user context command with Invoke-ImmyCommand -Context User to get the signed-in user's UPN. It catches the NoLoggedOnUserException and OperationTimeout errors, clearing the error and continuing, while rethrowing other errors.

```powershell
try {
    Invoke-ImmyCommand -Context User {
        $userDomain = $env:USERDOMAIN
        $computerName = $env:COMPUTERNAME

        if ($userDomain -ne $computerName) {
            whoami /upn
        }
    } -ErrorAction Stop
} catch {
    if ($_.FullyQualifiedErrorId -eq "Immybot.Agent.MinimalShared.NoLoggedOnUserException" -or
        $_.FullyQualifiedErrorId -eq "OperationTimeout") {
        $_
        $Error[0] = $null
    } else {
        throw
    }
}

```

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

### SentinelOne Dynamic Integration Setup

Source: https://www.immy.bot/documentation/integrations/build-your-own-integration

Defines a new Dynamic Integration for SentinelOne with initialization and health check. The init block collects mandatory parameters (S1Uri, S1ApiKey) and stores them in IntegrationContext. The health check is a placeholder returning a healthy result.

```powershell
$Integration = New-DynamicIntegration -Init {
    # These parameters generate the form on the New/Edit Integration page
    param(
        [Parameter(Mandatory)]
        [Uri]$S1Uri,
        [Parameter(Mandatory)]
        # [DisplayName("API Key")]
        [Password(StripValue = $true)]
        $S1ApiKey
    )
    $providerTypeFormData | Write-Variable
    # Note: The SentinelOne module is a Module script in Global
    Import-Module SentinelOne
    Get-Command -Module SentinelOne | Out-String | Write-Host
    $S1AuthHeader = Connect-S1API -S1Uri $S1Uri -S1APIToken $S1ApiKey

    # The SentinelOne module in Global will automatically use the following $IntegrationContext values if present
    $IntegrationContext.S1Uri = $S1Uri
    $IntegrationContext.S1ApiKey = $S1ApiKey
    $IntegrationContext.AuthHeader = $S1AuthHeader

    [OpResult]::Ok()
} -HealthCheck {
    [CmdletBinding()]
    [OutputType([HealthCheckResult])]
    param(

    )
    # todo: implement health check
    return New-HealthyResult
}
```

```powershell
# ISupportsListingClients will create a Clients tab on the Integration for mapping ImmyBot tenants to the Clients returned by this script
$Integration | Add-DynamicIntegrationCapability -Interface ISupportsListingClients -GetClients {
    [CmdletBinding()]
    [OutputType([Immybot.Backend.Domain.Providers.IProviderClientDetails[]])]
    param()
    # return a list of clients for this integration using the New-IntegrationClient cmdlet
    Import-Module SentinelOne
    Get-S1Site -Verbose | ForEach-Object {
        New-IntegrationClient -ClientId $_.Id -ClientName $_.Name
    }
}
```

```powershell
# supports listing agents

$Integration | Add-DynamicIntegrationCapability -Interface ISupportsListingAgents -GetAgents {
    [CmdletBinding()]
    [OutputType([Immybot.Backend.Domain.Providers.IProviderAgentDetails[]])]
    param(
        [Parameter()]
        [string[]]$ClientIds = $null
    )
    # ClientIds will contain the clientids you mapped to ImmyBot tenants under the Integration->Clients tab
    # The agents you return here will go into the Computers->Pending Identification area until they are linked to Computers via the AgentId provided by ISupportsInventoryIdentification

    Import-Module SentinelOne
    foreach($ClientId in $ClientIds)
    {
        Get-S1Agent -SiteId $ClientId -Verbose | ForEach-Object {
            New-IntegrationAgent -AgentId $_.uuid -Name $_.computerName -SerialNumber $_.serialNumber -OSName $_.osName -Manufacturer $_.modelName -ClientId $_.siteId -IsOnline $true -AgentVersion $_.agentVersion -SupportsRunningScripts $false
    }
}
}
```

```powershell
# supports inventory identification

$Integration | Add-DynamicIntegrationCapability -Interface ISupportsInventoryIdentification -GetInventoryScript {
    [CmdletBinding()]
    param()
    # This ScriptBlock will be run in the Metascript context for every machine during initial identification and daily inventory
    Invoke-ImmyCommand {
        # Return the SentinelOne AgentId
        # We will match it to New-IntegrationAgent -AgentId you returned in ISupportsListingAgents
        $path = Resolve-Path  "C:\Program Files\SentinelOne\Sentinel Agent*\SentinelCtl.exe"
        if($path)
        {
            . $path.Path agent_id
        }
    }
}
```

```powershell
# supports retrieving a tenant install token

$Integration |  Add-DynamicIntegrationCapability -Interface ISupportsTenantInstallToken -GetTenantInstallToken {
    [CmdletBinding()]
    [OutputType([System.String])]
    param(
        [Parameter(Mandatory=$true)]
        [string]$clientId
    )
    Get-S1Site -Id $clientId | %{ $_.registrationToken}
}
```

```powershell
# supports retrieving a tenant uninstall token

$Integration | Add-DynamicIntegrationCapability -Interface ISupportsTenantUninstallToken -GetTenantUninstallToken {
    [CmdletBinding()]
    [OutputType([System.String])]
    param(
        [Parameter(Mandatory=$true)]
        [System.String]$clientId
    )
    return "implement me"
}
```

```powershell
$Integration | Add-DynamicIntegrationCapability -Interface ISupportsHttpRequest -HandleHttpRequest {
    [CmdletBinding()]
    [OutputType([Microsoft.AspNetCore.Mvc.IActionResult])]
    param(
        [Parameter(Mandatory=$True)]
        [Microsoft.AspNetCore.Http.HttpContext]$httpContext,
        [Parameter(Mandatory=$false)]
        $body,
        [Parameter(Mandatory=$True)]
        $route
    )
will response to  "plugins/api/v1/{providerLinkId}"
    # handle a http request sent to this integration
    # return an [ObjectResult] and set the status code
    $res = [ObjectResult]::new('ok')
    $res.StatusCode = 200;
    return $res;
}
return $Integration
```

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

### ShouldHave-One - Simplified Example

Source: https://www.immy.bot/documentation/advanced-topics/scripts

Reduces the manual count logic to a single pipeline using ShouldHave-One.

```powershell
$MatchingUsers = Get-ADUser -Filter * | ?{$_.SAMAccountName -like "Admin*" }
$MatchingUsers | ShouldHave-One

```

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

### Use the module in your integration

Source: https://www.immy.bot/documentation/integrations/build-your-own-integration

Shows how to use the module within an ImmyBot integration by adding a dynamic capability to list clients.

```powershell
$Integration | Add-DynamicIntegrationCapability -Interface ISupportsListingClients -GetClients {

```
Tokens:
Raw