Skip to main content

NinjaRMM → Halo PSA GUID Sync — Setup & Operations

Overview

This page documents the setup and ongoing operation of the automated GUID sync between NinjaRMM and Halo PSA. The sync reads the DTC Org GUID custom field from each NinjaRMM organization and writes it to the DTC Client GUID custom field in Halo PSA for all active clients.

Reference Ticket: Halo Ticket #1141374

Why This Exists

Each client org in NinjaRMM has a unique GUID stored in a custom field called DTC Org GUID. This GUID needs to be available in Halo PSA under the DTC Information tab so it can be used for cross-platform automation and identification. This integration syncs it automatically on a weekly schedule.

Components

Halo PSA API Application

  • Name: NinjaRMM GUID Sync
  • Location: Configuration > Integrations > HaloPSA API
  • Auth Method: Client ID and Secret (Services)
  • Login Type: Agent — Integrator Agent (SSO accounts are incompatible with client credentials flow)
  • Permissions: All enabled
  • Client ID: 25542a6d-2d0e-4093-bf82-e11edc64faf6
  • Client Secret: Stored in 1Password

NinjaRMM API Application

  • Name: Halo GUID Sync
  • Location: Administration > Apps > API
  • Platform: API Services (machine-to-machine)
  • Scopes: Monitoring, Management
  • Grant Type: Client Credentials
  • Client ID: 0S1xEjce1FQp7Rbn_GJTrSWTp64
  • Client Secret: Stored in 1Password

PowerShell Script

Scheduled Task

  • Location: NinjaRMM > Administration > Scheduled Tasks
  • Name: Halo GUID Sync
  • Schedule: Weekly

How the Script Works

  1. Authenticates to both NinjaRMM and Halo PSA APIs using client credentials
  2. Pulls all organizations from NinjaRMM
  3. For each org, reads the dtcOrgGuid custom field
  4. Searches Halo PSA for a matching client using a three-tier matching strategy:
    • Exact name match — preferred
    • Fuzzy word overlap match — 60% word overlap threshold
    • Manual name mapping table — for clients where names differ significantly between systems
  5. Writes the GUID to Halo PSA using the CFDtcClientGuid field
  6. Outputs a summary of all updated, skipped, and failed clients

Adding Manual Name Mappings

If a client exists in both systems but has a different name, add a mapping to the $nameMappings table at the top of the script:

$nameMappings = @{
    "Ninja Org Name" = "Halo Client Name"
}

Then update the script in GitHub and re-run.

Adding a New Client

When a new client is onboarded:

  1. Make sure they are created in both NinjaRMM and Halo PSA
  2. Ensure the DTC Org GUID custom field is populated in NinjaRMM
  3. The weekly scheduled task will automatically sync the GUID to Halo on the next run
  4. If needed immediately, run the script manually from PowerShell

Credentials

All API credentials are stored in 1Password. Do not store plaintext credentials anywhere outside of 1Password or the NinjaRMM script variables.

Credential Location
Halo Client ID 1Password
Halo Client Secret 1Password
Ninja Client ID 1Password
Ninja Client Secret 1Password

Troubleshooting

Issue Resolution
invalid_client on Halo auth Regenerate client secret in Halo > Configuration > Integrations > HaloPSA API > NinjaRMM GUID Sync. Ensure Integrator Agent is set as the login agent — SSO accounts will not work
invalid_client on Ninja auth Verify client ID and secret in Ninja > Administration > Apps > API > Halo GUID Sync
Client showing ⚠️ No Halo match Client name differs between systems — add a manual mapping to the $nameMappings table in the script
GUID not showing in Halo after update Verify field name is CFDtcClientGuid — this is the internal name, not the display label
Scheduled task not running Check NinjaRMM > Administration > Scheduled Tasks and verify the target device is online
Back to top