Skip to content

A free open source IT asset/license management system

9.7 KB
Raw Blame
<?php

namespace App\SyncAdapters;

use App\Models\CustomField;

/**
 * Enumerates the target options each normalized host-inventory field can
 * be mapped to. Every adapter reads the same normalized shape (hostname,
 * serial, model, mac, ip, os, os_version, last_seen) and hands it to
 * SyncAdapter. per-instance overrides let admins redirect each
 * field to a different Snipe-IT destination (native column, side table,
 * custom field, or skip).
 *
 * Target encoding is `<type>:<id>` so the value stays compact and
 * self-describing when stored in the instance config blob:
 *   - skip                      -> don't write this field
 *   - native:name               -> asset.name
 *   - native:serial             -> asset.serial
 *   - native:model              -> AssetModel (auto-created if missing)
 *   - external:mac              -> asset_external_sources.primary_mac
 *   - external:ip               -> asset_external_sources.primary_ip
 *   - external:os               -> asset_external_sources.os
 *   - external:os_version       -> asset_external_sources.os_version
 *   - external:last_seen        -> asset_external_sources.last_seen
 *   - custom:{id}               -> assets._snipeit_<db_column>_<id>
 */
class MappingTargets
{
    /** Every normalized field the sync pipeline knows about. */
    public const FIELDS = [
        'hostname',
        'serial',
        'asset_tag',
        'model', 'mac',
        'ip', 'os',
        'os_version',
        'last_seen',
    ];

    /**
     * The shipped default target for a field (before any per-instance
     * override). Used by SyncAdapter as the fallback.
     */
    public static function defaultTarget(string $field): string
    {
        return match ($field) {
            'hostname' => 'native:name',
            'serial' => 'native:serial',
            'model' => 'native:model',
            'mac' => 'external:mac',
            'ip' => 'external:ip',
            'os' => 'external:os',
            'os_version' => 'external:os_version',
            'last_seen' => 'external:last_seen',
            // Vendor-side asset tag mapping to Snipe-IT's asset_tag
            // column is the useful default. writeNative()'s
            // "only overwrite when vendor sent a non-empty tag" guard
            // means admin-curated tags survive vendor payloads that
            // happen to omit the field.
            'asset_tag' => 'native:asset_tag',
            default => 'skip',
        };
    }

    /**
     * Dropdown options for a given normalized field, keyed by target
     * encoding and valued by human-readable label. Custom fields whose
     * element type doesn't fit the normalized field's value shape are
     * filtered out.
     *
     * @return array<string, string>
     */
    public static function options(string $field): array
    {
        $options = ['skip' => trans('admin/settings/sync_adapters.target_skip')];

        $default = self::defaultTarget($field);
        if ($default !== 'skip') {
            $options[$default] = self::labelFor($default).' '.trans('admin/settings/sync_adapters.target_default_suffix');
        }

        foreach (self::compatibleCustomFields($field) as $customField) {
            $options['custom:'.$customField->id] = trans('admin/settings/sync_adapters.target_custom_prefix').': '.$customField->name;
        }

        return $options;
    }

    /**
     * Human-readable label for a stored target value, used when
     * rendering the current selection outside a dropdown context.
     */
    public static function labelFor(string $target): string
    {
        if ($target === 'skip') {
            return trans('admin/settings/sync_adapters.target_skip');
        }

        [$type, $id] = array_pad(explode(':', $target, 2), 2, '');

        return match ($type) {
            'native' => match ($id) {
                'purchase_date', 'order_number' => trans('general.' . $id),
                'model_number' => trans('general.model_no'),
                'eol_date' => trans('admin/hardware/form.eol_date'),
                default => trans('admin/settings/sync_adapters.target_native_' . $id),
            },
            'external' => trans('admin/settings/sync_adapters.target_external_'.$id),
            'custom' => trans('admin/settings/sync_adapters.target_custom_prefix').': '
                .(CustomField::find((int) $id)?->name ?? '?'),
            default => $target,
        };
    }

    /**
     * Dropdown options for an adapter-specific extra field. Extras
     * can only be routed to a custom field or skipped. `type` filters
     * the custom-field target pool: 'text' offers text/textarea/
     * markdown-textarea fields, 'boolean' offers checkbox fields.
     *
     * `$adminDefined` narrows the target pool to skip + custom-only
     * for tenant-defined vendor extras (Kaseya VSA 10 custom fields,
     * ServiceNow variables, etc). Those hold arbitrary admin-labeled
     * key/value data and never make sense as a Snipe-IT native
     * column, so we don't show the native branch at all. Adapter-
     * declared extras (fleet_labels, kandji_blueprint_id) still get
     * native:asset_tag / native:notes as options because a real
     * admin use-case exists for routing labels/blueprints to those
     * slots.
     *
     * @return array<string, string>
     */
    public static function optionsForExtra(string $type = 'text', bool $adminDefined = false): array
    {
        $options = [];

        // Target pool is scoped by extra type so a non-date vendor
        // value can't be routed into a Snipe-IT date column.
        // text natives:
        //   asset_tag, model, model_number, notes, order_number.
        //   model_number updates the resolved AssetModel. model lands
        //   on AssetModel.name via resolveModelIdByName.
        //
        // date natives:
        //   purchase_date, eol_date. eol_date sets eol_explicit so
        //   the derived "purchase_date + model.eol" default yields
        //   to the sync-sourced value.
        //
        // boolean native: byod.
        //
        // Admin-defined extras stay custom-only across every type
        // because arbitrary tenant-labeled data doesn't carry a
        // semantic that maps to native asset columns.
        if (!$adminDefined) {
            if ($type === 'boolean') {
                $options['native:byod'] = self::labelFor('native:byod');
            } else {
                if ($type === 'date') {
                    foreach (['purchase_date', 'eol_date'] as $nativeColumn) {
                        $options['native:' . $nativeColumn] = self::labelFor('native:' . $nativeColumn);
                    }
                }
                foreach (['asset_tag', 'model', 'model_number', 'notes', 'order_number'] as $nativeColumn) {
                    $options['native:' . $nativeColumn] = self::labelFor('native:' . $nativeColumn);
                }
            }
        }

        // Date extras can also land in text custom fields (ISO date
        // strings are text-shaped), so merge the two pools for the
        // date type. Boolean stays checkbox-only.
        $customFields = match ($type) {
            'boolean' => self::checkboxCustomFields(),
            'date' => self::dateLikeCustomFields()->concat(self::textLikeCustomFields())->unique('id')->sortBy('name')->values(),
            default => self::textLikeCustomFields(),
        };

        foreach ($customFields as $customField) {
            $options['custom:'.$customField->id] = trans('admin/settings/sync_adapters.target_custom_prefix').': '.$customField->name;
        }

        return $options;
    }

    /**
     * Custom fields whose element type can plausibly hold this
     * normalized field's value. For MVP: text/textarea for any string,
     * date_picker/datetime_picker for last_seen. Extend as we hit
     * real-world requests.
     *
     * @return \Illuminate\Support\Collection<int, CustomField>
     */
    private static function compatibleCustomFields(string $field): \Illuminate\Support\Collection
    {
        $textLike = ['text', 'textarea', 'markdown-textarea'];
        $dateLike = ['date_picker', 'datetime_picker'];

        $accepted = match ($field) {
            'last_seen' => $dateLike,
            default => $textLike,
        };

        return CustomField::query()
            ->whereIn('element', $accepted)
            ->orderBy('name')
            ->get();
    }

    /**
     * Text-like custom fields, used as the target pool for extras.
     * Extras are stringified before write so any text-like field can
     * hold whatever the vendor emits.
     *
     * @return \Illuminate\Support\Collection<int, CustomField>
     */
    private static function textLikeCustomFields(): \Illuminate\Support\Collection
    {
        return CustomField::query()
            ->whereIn('element', ['text', 'textarea', 'markdown-textarea'])
            ->orderBy('name')
            ->get();
    }

    /**
     * Checkbox-style custom fields, used as the target pool for
     * boolean-typed extras (mdm_enabled, supervised, adopted, etc).
     *
     * @return \Illuminate\Support\Collection<int, CustomField>
     */
    private static function checkboxCustomFields(): \Illuminate\Support\Collection
    {
        return CustomField::query()
            ->where('element', 'checkbox')
            ->orderBy('name')
            ->get();
    }

    /**
     * Date-shaped custom fields, used as the target pool for date-
     * typed extras (AppleCare end date, enrollment time, management-
     * certificate expiration, etc).
     *
     * @return \Illuminate\Support\Collection<int, CustomField>
     */
    private static function dateLikeCustomFields(): \Illuminate\Support\Collection
    {
        return CustomField::query()
            ->whereIn('element', ['date_picker', 'datetime_picker'])
            ->orderBy('name')
            ->get();
    }
}