A free open source IT asset/license management system
<?php
namespace App\SyncAdapters\EndpointCentral;
use App\Models\Asset;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\PushableSyncAdapter;
use Carbon\Carbon;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;
/**
* ManageEngine Endpoint Central adapter. Pulls managed-computer
* inventory from a cloud OR on-prem Endpoint Central tenant and
* normalizes it into HostInventoryRecord objects. Also pushes
* Snipe-IT's asset_tag back to the vendor as the device's "Remarks"
* freeform field (the writable free-text slot ME exposes per
* computer).
*
* Deployment variants:
*
* Cloud: hosted on Zoho's infrastructure, OAuth 2.0 refresh-token
* flow against accounts.zoho.{region}. Admin generates a refresh
* token at api-console.zoho.com with scopes DesktopCentralCloud.SOM
* (plus .Inventory for the hardware opt-in and .SOM.CREATE for
* push) and pastes the client ID + secret + refresh token into
* Snipe-IT. The data_center setting selects the right regional
* accounts host.
*
* On-prem: admin issues an API Key / AuthToken from Admin ->
* Integrations in the on-prem console and pastes it in. Snipe-IT
* sends it as a Zoho-authtoken header per ME's historical scheme.
* FIXME: unverified against a modern on-prem tenant.
*
* Serial resolution: the list endpoint omits hardware serial. An
* opt-in setting enables a per-device detail fetch at pull time
* so adopt_by_serial works. Costs an extra API call per device per
* sync when the opt-in is on.
*
* ME API docs: https://www.manageengine.com/products/desktop-central/help/api/cloud/api-index.html
*/
class EndpointCentralAdapter extends PushableSyncAdapter
{
private const DATA_CENTERS = [
'us' => 'US (accounts.zoho.com)',
'eu' => 'EU (accounts.zoho.eu)',
'in' => 'India (accounts.zoho.in)',
'au' => 'Australia (accounts.zoho.com.au)',
'cn' => 'China (accounts.zoho.com.cn)',
'jp' => 'Japan (accounts.zoho.jp)',
];
public static function typeLabel(): string
{
return 'ManageEngine Endpoint Central';
}
public static function typeSlug(): string
{
return 'endpoint_central';
}
public static function docsUrl(): ?string
{
return 'https://www.manageengine.com/products/desktop-central/help/api/cloud/api-index.html';
}
public function baseUrlPlaceholder(): ?string
{
return 'https://desktopcentralcloud.manageengine.com';
}
public function settingsSchema(): array
{
return [
[
'key' => 'mode',
'label' => trans('admin/settings/sync_adapters.endpoint_central_label_mode'),
'type' => 'select',
'options' => [
EndpointCentralClient::MODE_CLOUD => trans('admin/settings/sync_adapters.endpoint_central_option_mode_cloud'),
EndpointCentralClient::MODE_ONPREM => trans('admin/settings/sync_adapters.endpoint_central_option_mode_onprem'),
],
'default' => EndpointCentralClient::MODE_CLOUD,
'help' => trans('admin/settings/sync_adapters.endpoint_central_mode_help'),
],
// Cloud-only credentials.
[
'key' => 'data_center',
'label' => trans('admin/settings/sync_adapters.endpoint_central_label_data_center'),
'type' => 'select',
'options' => self::DATA_CENTERS,
'default' => 'us',
'required' => false,
'help' => trans('admin/settings/sync_adapters.endpoint_central_data_center_help'),
],
[
'key' => 'client_id',
'label' => trans('admin/settings/sync_adapters.label_client_id'),
'required' => false,
'help' => trans('admin/settings/sync_adapters.endpoint_central_client_id_help'),
],
[
'key' => 'client_secret',
'label' => trans('admin/settings/sync_adapters.label_client_secret'),
'secret' => true,
'required' => false,
'help' => trans('admin/settings/sync_adapters.endpoint_central_client_secret_help'),
],
[
'key' => 'refresh_token',
'label' => trans('admin/settings/sync_adapters.endpoint_central_label_refresh_token'),
'secret' => true,
'required' => false,
'help' => trans('admin/settings/sync_adapters.endpoint_central_refresh_token_help'),
],
// On-prem-only credential.
[
'key' => 'auth_token',
'label' => trans('admin/settings/sync_adapters.endpoint_central_label_auth_token'),
'secret' => true,
'required' => false,
'help' => trans('admin/settings/sync_adapters.endpoint_central_auth_token_help'),
],
// Opt-in N+1 hardware fetch for serial resolution.
[
'key' => 'fetch_hardware_details',
'label' => trans('admin/settings/sync_adapters.endpoint_central_label_fetch_hardware_details'),
'type' => 'checkbox',
'required' => false,
'help' => trans('admin/settings/sync_adapters.endpoint_central_fetch_hardware_details_help'),
],
];
}
public function extraFields(): array
{
return [
'endpoint_central_resource_id' => ['label_key' => 'admin/settings/sync_adapters.endpoint_central_extra_resource_id'],
'endpoint_central_live_status' => ['label_key' => 'admin/settings/sync_adapters.endpoint_central_extra_live_status'],
'endpoint_central_agent_version' => ['label_key' => 'admin/settings/sync_adapters.extra_agent_version'],
'endpoint_central_domain' => ['label_key' => 'admin/settings/sync_adapters.endpoint_central_extra_domain'],
'endpoint_central_remote_office' => ['label_key' => 'admin/settings/sync_adapters.endpoint_central_extra_remote_office'],
];
}
public function supportsGroupScoping(): bool
{
// Remote Office is ME's per-site tenancy construct. Admins can
// route devices to Snipe-IT companies via the group mapping UI
// once we expose the Remote Office id as the vendor group id.
return true;
}
public function vendorGroupLabel(): string
{
return trans('admin/settings/sync_adapters.endpoint_central_vendor_group_remote_office');
}
public function fetchGroups(): array
{
// FIXME: ME has a Remote Offices endpoint
// (/dcapi/som/remoteOffices) that would populate this. Returning
// an empty list for v1 so the group-mapping UI is visible but
// callers cannot pick a vendor group until this is wired up
// against a tenant.
return [];
}
public function pull(): iterable
{
$client = $this->buildClient();
$fetchHardware = $this->credentialBool('fetch_hardware_details');
foreach ($client->computers() as $computer) {
$hardwareDetails = null;
if ($fetchHardware) {
$resourceId = (string) ($computer['computerId'] ?? '');
if ($resourceId !== '') {
$hardwareDetails = $client->hardwareDetails($resourceId);
}
}
yield $this->normalize($computer, $hardwareDetails);
}
}
private function buildClient(): EndpointCentralClient
{
$mode = $this->credentialOrDefault('mode', EndpointCentralClient::MODE_CLOUD);
$dataCenter = $this->credentialOrDefault('data_center', 'us');
$accountsHost = EndpointCentralClient::ZOHO_ACCOUNTS_HOSTS[$dataCenter]
?? EndpointCentralClient::ZOHO_ACCOUNTS_HOSTS['us'];
return new EndpointCentralClient(
mode: $mode,
baseUrl: $this->url(),
clientId: $this->credentialOrNull('client_id'),
clientSecret: $this->credentialOrNull('client_secret'),
refreshToken: $this->credentialOrNull('refresh_token'),
accountsHost: $accountsHost,
authToken: $this->credentialOrNull('auth_token'),
);
}
/**
* Convert one computer payload into the normalized record shape.
* The computerId from the list endpoint is stable per enrolled
* device and is what we key asset_external_sources on. When the
* hardware opt-in is on, pull the serial out of
* biosDetails[0].serialNumber (the common location per the ME
* hardware response).
*
* @param array<string, mixed> $computer
* @param array<string, mixed>|null $hardwareDetails
*/
private function normalize(array $computer, ?array $hardwareDetails): HostInventoryRecord
{
// ME's list endpoint has no hardware model string. When the
// opt-in hardware fetch is off, fall back to the osName so
// admins get a reasonable grouping (per Windows release, per
// macOS version, etc.) rather than a null that would reject
// the AssetModel save. Admins who turn on fetch_hardware_details
// get the actual motherboard model name.
$hardwareModel = self::extractHardwareModel($hardwareDetails)
?? Arr::get($computer, 'osName')
?? Arr::get($computer, 'osPlatform');
return new HostInventoryRecord(
sourceKey: $this->name(),
sourceId: (string) Arr::get($computer, 'computerId'),
hostname: Arr::get($computer, 'computerName'),
hardwareSerial: self::extractSerialNumber($hardwareDetails),
hardwareModel: $hardwareModel,
manufacturer: self::extractManufacturer($hardwareDetails),
primaryMac: self::firstMacAddress(Arr::get($computer, 'macAddress')),
primaryIp: Arr::get($computer, 'ipAddress'),
os: Arr::get($computer, 'osPlatform') ?? Arr::get($computer, 'osName'),
osVersion: Arr::get($computer, 'osVersion'),
lastSeen: $this->parseTimestamp(Arr::get($computer, 'lastContactTime')),
assignedUserName: self::firstLoggedUser(Arr::get($computer, 'loggedUsers')),
vendorGroupId: Arr::has($computer, 'remoteOfficeID') ? (string) Arr::get($computer, 'remoteOfficeID') : null,
extra: [
'endpoint_central_resource_id' => (string) Arr::get($computer, 'computerId'),
'endpoint_central_live_status' => Arr::get($computer, 'liveStatus'),
'endpoint_central_agent_version' => Arr::get($computer, 'agentVersion'),
'endpoint_central_domain' => Arr::get($computer, 'domainName'),
'endpoint_central_remote_office' => Arr::get($computer, 'remoteOfficeName'),
],
);
}
/**
* ME's hardware endpoint groups BIOS entries under biosDetails as
* an array. The device serial lives on the first (typically only)
* entry. motherBoardDetails[0].serialNumber is the fallback when
* biosDetails is absent, which happens on some device classes.
*
* @param array<string, mixed>|null $hardwareDetails
*/
private static function extractSerialNumber(?array $hardwareDetails): ?string
{
if ($hardwareDetails === null) {
return null;
}
$candidates = [
Arr::get($hardwareDetails, 'biosDetails.0.serialNumber'),
Arr::get($hardwareDetails, 'motherBoardDetails.0.serialNumber'),
];
foreach ($candidates as $value) {
if (is_string($value) && $value !== '') {
return $value;
}
}
return null;
}
/**
* Hardware model string from the motherboard or system group.
*
* @param array<string, mixed>|null $hardwareDetails
*/
private static function extractHardwareModel(?array $hardwareDetails): ?string
{
if ($hardwareDetails === null) {
return null;
}
$candidates = [
Arr::get($hardwareDetails, 'motherBoardDetails.0.hardwareName'),
Arr::get($hardwareDetails, 'motherBoardDetails.0.hardwareDescription'),
];
foreach ($candidates as $value) {
if (is_string($value) && $value !== '') {
return $value;
}
}
return null;
}
/**
* Manufacturer string from the motherboard or BIOS group.
*
* @param array<string, mixed>|null $hardwareDetails
*/
private static function extractManufacturer(?array $hardwareDetails): ?string
{
if ($hardwareDetails === null) {
return null;
}
$candidates = [
Arr::get($hardwareDetails, 'motherBoardDetails.0.hardwareManufacturer'),
Arr::get($hardwareDetails, 'biosDetails.0.hardwareManufacturer'),
];
foreach ($candidates as $value) {
if (is_string($value) && $value !== '') {
return $value;
}
}
return null;
}
/**
* ME returns macAddress as a comma-separated list when a device
* has multiple interfaces. Grab the first non-empty entry for
* the normalized primaryMac slot. The rest live on the raw
* payload and admins can map them to custom fields separately.
*/
private static function firstMacAddress(mixed $raw): ?string
{
if (! is_string($raw) || $raw === '') {
return null;
}
foreach (explode(',', $raw) as $candidate) {
$candidate = trim($candidate);
if ($candidate !== '') {
return $candidate;
}
}
return null;
}
/**
* loggedUsers is a comma-separated list of recent logged-in
* accounts, newest first per ME's convention. We take the first
* for the normalized assignedUserName slot and let admins map
* the raw string to a custom field if they want the full list.
*/
private static function firstLoggedUser(mixed $raw): ?string
{
if (! is_string($raw) || $raw === '') {
return null;
}
foreach (explode(',', $raw) as $candidate) {
$candidate = trim($candidate);
if ($candidate !== '') {
return $candidate;
}
}
return null;
}
private function parseTimestamp(mixed $value): ?Carbon
{
if ($value === null || $value === '') {
return null;
}
try {
// ME emits timestamps as both ISO 8601 strings and Unix epoch
// milliseconds depending on endpoint version. Numeric input
// in the plausible ms range is treated as epoch milliseconds.
if (is_numeric($value) && $value >= 1_000_000_000_000 && $value <= 100_000_000_000_000) {
return Carbon::createFromTimestampMsUTC((int) $value);
}
return Carbon::parse($value);
} catch (\Throwable $e) {
Log::channel('sync-adapters')->warning(
$this->name().': skipped unparseable Endpoint Central timestamp ('.var_export($value, true).'): '.$e->getMessage()
);
return null;
}
}
private function credentialOrNull(string $key): ?string
{
try {
$value = $this->credential($key);
} catch (\Throwable) {
return null;
}
return $value === '' ? null : $value;
}
private function credentialOrDefault(string $key, string $default): string
{
$value = $this->credentialOrNull($key);
return $value ?? $default;
}
private function credentialBool(string $key): bool
{
return $this->credentialOrNull($key) === '1';
}
/**
* ME exposes Remarks as the writable per-computer freeform slot
* admins commonly use for inventory tags. canPush is always true
* for a configured instance since the write capability is tied to
* the OAuth scope / API token (gated at auth time rather than
* per-request).
*/
public function canPush(): bool
{
return true;
}
/**
* ME's "Remarks" freeform field is a plausible notes target but
* we already route asset_tag there (the writable per-computer
* slot). Keeping notes unmapped for v1 so admins can configure
* push-asset_tag without accidentally overwriting Remarks via
* two paths. Revisit once ME exposes a separate notes field.
*/
public function notesFieldTarget(): ?string
{
return null;
}
/**
* Snipe-IT asset_tag flows to ME's Remarks freeform field.
*
* @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
{
$payload = [];
$pushed = [];
if (in_array('asset_tag', $this->pushDirectedFields(), true)) {
$value = $this->assetValueForSourceField($asset, 'asset_tag');
if (is_string($value) && $value !== '') {
$payload['remarks'] = $value;
$pushed[] = 'asset_tag';
}
}
return [$payload, $pushed];
}
/**
* @param array<string, mixed> $payload
*/
protected function dispatchPush(\App\Models\AssetExternalSource $externalSource, array $payload): void
{
$this->buildClient()->updateRemarks($externalSource->external_id, $payload);
}
}