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

Fixing Name Mismatches Between Ninja and Halo

IfWhen athe script reports ⚠️ No Halo match for 'Client Name', it means the client exists in both systemsHalo but hasunder a different name,name. addThe correct fix is to update the client name in NinjaRMM to match exactly what Halo has — not the other way around.

Step 1 — Find the Client's Exact Name in Halo

    Log into Halo PSA at psa.dtctoday.com In the left navigation click Customers > Clients Use the search bar at the top to search for the client by a mappingkeyword to(e.g. part of their name) Click on the $nameMappingsmatching tableclient Note the exact name shown at the top of the script:client 
    $nameMappingsrecord =— @{this "Ninjais Orgwhat Name" = "Halo Clientuses Name"as }the
    official name

    Step 2 — Update the Name in NinjaRMM

      Log into NinjaRMM at app.ninjarmm.com Go to Administration > Organizations Search for the client Click into the org and click Edit Update the Organization Name field to match exactly what Halo shows Click Save

      Step 3 — Re-run the Sync

      Then updateRun the script inagain GitHubfrom PowerShell or wait for the next scheduled run. The client will now match and re-run.the GUID will sync successfully.

      Note: Always use Halo's naming as the source of truth. Halo is the primary PSA and its client names should be considered canonical.

      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