Usage Manual

This page describes how the connector can be used and configured.

Prerequisites

The connector requires HTTPS network access to the NinjaOne instance hosting the account (by default https://eu.ninjarmm.com). In particular it calls:

• {Url}/ws/oauth/token, to obtain the access token;
• {Url}/v2/..., the NinjaOne public REST API (organizations, locations, users, contacts and detailed devices).

A NinjaOne API client application must be provided for each connector instance, exposing the following values:

• Client ID
• Client secret
• Refresh token (optional)

The connector authenticates through OAuth 2.0 and supports two modes:

• client credentials (default, used when no refresh token is configured): the connector requests an access token using the client ID and secret, with the scope monitoring;
• refresh token: when a refresh token is configured, the connector requests the access token with the refresh_token grant, using the client ID, secret and refresh token. The refresh token must be obtained by using the Authorization Code Flow with the scope offline_access.

The connector only performs read requests. The access token must grant the following scope:

monitoring

Service configuration

Create an API client application in NinjaOne that allows the client credentials flow (and, if the refresh token mode is used, the authorization code flow with refresh tokens), and record its Client ID and Client secret, as these values are required in the connector instance configuration.

If the refresh token mode is used, obtain the refresh token through the Authorization Code Flow requesting the scope offline_access, and copy it in the instance configuration.

Connector dependencies

The connector requires the installation of the Connector utils plugin version 2.0.9 or higher and CMDBuild version 4.2.0 or higher.

Configuration

Plugin configuration

The standard connector plugin configuration can be found here. This plugin has no additional configurations.

Instance configuration

Config	Default	Description	Notes
Code*		Unique name used to identify the connector instance.	Used in executions, logs, notifications, and data source references.
Active*	true	Defines whether the instance is included in connector batch executions.
Url	https://eu.ninjarmm.com	Base URL of the NinjaOne instance hosting the account.	Used to build both the authentication URL ({Url}/ws/oauth/token) and the API URL ({Url}/v2), so it must not end with /. When empty, the default is used.
Client ID*		Client ID of the NinjaOne API client application.
Client secret*		Client secret of the NinjaOne API client application.	Stored as a password.
Refresh token		Refresh token used to obtain the access token.	Stored as a password. When empty, the client credentials flow is used; when set, the refresh_token grant is used. Must be obtained by using the Authorization Code Flow with the scope offline_access.
Page size	150	Number of elements requested for each page of the paginated API calls.

Entities preview

100%

The diagram provides a high-level overview of the entities extracted by the connector and the relationships between them.

The diagram uses the following conventions:

• Orange containers represent CMDBuild superclasses. The entities contained within them belong to the corresponding superclass.

• Blue boxes represent record types extracted by the connector. Each box is labeled using the format {Source Object Name} ({_type}), combining the object name used by the source service with the internal record type produced by the connector.

• Blue boxes with a dashed border represent calculated entities. These records do not directly correspond to objects exposed by the source system but are generated during data processing to represent information that would otherwise be embedded within another record.

• Arrows represent relationships between entities managed by the connector. The arrow points to the "many" side of the relationship, as indicated by its label (1 : N).

Below is a list of all the entities retrieved by the connector.

• Organization (organization)
• Location (location)
• User (user)
• Contact (contact)
• Device (device)
• Processor (processor)
• Volume (volume)

Additional Information

Synchronization to Application Classes

The standard connector imports and maintains data within the CMDBuild standard classes and relationships, providing a consistent representation of the data.

As a separate and optional customization activity, organizations may define additional synchronization processes to populate application-specific classes from the imported infrastructure data. Through custom mappings and enrichment rules, connector resources can be associated with organization-specific business objects, services, assets, or other application entities.

This approach supports customer-specific business models, enrichment processes, and classification rules while preserving the standard infrastructure representation provided by the connector.

Known Limitations

• The connector operates in read-only mode.
• Large environments may require increased execution time.
• No real-time synchronization: data is updated only during scheduled runs.
• The plugin is distributed under a Premium license model. Its usage is tied to an active support and maintenance agreement, which is subject to expiration and must be renewed to remain valid.

Deployment Guidelines

Deployment of the connector includes the creation of standard CMDBuild classes and relationships corresponding to supported connector resource types. These structures provide the foundation for storing and organizing synchronized infrastructure information. The deployment process also includes configuration elements required for data visualization and the establishment of scheduled synchronization activities.

Following deployment, it is recommended to validate the configuration by executing an initial synchronization and reviewing the imported data.

Scheduling frequency should be selected according to the scale of the environment, expected rate of infrastructure change, and operational reporting requirements.