A free open source IT asset/license management system
<?php
namespace App\SyncAdapters\Mosyle;
use App\Models\Asset;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\PushableSyncAdapter;
use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;
/**
* Mosyle adapter. Pulls device inventory from a Mosyle Manager v2
* tenant via the Mosyle API and normalizes it into HostInventoryRecord
* objects. Also pushes Snipe-IT-authoritative asset_tag back via
* Mosyle's /devices elements endpoint.
*
* Business v1 (businessapi.mosyle.com/v1) uses a different endpoint
* shape than Manager v2 and is not covered by this adapter today. The
* base URL field accepts a Business URL but the device endpoints
* expect Manager-shaped payloads, so Business tenants will see the
* login succeed and device calls fail. See issue #19790.
*/
class MosyleAdapter extends PushableSyncAdapter
{
use UsesAppleDbEnrichment;
/**
* Per-category-selector config keys -> friendly display name. Same
* split pattern as ABM: Mosyle's device_type is a four-value enum
* (mac / ios / tvos / visionos) but admins usually want MacBook vs.
* iMac/Mini/Studio/Pro in separate Snipe-IT categories, and iPhone
* vs. iPad in separate ones too. categoryConfigKeyForRecord()
* encodes the device_type + model prefix mapping below. Issue
* #19884.
*
* @var array<string, string>
*/
private const CATEGORY_SELECTORS = [
'category_id_mac_laptop' => 'Mac Laptop',
'category_id_mac_desktop' => 'Mac Desktop',
'category_id_iphone' => 'iPhone',
'category_id_ipad' => 'iPad',
'category_id_appletv' => 'Apple TV',
'category_id_vision' => 'Apple Vision',
];
public static function typeLabel(): string
{
// Mosyle Manager and Mosyle Business are different products
// with different API shapes. This adapter targets Manager v2
// only. Labeling it as "Mosyle Manager" in the adapter picker
// keeps Business customers from configuring this expecting it
// to work against businessapi.mosyle.com/v1.
return 'Mosyle Manager';
}
public static function typeSlug(): string
{
return 'mosyle';
}
public static function docsUrl(): ?string
{
return 'https://school.mosyle.com/solutions/macos/privilege-management';
}
public function baseUrlPlaceholder(): ?string
{
return 'https://managerapi.mosyle.com/v2';
}
public function settingsSchema(): array
{
$schema = [
[
'key' => 'access_token',
'label' => trans('admin/settings/sync_adapters.label_access_token'),
'secret' => true,
'help' => trans('admin/settings/sync_adapters.mosyle_access_token_help'),
],
[
'key' => 'email',
'label' => trans('general.email'),
'help' => trans('admin/settings/sync_adapters.mosyle_email_help'),
],
[
'key' => 'password',
'label' => trans('general.password'),
'secret' => true,
'help' => trans('admin/settings/sync_adapters.mosyle_password_help'),
],
$this->appleDbSettingsField(),
];
// Per-family category overrides. Mirrors the ABM pattern (which
// uses the same Apple product-family vocabulary). Translation
// keys are shared across both adapters because the strings are
// adapter-neutral and the FOSS translator community pays the
// cost of every new key. Empty selection falls back to
// default_category_id.
foreach (self::CATEGORY_SELECTORS as $key => $displayName) {
$schema[] = [
'key' => $key,
'label' => trans('admin/settings/sync_adapters.abm_category_family_label', ['family' => $displayName]),
'type' => 'category',
'required' => false,
'section' => 'categories',
'help' => trans('admin/settings/sync_adapters.abm_category_family_help', ['family' => $displayName]),
];
}
return $schema;
}
public function settingsSections(): array
{
return [
'categories' => [
'title' => trans('admin/settings/sync_adapters.abm_section_categories_title'),
],
];
}
/**
* Route each record to a per-family category when the admin
* configured one. Falls through to defaultCategoryId() when the
* device_type / model prefix doesn't match a configured selector,
* matching the ABM adapter's convention.
*/
public function categoryIdForRecord(HostInventoryRecord $record): ?int
{
$configKey = self::categoryConfigKeyForRecord($record);
if ($configKey === null) {
return null;
}
try {
$stored = $this->credential($configKey);
} catch (\Throwable) {
return null;
}
return $stored === '' ? null : (int) $stored;
}
/**
* Which per-family credential key applies to this record. Mosyle's
* device_type is coarser than Apple's productFamily (ios covers
* both iPhone and iPad), so the mapping splits on the hardwareModel
* prefix in addition to the device_type. mac devices split into
* laptop (MacBook*) vs. desktop (iMac / Mac mini / Mac Studio /
* Mac Pro), matching the ABM split.
*
* Returns null when the device_type is unrecognized OR when the
* model prefix doesn't match a known split, so the framework falls
* back to defaultCategoryId() rather than saving under an arbitrary
* bucket.
*/
private static function categoryConfigKeyForRecord(HostInventoryRecord $record): ?string
{
$deviceType = $record->extra['mosyle_device_type'] ?? null;
if (! is_string($deviceType)) {
return null;
}
$model = $record->hardwareModel ?? '';
if ($deviceType === 'mac') {
if ($model === '') {
return null;
}
if (str_starts_with($model, 'MacBook')) {
return 'category_id_mac_laptop';
}
foreach (['iMac', 'Mac mini', 'Mac Studio', 'Mac Pro'] as $desktopPrefix) {
if (str_starts_with($model, $desktopPrefix)) {
return 'category_id_mac_desktop';
}
}
return null;
}
if ($deviceType === 'ios') {
if ($model === '') {
return null;
}
if (str_starts_with($model, 'iPhone')) {
return 'category_id_iphone';
}
if (str_starts_with($model, 'iPad')) {
return 'category_id_ipad';
}
return null;
}
return match ($deviceType) {
'tvos' => 'category_id_appletv',
'visionos' => 'category_id_vision',
default => null,
};
}
public function extraFields(): array
{
return [
...$this->appleDbExtraFieldsDeclaration(),
// Hardware / inventory
'mosyle_battery' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_battery'],
'mosyle_total_disk' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_total_disk'],
'mosyle_available_disk' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_available_disk'],
'mosyle_bluetooth_mac' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_bluetooth_mac'],
'mosyle_ethernet_mac' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_ethernet_mac'],
'mosyle_device_type' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_device_type'],
'mosyle_build_version' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_build_version'],
// Cellular (basic). Dual-SIM imeiOne/Two, carrier labels,
// phone numbers etc. are intentionally left off per #19790
// triage. Add on request if a carrier-managed-iPhone-fleet
// customer surfaces.
'mosyle_carrier' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_carrier'],
'mosyle_imei' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_imei'],
'mosyle_meid' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_meid'],
// Security / posture
'mosyle_activation_lock_enabled' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_activation_lock_enabled', 'type' => 'boolean'],
'mosyle_device_locator_enabled' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_device_locator_enabled', 'type' => 'boolean'],
'mosyle_cloud_backup_enabled' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_cloud_backup_enabled', 'type' => 'boolean'],
'mosyle_last_cloud_backup_date' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_last_cloud_backup_date', 'type' => 'date'],
'mosyle_sip_enabled' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_sip_enabled', 'type' => 'boolean'],
'mosyle_device_attestation_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_device_attestation_status'],
// MDM / lifecycle
'mosyle_enrollment_type' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_enrollment_type'],
'mosyle_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_status'],
'mosyle_management_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_management_status'],
'mosyle_os_update_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_os_update_status'],
'mosyle_date_last_beat' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_date_last_beat', 'type' => 'date'],
'mosyle_date_last_push' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_date_last_push', 'type' => 'date'],
'mosyle_user_id' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_user_id'],
'mosyle_supervised' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_supervised', 'type' => 'boolean'],
// User / scoping
'mosyle_user_type' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_user_type'],
'mosyle_location' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_location'],
'mosyle_tags' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_tags'],
// Network
'mosyle_last_ssid' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_last_ssid'],
// Lost-mode fields. Only populated on devices currently in
// lost mode. Expect these to stay null on healthy devices.
'mosyle_lost_mode_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_lost_mode_status'],
'mosyle_latitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_latitude'],
'mosyle_longitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_longitude'],
'mosyle_altitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_altitude'],
'mosyle_device_model' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
];
}
public function pull(): iterable
{
$client = $this->makeClient();
$enrichmentEnabled = $this->appleDbEnrichmentEnabled();
$enrichmentHandled = [];
foreach ($client->devices() as $device) {
$record = $this->normalize($device);
if ($enrichmentEnabled) {
$enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
}
yield $record;
}
}
/**
* Pass the Mosyle record to the shared enrichment flow. Mosyle's
* `device_model` field holds the AppleDB-shape hardware
* identifier (sample "iPad12,1" per the Mosyle Business API
* reference) while `device_model_name` is the marketing-shape
* string used as the AssetModel name. Both Mosyle Manager and
* Mosyle Business follow this split.
*
* @param array<string, bool> $handled
* @return array<string, bool>
*/
private function enrichFromAppleDb(HostInventoryRecord $record, array $handled): array
{
$modelName = $record->hardwareModel;
if (! is_string($modelName) || $modelName === '') {
return $handled;
}
$productType = $record->extra['mosyle_device_model'] ?? null;
if (! is_string($productType) || $productType === '') {
return $handled;
}
return $this->enrichModelFromAppleDb($modelName, $productType, null, $handled);
}
/**
* Convert a Mosyle device payload into the normalized record shape.
* Mosyle's `deviceudid` is stable per enrolled device and is what
* we key asset_external_sources on.
*
* Field names here match the Mosyle Manager v2 /listdevices response
* shape (issue #19790): `username` not `usename`, `last_lan_ip` for
* the device IP (`ip_address` is not a documented field).
*
* @param array<string, mixed> $device
*/
private function normalize(array $device): HostInventoryRecord
{
$productType = Arr::get($device, 'device_model');
$modelName = Arr::get($device, 'device_model_name');
$canonical = $this->canonicalIdentityFor($productType, $modelName);
$appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);
return new HostInventoryRecord(
sourceKey: $this->name(),
sourceId: (string) Arr::get($device, 'deviceudid'),
hostname: Arr::get($device, 'device_name'),
hardwareSerial: Arr::get($device, 'serial_number'),
hardwareModel: $modelName,
manufacturer: 'Apple',
primaryMac: Arr::get($device, 'wifi_mac_address'),
primaryIp: Arr::get($device, 'last_lan_ip'),
os: Arr::get($device, 'os'),
osVersion: Arr::get($device, 'osversion'),
lastSeen: $this->parseTimestamp(Arr::get($device, 'date_info')),
assetTag: Arr::get($device, 'asset_tag'),
assignedUserEmail: Arr::get($device, 'useremail'),
assignedUserName: Arr::get($device, 'username'),
extra: [
...$appleDbExtras,
// Hardware / inventory
'mosyle_battery' => Arr::get($device, 'battery'),
'mosyle_total_disk' => Arr::get($device, 'total_disk'),
'mosyle_available_disk' => Arr::get($device, 'available_disk'),
'mosyle_bluetooth_mac' => Arr::get($device, 'bluetooth_mac_address'),
'mosyle_ethernet_mac' => Arr::get($device, 'ethernet_mac_address'),
'mosyle_device_type' => Arr::get($device, 'device_type'),
'mosyle_build_version' => Arr::get($device, 'BuildVersion'),
// Cellular
'mosyle_carrier' => Arr::get($device, 'carrier'),
'mosyle_imei' => Arr::get($device, 'imei'),
'mosyle_meid' => Arr::get($device, 'meid'),
// Security / posture
'mosyle_activation_lock_enabled' => Arr::get($device, 'isActivationLockEnabled'),
'mosyle_device_locator_enabled' => Arr::get($device, 'isDeviceLocatorServiceEnabled'),
'mosyle_cloud_backup_enabled' => Arr::get($device, 'isCloudBackupEnabled'),
'mosyle_last_cloud_backup_date' => Arr::get($device, 'LastCloudBackupDate'),
'mosyle_sip_enabled' => Arr::get($device, 'SystemIntegrityProtectionEnabled'),
'mosyle_device_attestation_status' => Arr::get($device, 'DeviceAttestationStatus'),
// MDM / lifecycle
'mosyle_enrollment_type' => Arr::get($device, 'enrollment_type'),
'mosyle_status' => Arr::get($device, 'status'),
'mosyle_management_status' => Arr::get($device, 'ManagementStatus'),
'mosyle_os_update_status' => Arr::get($device, 'OSUpdateStatus'),
'mosyle_date_last_beat' => Arr::get($device, 'date_last_beat'),
'mosyle_date_last_push' => Arr::get($device, 'date_last_push'),
'mosyle_user_id' => Arr::get($device, 'userid'),
'mosyle_supervised' => Arr::get($device, 'is_supervised'),
// User / scoping
'mosyle_user_type' => Arr::get($device, 'usertype'),
'mosyle_location' => Arr::get($device, 'location'),
'mosyle_tags' => Arr::get($device, 'tags'),
// Network
'mosyle_last_ssid' => Arr::get($device, 'last_ssid'),
// Lost-mode (only populated when the device is in lost mode)
'mosyle_lost_mode_status' => Arr::get($device, 'lostmode_status'),
'mosyle_latitude' => Arr::get($device, 'latitude'),
'mosyle_longitude' => Arr::get($device, 'longitude'),
'mosyle_altitude' => Arr::get($device, 'altitude'),
'mosyle_device_model' => $productType,
],
canonicalMarketingName: $canonical['canonicalMarketingName'],
canonicalModelNumber: $canonical['canonicalModelNumber'],
);
}
/**
* Mosyle Manager v2 mixes timestamp formats across fields and
* across tenants. Observed shapes:
* - ISO 8601 string: "2026-01-15T10:00:00.000Z"
* - Unix epoch seconds as integer or string: 1791483579
* - null or empty string on devices that have never beaten in
*
* Numeric values in the plausible Unix-time range (1e9 to 1e11,
* roughly 2001 to 5138) are treated as epoch seconds. Anything
* else goes through Carbon::parse(). Unparseable values log and
* return null rather than throwing, so one device with a bad
* date_info doesn't abort an entire sync run.
*/
private function parseTimestamp(mixed $value): ?Carbon
{
if ($value === null || $value === '') {
return null;
}
try {
if (is_numeric($value) && $value >= 1_000_000_000 && $value <= 100_000_000_000) {
return Carbon::createFromTimestampUTC((int) $value);
}
return Carbon::parse($value);
} catch (\Throwable $e) {
Log::channel('sync-adapters')->warning(
$this->name().': skipped unparseable Mosyle timestamp ('.var_export($value, true).'): '.$e->getMessage()
);
return null;
}
}
/**
* Mosyle writes use the same credential set as reads (access token
* + login) and the same JWT token flow. No tier / license gate, so
* canPush is always true for a configured instance.
*/
public function canPush(): bool
{
return true;
}
/**
* Mosyle Manager v2's push payload does not include a notes field.
* The documented writable fields on /devices elements are asset_tag,
* device_name, lock-screen message, and custom tags. Returning null
* here keeps the composed-notes push framework from calling us at
* push time. The settings-page UI section is gated separately via
* supportsComposedNotesPush() below.
*/
public function notesFieldTarget(): ?string
{
return null;
}
/**
* Mosyle Manager v2's push payload has no field that admin-composed
* notes could land in, so hide the composed-notes section on the
* adapter settings page entirely. Prevents admins from filling in a
* template that would get silently dropped at push time.
*/
public function supportsComposedNotesPush(): bool
{
return false;
}
/**
* Push Snipe-IT asset_tag back to Mosyle. Mosyle's write API is
* POST /devices with an `elements` array keyed by `serialnumber`.
* Mosyle also accepts UDID, but serial is what we cached from pull
* and is more stable across re-enrollment.
*
* @param array<int, string> $changedFields
*/
public function push(Asset $asset, array $changedFields = []): bool
{
$externalSource = $this->pushPrologue($asset, $changedFields);
if ($externalSource === null) {
return false;
}
$serial = $asset->serial;
if ($serial === null || $serial === '') {
// Mosyle keys writes by serial, not the UDID we stored as
// external_id. Fall back to external_id when the asset has
// no serial.
$serial = $externalSource->external_id;
}
if (! in_array('asset_tag', $this->pushDirectedFields(), true)) {
return false;
}
$value = $this->assetValueForSourceField($asset, 'asset_tag');
if ($value === null || $value === '') {
return false;
}
if ($this->isPushDryRun()) {
Log::channel('sync-adapters')->info(
$this->name().' push [dry-run]: would set Mosyle device serial='.$serial.' asset_tag='.$value
);
return true;
}
$this->makeClient()->updateDeviceAssetTagBySerial($serial, (string) $value);
Log::channel('sync-adapters')->info(
$this->name().' push: updated Mosyle device serial='.$serial.' fields [asset_tag]'
);
return true;
}
private function makeClient(): MosyleClient
{
return new MosyleClient(
baseUrl: $this->url(),
accessToken: $this->credential('access_token'),
email: $this->credential('email'),
password: $this->credential('password'),
);
}
}