Halo Service Desk

Halo Service Desk Guides

Documentation to assist with the setup and configuration of the Halo Service Desk platform

Guides > Ninja RMM Integration (API v2)

Ninja RMM Integration (API v2)

To enable the Ninja RMM integration in Halo, go to Configuration > Integrations and enable the module. Once the module has been enabled, click the menu icon for the module to begin configuring it.


NB: As of version 2.93.3, we have changed the way we authenticate with NinjaRMM. If you are an existing client with a connected NinjaRMM instance, please disconnect/reconnect to apply the new authentication method. If you are on 2.93.3+ and experiencing issues connecting to Ninja for the first time, please reach out to our support team.


Registering an OAuth Application


So that Halo can communicate with version 2 of the Ninja RMM API, an OAuth application must be registered in Ninja RMM. To do this, open Ninja RMM and navigate to Configuration > Integrations > API > Client App IDs and select "Add". On the creation screen choose the following values:


Field NameField Value
Application platform
Web (PHP, Java, .Net Core, etc.)
NameHalo PSA
Redirect URIhttps://auth.halopsa.com/externalauth
ScopesMonitoring, Management
Allowed Grant TypesRefresh Token
Authorization Code


Once configured, save the application and a client secret will be generated. Be sure to copy this value as you will not be able to retrieve it again. If you are unsure of any of the values that must be entered above, particularly what your redirect URI value is, then all values for your Halo instance are displayed in the Ninja RMM module:


Connecting to the Ninja RMM Application


Now that an OAuth application has been configured, open the Ninja RMM module in Halo. You are required to select the location of your hosted Ninja RMM environment, followed by inputting the client ID and secret of the application you just registered.



Once complete, click the Authorize Application button to connect to your application. You will be redirected to the Ninja RMM login screen, where you will be asked if you're happy for your app to access certain features within the API. After confirming, you will be redirected back to the Halo screen and new configuration options will be able. Should the connection fail for whatever reason, an error message will be displayed and you will remain disconnected from your application.


Organizations and Locations


Organizations and locations can be imported from Ninja RMM and created as clients and sites. To assist with linking organizations and locations in Ninja RMM to existing clients and sites in Halo, you can create mappings between the two. If you have mapped an organization/location to a client/site in Halo, the client and site in Halo will not have their names changed during an import. 


When importing, if no mapping is created for an organization/location, Halo will then try to match to an existing record using the name of the record. Once an import has been completed, a mapping will be added automatically to the table for you.


Once you are happy with your organization/location mappings, you can choose a top level to assign the incoming records too. Click the Import Organizations and Locations button to open the importer screen to complete the import.




Devices and Software


Devices and software can be imported from Ninja RMM into Halo. For the software to be visible against a device in Halo, the software licencing module must be enabled. To enable this, navigate to Configuration > Devices > Software Licencing.


There are four configuration options for the device import.


The first option allows you to choose a default site for devices. This is particularly important if you have not imported your entire client list from Ninja RMM. All devices must be associated with a site in Halo, therefore, if the imported device's Ninja RMM organization/location cannot be found because it hasn’t been imported, the Halo site will be set to the default value that you specify here.


Next you can specify a default group for any new asset types that are created. New asset types will be created automatically if a type does not already exist in Halo with the same name as the Ninja RMM device's type. You can choose which field is uses as the Ninja RMM device type using the third field ("Field for determining a Device's type"). The two options available here are the nodeClass field and the deviceType field. By expanding the drop down field, examples values are provided to give you an idea of how this may look when created:


Finally, you have the option to choose a device field that should be used to match new imported records to existing records. Again, the Ninja RMM ID of the device which gets assigned to the device on it’s first import is always checked first, so this field is only useful/required if you already have your device list in Halo, and you’re importing from Ninja RMM for the first time.


IMPORTANT: if you are using this field, the Asset field that you choose must exist as a field mapping. These are configured in the next section. 


It is possible to map Ninja RMM device fields to both Halo device fields and Halo custom fields. To add a new field mapping, press the plus icon in the top right corner of the field mapping table. This will display an input screen with three options.



You should first choose whether you would like to map to an asset field, or a custom field. Custom fields must be created before you can create a mapping to them. For device fields, there is an extra option that can be chosen which will create you a new field during the next import. Each Ninja RMM field can only be mapped once. When imported, the device's field value from the Ninja RMM field will be saved to the Halo field that you have mapped it too for that device.


Once you’re happy with your configuration, click the Import Devices button to load you device list from Ninja RMM into the importer screen. Software information is not displayed for each device on the importer screen, but will be imported as each device is imported.


Alert Management


Active alerts can be imported into Halo from Ninja RMM and created as tickets. If an alert is automatically resolved in Ninja, then the ticket will be automatically closed in Halo. If the ticket is closed in Halo, then the alert will be reset in Ninja RMM. This functionality requires use of the Halo Integrator, which is discussed later in this guide.


To manage alerts via the Halo Integrator, you must choose a ticket type that will be used whenever a new active alert is found, and also specify a default user for the alert. The default user will be overridden by the device's site/user if the active alert is linked to a device which exists in Halo when the ticket is created.



Halo Integrator


The Halo Integrator can be used to import organizations, locations, devices and alerts on a recurring schedule. To enable this functionality in the Halo Integrator, check the "Enable the Halo Integrator for the Ninja RMM integration" checkbox.



During each import, the Halo Integrator will retrieve all organizations and active alerts. Only device's which have been updated in Ninja RMM since the last sync date will be retrieved during the import, allowing you to run the Halo Integrator on a more frequent schedule. You can also choose whether or not the Halo Integrator should import all entities or just one entity using the drop down available. Use of the Halo Integrator is not discussed in this guide.



Popular Guides