HaloITSM Guides
Documentation to assist with the setup and configuration of the HaloITSM platform
NinjaOne Integration (API v2)
To enable the NinjaOne 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 NinjaOne. If you are an existing client with a connected NinjaOne 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.
When heading to the NinjaOne integration configuration within Halo, if you do not see options to enter a client ID/client secret then you do not need to follow the below steps:
- Registering an OAuth Application (legacy connection method)
- Connecting to the NinjaOne Application (legacy connection method)
Instead, simply select your location & click 'Connect'. You will then be redirected to the NinjaOne login, upon logging in you will be redirected back to Halo, where you can continue configuring the integration. If the connection fails when using this method, please try again with one of the other locations.
Registering an OAuth Application (Legacy connection method)
So that Halo can communicate with version 2 of the NinjaOne API, an OAuth application must be registered in NinjaOne. To do this, open NinjaOne and navigate to Configuration > Integrations > API > Client App IDs and select "Add". On the creation screen choose the following values:
Field Name | Field Value |
Application platform | Web (PHP, Java, .Net Core, etc.) |
Name | Halo PSA |
Redirect URI | https://auth.halopsa.com/externalauth |
Scopes | Monitoring, Management |
Allowed Grant Types | Refresh 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 NinjaOne module:
Connecting to the NinjaOne Application (legacy connection method)
Now that an OAuth application has been configured, open the NinjaOne (NinjaRMM) module in Halo. You are required to select the location of your hosted NinjaOne 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 NinjaOne 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 NinjaOne and created as clients and sites. To assist with linking organizations and locations in NinjaOne 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 NinjaOne 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 > Asset Management > 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 NinjaOne. All devices must be associated with a site in Halo, therefore, if the imported device's NinjaOne 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 NinjaOne device's type. You can choose which field is uses as the NinjaOne 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 NinjaOne 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 NinjaOne 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 NinjaOne 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 a new field during the next import. Each NinjaOne field can only be mapped once. When imported, the device's field value from the NinjaOne field will be saved to the Halo field that you have mapped it to for that device.
Once you’re happy with your configuration, click the Import Devices button to load your device list from NinjaOne 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
Webhooks support was recently added (v2.105 of Halo) so that you don't need to import Alerts regularly and they are created almost instantly instead.
The setup in NinjaOne is in two steps.
1. Setup the Webhook as below
The webhook format is as follows: https://yourhaloaddress.com/api/notify/ninja/alerts where 'yourhaloaddress' is your halo instance address like company.halopsa.com or halo.yourcomanydomain.com.
2. Edit your policies so that this webhook is included
Active alerts can be imported into Halo from NinjaOne and created as tickets. If an alert is automatically resolved in NinjaOne, then the ticket will be automatically closed in Halo. If the ticket is closed in Halo, then the alert will be reset in NinjaOne. 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. The selection of entities to import is on a multi-select basis, so multiple entities can be chosen from the list, not just all or one.
NB: It is Important to import customers and sites first, before importing items and assets.
To enable this functionality in the Halo Integrator, check the "Enable the Halo Integrator for the NinjaOne integration" checkbox.
During each import, the Halo Integrator will retrieve all organizations. Only device's which have been updated in NinjaOne 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
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management in Halo
- Creating a New Application for API Connections
- Creating Agents and Editing Agent Details
- Departments, Teams and Roles
- Halo Integrator
- Importing Data
- Multiple New Portals with different branding for one customer [Hosted]
- NHServer Deprecation User Guide
- Organisation Basics
- Organising Teams of Agents
- Step-by-Step Configuration Walk Through
- Suppliers