HaloPSA

HaloPSA Guides

Documentation to assist with the setup and configuration of the HaloPSA platform

Guides > NinjaOne Integration

NinjaOne Integration

The following video covers the setup of the NinjaOne integration:



This video from Renada Solutions will Cover the Mapping of Ninja Devices to Users in Halo:



In this guide we will cover:

- Configuring the NinjaOne Module

- Organizations and Locations

- Devices and Software

- Alert Management

- Halo Integrator



Configuring the NinjaOne Module

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.

Fig 1. Enabling the module.


Once complete, click into the module to begin configuration. 


Choosing an Authentication Type (v2.188+)

From v2.188+ you will have an option to choose an authentication type for the integration. 


Fig 2. Authentication Type


Use the Halo app (recommended) - This is the recommended option and should be selected by all hosted customers. When this option is selected you will need to authenticate the integration by logging into your Ninja One account. 


Use a custom developer app - This option should only be selected if you are unable to authenticate successfully using the Halo app method. As this option does not support webhooks. On-premise customers that do not allow their Halo instance to communicate with our API will need to use this authentication method. When this option is selected you will need to authenticate the integration using a client ID and secret. 


Note: When you update to v2.188+ the 'Halo app' method will be selected by default. 



Now 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.


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.


Fig 3. Selecting a top level and importing.


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.

Fig 4. Devices and software configuration.


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:

Fig 5. Field to determine asset type.


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.

Fig 6. Field mappings popup.


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.


Only apply this mapping to new Assets and Assets where the Asset field does not currently have a value - This setting is used when changing an existing mapping. This allows you to prevent data in the previously mapped field moving to the the newly mapped field, as when enabled any assets that already have data in this field will not have the data overridden. 


User matching 

You can also use turn on user-matching underneath this table, and choose how this is matched. This can be based on a Ninja Custom field or the last logged in user. This will determine how assets are matched to users, if matched the asset will be assigned to the associated user in Halo. 

Fig 7. User matching.


Matching Based on Last logged in User - When this is enabled the user that was last logged into the asset (device) will be checked. This user will then be matched to a user in Halo based on the 'User matching field' selected. Therefore, if users are logging into devices using their windows username you will need to set 'Windows username' in the 'User matching field' field.


Ninja usually stores the value for 'lastloggedinuser' like so: HL-LPT-00112\\Tim Bowers ,when matching takes place both the whole value here will attempted to be matched on, and the section after the slashes ('Tim Bowers'). 


If you have chosen 'windows username' as the user matching field, user matching will only work for users imported from Azure/CSP (Microsoft). This is because windows username (network login) is not stored in Halo, and needs to be imported from one of these integrations. 


Ninja Custom Field to use for matching User - Here you can enter a Ninja custom field. This will work in conjunction with the 'User Matching Field' to match assets to users. 


You can also set whether to import warranty information for your devices.


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

Alerts in Ninja can either be processed using the Halo integrator or using webhooks. When using the Halo integrator alerts will be imported on a scheduled basis, when using webhooks alerts will be imported into Halo as soon as they are raised in Ninja. When an alert is raised in Ninja a ticket will be raised in Halo, when the alert is resolved in Ninja the ticket in Halo will automatically be closed. Additionally if the ticket is resolved in Halo the alert will be reset in NinjaOne. 


Note: If you are using the 'custom developer app' authentication method webhooks will not be supported.


Process alerts with Webhooks

The setup in NinjaOne is in two steps.


1. Setup the Webhook as below.


Fig 8. Enabling the webhook.


The webhook format is as follows: https://YOURHALODOMAIN.com/api/notify/ninja/alerts where 'YOUHALODOMAIN' is your halo instance address like company.halopsa.com or halo.yourcomanydomain.com. 


2. Edit your policies so that this webhook is included.


Fig 9. Including the webhook.


Once you have setup the webhook in Ninja head back to the NinjaOne integration module in Halo > Alerting tab.  

Fig 10. Alerting setup for NinjaOne integration


Here, choose the ticket type alerts will be created using and the user alert tickets will be assigned to. 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. 


Once you are happy with your setup enable 'Enable alert processing via webhooks'. Now as soon as an alert is raised in Ninja a ticket will be logged in Halo. When this alert is resolved in Ninja the ticket will be automatically resolved in Halo. If the ticket is closed in Halo, then the alert will be reset in NinjaOne. 


From v2.186+ you can also map the 'activity type' field in Ninja to a category or single select field in Halo for alerts. 

Fig 11. Activity type mapping


If a mapping is set, data in the activity type field of the alert will be imported to the Halo field selected here, allowing you to see it against the ticket in Halo. This mapping only applies when webhooks are being used to process alerts, if you are processing alerts using the Halo integrator this mapping will not apply.  


Process alerts with the Halo integrator

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.


Fig 12. Alert defaults.


Once this is set ensure you have enabled the Halo integrator for the integration (see next section) and added 'Alerts' as an entity to import. 


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. 


Note: 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.


Fig 13. Enabling the integrator.


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.


The deeplink input for Halo's ninja integration will be your branded Ninja URL (Custom URL).


With the Ninja integration you can now Trigger scripts from Halo automatically with a custom setup using runbooks, the details are covered in this guide: Triggering Automation Policies in RMM via HaloPSA.

Popular Guides