Usage Manual
This page describes how the connector can be used and configured.
Prerequisites
The connector reads data from the Claroty REST API, so the CMDBuild server must be able to reach the Claroty API endpoint over HTTPS (for example https://eu.api.claroty.com, depending on the region of the Claroty tenant). The connector does not validate the TLS certificate of the server.
The connector authenticates with a static API token generated in Claroty: the token is sent in every request in the Authorization header with the Bearer scheme. No username or password is required.
The token must be allowed to call the following API endpoints (all invoked with the POST method):
POST /api/v1/devices/
POST /api/v1/site-groups/get
POST /api/v1/sites/get
Service version
The connector has been tested with xDome API version 1.0.0.
Connector dependencies
The connector requires the installation of the Connector utils plugin version 2.0.9 or higher and CMDBuild version 4.2.3 or higher.
Configuration
Plugin configuration
The standard connector plugin configuration can be found here.
The connector has no additional configurations.
Instance configuration
Each Claroty instance to be read is a card of the Claroty class (ClarotyConfig). Only active instances are read during the synchronization.
| Config | Default | Description | Notes |
|---|---|---|---|
Key* | Unique code of the instance | Used in the description of the imported records and in the notifications | |
Active* | Enables the instance | Inactive instances are skipped by the synchronization | |
Base URL* | Base URL of the Claroty API | Without the API path, e.g. https://eu.api.claroty.com | |
Token* | API token used for the authentication | Stored as a password attribute | |
Page size | 100 | Number of records requested for each page | Allowed values from 1 to 5000; empty, zero, negative or greater values use the default |
Number of threads | 8 | Number of threads used in parallel to process the devices and generate the device and network interface records | Empty, zero or negative values use the default |
Thread timeout | 15 | Minutes to wait for the termination of the device processing threads | Empty, zero or negative values use the default. If the threads do not end in time, the reading of the instance fails |
Entities preview
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.
- Site group (
sitegroup) - Site (
site) - Device (
device) - Network interface (
networkinterface) – calculated from the network data of each device
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.