Skip to content

A free open source IT asset/license management system

9.0 KB
Raw Blame
<?php

namespace App\SyncAdapters\NinjaOne;

use App\Models\Asset;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\PushableSyncAdapter;
use App\SyncAdapters\SyncAdapter;
use Carbon\Carbon;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;

/**
 * NinjaOne (formerly NinjaRMM) adapter. Pulls managed devices from the
 * REST API v2 (/v2/devices-detailed) via an OAuth 2.0 client-credentials
 * application, keyed on NinjaOne's stable device id.
 *
 * NinjaOne is region-hosted: `app.ninjarmm.com` (US), `eu.ninjarmm.com`
 * (EU), `oc.ninjarmm.com` (AU/NZ), `ca.ninjarmm.com` (CA). Admins pick
 * the region-appropriate host in the Base URL field so the OAuth token
 * endpoint and the devices endpoint stay on the same host (NinjaOne
 * doesn't split the two the way Microsoft Graph does).
 *
 * client_id is non-secret per OAuth 2.0 convention and stored plain
 * text so admins can audit which OAuth application a Snipe-IT instance
 * is talking to. client_secret is encrypted at rest.
 *
 * Push story: NinjaOne has no first-class asset_tag field, but the
 * admin can create per-device Custom Fields under Administration ->
 * Devices -> Custom Fields. Push writes to whichever custom field name
 * the admin puts in the "Asset Tag Custom Field Name" schema slot. If
 * empty, push silently no-ops (nothing to write to).
 */
class NinjaOneAdapter extends PushableSyncAdapter
{
    public static function typeLabel(): string
    {
        return 'NinjaOne';
    }

    public static function typeSlug(): string
    {
        return 'ninjaone';
    }

    public static function docsUrl(): ?string
    {
        return 'https://www.ninjaone.com/docs/application-programming-interface-api/public-api-operations/';
    }

    public function baseUrlPlaceholder(): ?string
    {
        return 'https://app.ninjarmm.com';
    }

    public function settingsSchema(): array
    {
        return [
            [
                'key' => 'client_id',
                'label' => trans('admin/settings/sync_adapters.label_client_id'),
                'help' => trans('admin/settings/sync_adapters.ninjaone_client_id_help'),
            ],
            [
                'key' => 'client_secret',
                'label' => trans('admin/settings/sync_adapters.label_client_secret'),
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.ninjaone_client_secret_help'),
            ],
            [
                'key' => 'asset_tag_custom_field',
                'label' => trans('admin/settings/sync_adapters.label_asset_tag_custom_field_name'),
                'required' => false,
                'help' => trans('admin/settings/sync_adapters.ninjaone_asset_tag_field_help'),
            ],
        ];
    }

    public function pull(): iterable
    {
        $client = new NinjaOneClient(
            baseUrl: $this->url(),
            clientId: $this->credential('client_id'),
            clientSecret: $this->credential('client_secret'),
        );

        foreach ($client->devices() as $device) {
            yield $this->normalize($device);
        }
    }

    /**
     * Convert a NinjaOne device payload into the normalized record
     * shape. NinjaOne's `id` is a stable long integer per registered
     * agent. We key asset_external_sources on it as a string.
     *
     * Hostname preference walks systemName -> dnsName -> netbiosName
     * because Ninja fills them opportunistically depending on OS and
     * agent version. Serial preference walks the SMBIOS system serial
     * first, then falls back to the BIOS serial (VM hosts often only
     * populate one or the other).
     *
     * @param  array<string, mixed>  $device
     */
    private function normalize(array $device): HostInventoryRecord
    {
        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: (string) Arr::get($device, 'id'),
            hostname: Arr::get($device, 'systemName')
                ?? Arr::get($device, 'dnsName')
                ?? Arr::get($device, 'netbiosName'),
            hardwareSerial: Arr::get($device, 'system.serialNumber')
                ?? Arr::get($device, 'system.biosSerialNumber')
                ?? Arr::get($device, 'serialNumber'),
            hardwareModel: Arr::get($device, 'system.model')
                ?? Arr::get($device, 'model'),
            manufacturer: Arr::get($device, 'system.manufacturer')
                ?? Arr::get($device, 'manufacturer'),
            primaryMac: null, // Ninja returns per-adapter MACs via a separate endpoint; not worth an extra call per device today
            primaryIp: Arr::get($device, 'publicIP'),
            os: Arr::get($device, 'os.name') ?? Arr::get($device, 'nodeClass'),
            osVersion: Arr::get($device, 'os.buildNumber')
                ?? Arr::get($device, 'os.releaseId'),
            lastSeen: $this->parseTimestamp(Arr::get($device, 'lastContact')),
            assignedUserEmail: null,
            assignedUserName: Arr::get($device, 'userTitle'),
            vendorGroupId: (string) (Arr::get($device, 'organizationId') ?? ''),
            extra: [
                'ninjaone_node_class' => Arr::get($device, 'nodeClass'),
                'ninjaone_organization_id' => Arr::get($device, 'organizationId'),
                'ninjaone_location_id' => Arr::get($device, 'locationId'),
                'ninjaone_offline' => Arr::get($device, 'offline'),
                'ninjaone_chassis_type' => Arr::get($device, 'chassisType'),
            ],
        );
    }

    /**
     * NinjaOne emits lastContact as a Unix epoch (seconds, sometimes
     * fractional). Bail on absent / zero values so we don't record
     * "device last seen in 1970".
     */
    private function parseTimestamp(mixed $value): ?Carbon
    {
        if ($value === null || $value === '' || $value === 0) {
            return null;
        }

        return Carbon::createFromTimestamp((float) $value);
    }

    /**
     * NinjaOne push is always available in principle. Per-write
     * validity depends on the admin having created the custom field
     * whose name is in the schema slot. Not a canPush gate because
     * "field not configured" is different from "vendor doesn't
     * support push at all".
     */
    public function canPush(): bool
    {
        return true;
    }

    /**
     * NinjaOne has no first-class freeform notes field. Composed
     * notes would require another admin-configured custom field
     * (same pattern as asset_tag) which we can add if there's demand.
     */
    public function notesFieldTarget(): ?string
    {
        return null;
    }

    /**
     * Push Snipe-IT asset_tag to a NinjaOne custom field. NinjaOne
     * doesn't expose a top-level asset_tag column, so the admin must
     * pre-create a custom field in the NinjaOne dashboard and put its
     * name in the "Asset Tag Custom Field Name" schema slot. If the
     * slot is blank, buildPushPayload returns empty and the template
     * short-circuits. If the slot has a name but no such field exists
     * in NinjaOne, NinjaOne returns a 4xx and the error surfaces via
     * the controller's outer catch.
     *
     * @param  array<int, string>  $changedFields
     */
    public function push(Asset $asset, array $changedFields = []): bool
    {
        return $this->pushViaSinglePayload($asset, $changedFields);
    }

    /**
     * @return array{0: array<string, mixed>, 1: array<int, string>}
     */
    protected function buildPushPayload(Asset $asset): array
    {
        $customFieldName = $this->credentialOrNull('asset_tag_custom_field');
        if ($customFieldName === null || $customFieldName === '') {
            Log::channel('sync-adapters')->info(sprintf(
                '%s push: skipped asset %d (no Ninja custom field name configured)',
                $this->name(),
                $asset->id,
            ));

            return [[], []];
        }

        $payload = [];
        $value = in_array('asset_tag', $this->pushDirectedFields(), true)
            ? $this->assetValueForSourceField($asset, 'asset_tag')
            : null;
        if ($value !== null && $value !== '') {
            $payload[$customFieldName] = $value;
        }

        return [$payload, []];
    }

    /**
     * @param  array<string, mixed>  $payload
     */
    protected function dispatchPush(\App\Models\AssetExternalSource $externalSource, array $payload): void
    {
        $client = new NinjaOneClient(
            baseUrl: $this->url(),
            clientId: $this->credential('client_id'),
            clientSecret: $this->credential('client_secret'),
        );
        $client->updateDeviceCustomFields($externalSource->external_id, $payload);
    }

    /**
     * credential() throws when the key is absent. For optional fields
     * (required=false in the schema) we want a nullable read, so wrap
     * with a catch and return null.
     */
    private function credentialOrNull(string $key): ?string
    {
        try {
            return $this->credential($key);
        } catch (\Throwable) {
            return null;
        }
    }
}