A free open source IT asset/license management system
Added custom http adapter, updated route
snipe32f77597cce2
diff --git a/app/Http/Controllers/SettingsController.php b/app/Http/Controllers/SettingsController.phpindex 0f3c2233da..bd1123d412 100644--- a/app/Http/Controllers/SettingsController.php+++ b/app/Http/Controllers/SettingsController.php@@ -923,7 +923,7 @@ class SettingsController extends Controller->with('error', trans('admin/settings/sync_adapters.not_found', ['slug' => $requestedSlug]));}- return view('settings.adapters.index', compact(+ return view('settings.adapters', compact('adapters', 'adapterTypes', 'selected', 'companies', 'hasCompanies', 'selectedCompany',));}diff --git a/app/SyncAdapters/AdapterRegistry.php b/app/SyncAdapters/AdapterRegistry.phpindex 41d7431b2c..725d469892 100644--- a/app/SyncAdapters/AdapterRegistry.php+++ b/app/SyncAdapters/AdapterRegistry.php@@ -5,6 +5,7 @@ namespace App\SyncAdapters;use App\Models\SyncAdapterInstance;use App\SyncAdapters\Addigy\AddigyAdapter;use App\SyncAdapters\AppleBusinessManager\AppleBusinessManagerAdapter;+use App\SyncAdapters\CustomHttp\CustomHttpAdapter;use App\SyncAdapters\Fleet\FleetAdapter;use App\SyncAdapters\Intune\IntuneAdapter;use App\SyncAdapters\Jamf\JamfAdapter;@@ -39,6 +40,7 @@ class AdapterRegistry'fleet' => FleetAdapter::class,'addigy' => AddigyAdapter::class,'abm' => AppleBusinessManagerAdapter::class,+ 'custom_http' => CustomHttpAdapter::class,'intune' => IntuneAdapter::class,'jamf' => JamfAdapter::class,'jamf_school' => JamfSchoolAdapter::class,diff --git a/app/SyncAdapters/CustomHttp/CustomHttpAdapter.php b/app/SyncAdapters/CustomHttp/CustomHttpAdapter.phpnew file mode 100644index 0000000000..fe51ad65b3--- /dev/null+++ b/app/SyncAdapters/CustomHttp/CustomHttpAdapter.php@@ -0,0 +1,977 @@+<?php++namespace App\SyncAdapters\CustomHttp;++use App\Models\Asset;+use App\SyncAdapters\HostInventoryRecord;+use App\SyncAdapters\PushableAdapter;+use App\SyncAdapters\Support\ConfigurableAdapter;+use Carbon\Carbon;+use Illuminate\Support\Arr;+use Illuminate\Support\Facades\Http;+use Illuminate\Support\Facades\Log;++/**+ * User-defined pull-only HTTP adapter. The admin points it at any+ * JSON HTTP API, picks an auth shape (bearer / basic / api-key /+ * none), enters a records-array dot-path plus a per-Snipe-IT-field+ * dot-path, and optionally declares extra fields as a JSON blob. The+ * generic pull() walks the response, extracts values by dot-path,+ * and yields normalized records the framework can save.+ */+class CustomHttpAdapter extends ConfigurableAdapter implements PushableAdapter+{+ /**+ * Cap on pagination loop iterations, to keep a misconfigured+ * next-url or an infinite server response from spinning forever.+ * At the default 500-per-page + 1000 iterations that is 500k+ * records, which comfortably fits any single-tenant fleet.+ */+ private const PAGINATION_MAX_PAGES = 1000;++ /**+ * Snipe-IT MappingTargets::FIELDS entries whose canonical source+ * is a real user-editable column on the Asset (and its Model).+ * These are the fields we can meaningfully write back to a+ * vendor. Network and telemetry fields (mac, ip, os, os_version,+ * last_seen) are vendor-authoritative in Snipe-IT, so+ * they aren't in the push set.+ */+ private const PUSHABLE_STANDARD_FIELDS = ['hostname', 'serial', 'asset_tag', 'model'];++ /**+ * Pickable HostInventoryRecord fields for the field-map repeater+ * dropdown, keyed by internal name mapped to the translated UI+ * label. Resolved through the sync_adapters lang file so+ * translators pick these up alongside the framework's other field+ * labels. Adding a new HostInventoryRecord field means adding one+ * row here and one assignment in normalize().+ *+ * source_id is deliberately NOT in this list. It's required for+ * every sync run (records without a stable vendor id can't be+ * matched on subsequent pulls). It gets its own top-level text+ * input via settingsSchema() instead.+ *+ * @return array<string, string>+ */+ private static function fieldPathOptions(): array+ {+ return [+ 'hostname' => trans('admin/settings/sync_adapters.field_hostname'),+ 'serial' => trans('admin/settings/sync_adapters.field_serial'),+ 'asset_tag' => trans('admin/settings/sync_adapters.field_asset_tag'),+ 'model' => trans('admin/settings/sync_adapters.field_model'),+ 'manufacturer' => trans('admin/settings/sync_adapters.field_manufacturer'),+ 'mac' => trans('admin/settings/sync_adapters.field_mac'),+ 'ip' => trans('admin/settings/sync_adapters.field_ip'),+ 'os' => trans('admin/settings/sync_adapters.field_os'),+ 'os_version' => trans('admin/settings/sync_adapters.field_os_version'),+ 'last_seen' => trans('admin/settings/sync_adapters.field_last_seen'),+ 'assigned_user_email' => trans('admin/settings/sync_adapters.field_assigned_user_email'),+ 'assigned_user_name' => trans('admin/settings/sync_adapters.field_assigned_user_name'),+ ];+ }++ public static function typeLabel(): string+ {+ return 'Custom HTTP';+ }++ public function settingsSchema(): array+ {+ return [+ [+ 'key' => 'auth_method',+ 'label' => trans('admin/settings/sync_adapters.label_authentication_method'),+ 'type' => 'select',+ 'section' => 'auth',+ 'options' => self::authMethodOptions(),+ 'help' => trans('admin/settings/sync_adapters.custom_auth_method_help'),+ ],+ [+ 'key' => 'bearer_token',+ 'label' => trans('admin/settings/sync_adapters.label_bearer_token'),+ 'secret' => true,+ 'required' => false,+ 'section' => 'auth',+ 'help' => trans('admin/settings/sync_adapters.custom_bearer_token_help'),+ 'visible_when' => ['auth_method' => 'bearer'],+ ],+ [+ 'key' => 'basic_username',+ 'label' => trans('admin/settings/sync_adapters.label_basic_auth_username'),+ 'required' => false,+ 'section' => 'auth',+ 'help' => trans('admin/settings/sync_adapters.custom_basic_username_help'),+ 'visible_when' => ['auth_method' => 'basic'],+ ],+ [+ 'key' => 'basic_password',+ 'label' => trans('admin/settings/sync_adapters.label_basic_auth_password'),+ 'secret' => true,+ 'required' => false,+ 'section' => 'auth',+ 'help' => trans('admin/settings/sync_adapters.custom_basic_password_help'),+ 'visible_when' => ['auth_method' => 'basic'],+ ],+ [+ 'key' => 'api_key_header',+ 'label' => trans('admin/settings/sync_adapters.label_api_key_header_name'),+ 'required' => false,+ 'section' => 'auth',+ 'placeholder' => 'X-API-Key',+ 'help' => trans('admin/settings/sync_adapters.custom_api_key_header_help'),+ 'visible_when' => ['auth_method' => 'api_key'],+ ],+ [+ 'key' => 'api_key_value',+ 'label' => trans('admin/settings/sync_adapters.label_api_key_value'),+ 'secret' => true,+ 'required' => false,+ 'section' => 'auth',+ 'help' => trans('admin/settings/sync_adapters.custom_api_key_value_help'),+ 'visible_when' => ['auth_method' => 'api_key'],+ ],+ [+ 'key' => 'pull_path',+ 'label' => trans('admin/settings/sync_adapters.label_pull_endpoint_path'),+ 'required' => false,+ 'section' => 'pull',+ 'placeholder' => '/api/v1/devices',+ 'help' => trans('admin/settings/sync_adapters.custom_pull_path_help'),+ 'url_prefix' => true,+ ],+ [+ 'key' => 'records_path',+ 'label' => trans('admin/settings/sync_adapters.label_records_array_path'),+ 'required' => false,+ 'section' => 'pull',+ 'placeholder' => 'data.devices',+ 'help' => trans('admin/settings/sync_adapters.custom_records_path_help'),+ ],+ [+ 'key' => 'source_id_path',+ 'label' => trans('admin/settings/sync_adapters.label_source_id_path'),+ 'required' => true,+ 'section' => 'pull',+ 'placeholder' => 'id',+ 'help' => trans('admin/settings/sync_adapters.custom_source_id_path_help'),+ ],+ // Push spec sits directly under the pull spec because the+ // two are the same shape of thing (endpoint + auth+ // details). Leaving push_path blank makes canPush()+ // return false and the push controls hide themselves, so+ // pull-only admins never have to think about these fields.+ [+ 'key' => 'push_method',+ 'label' => trans('admin/settings/sync_adapters.label_push_http_method'),+ 'type' => 'select',+ 'section' => 'push',+ 'options' => self::pushMethodOptions(),+ 'required' => false,+ 'help' => trans('admin/settings/sync_adapters.custom_push_method_help'),+ ],+ [+ 'key' => 'push_path',+ 'label' => trans('admin/settings/sync_adapters.label_push_endpoint_path'),+ 'required' => false,+ 'section' => 'push',+ 'placeholder' => '/api/v1/devices/{external_id}',+ 'help' => trans('admin/settings/sync_adapters.custom_push_path_help'),+ 'url_prefix' => true,+ ],+ [+ 'key' => 'push_notes_target',+ 'label' => trans('admin/settings/sync_adapters.label_push_notes_target_path'),+ 'required' => false,+ 'section' => 'push',+ 'placeholder' => 'notes',+ 'help' => trans('admin/settings/sync_adapters.custom_push_notes_target_help'),+ ],+ [+ 'key' => 'pagination_style',+ 'label' => trans('admin/settings/sync_adapters.label_pagination_style'),+ 'type' => 'select',+ 'section' => 'pagination',+ 'options' => self::paginationStyleOptions(),+ 'required' => false,+ 'help' => trans('admin/settings/sync_adapters.custom_pagination_style_help'),+ ],+ [+ 'key' => 'pagination_page_size',+ 'label' => trans('admin/settings/sync_adapters.label_page_size'),+ 'required' => false,+ 'section' => 'pagination',+ 'placeholder' => '500',+ 'help' => trans('admin/settings/sync_adapters.custom_pagination_page_size_help'),+ 'visible_when' => ['pagination_style' => ['offset_limit', 'page_number']],+ ],+ [+ 'key' => 'pagination_limit_param',+ 'label' => trans('admin/settings/sync_adapters.label_limit_query_parameter'),+ 'required' => false,+ 'section' => 'pagination',+ 'placeholder' => 'limit',+ 'help' => trans('admin/settings/sync_adapters.custom_pagination_limit_param_help'),+ 'visible_when' => ['pagination_style' => ['offset_limit', 'page_number']],+ ],+ [+ 'key' => 'pagination_offset_param',+ 'label' => trans('admin/settings/sync_adapters.label_offset_query_parameter'),+ 'required' => false,+ 'section' => 'pagination',+ 'placeholder' => 'offset',+ 'help' => trans('admin/settings/sync_adapters.custom_pagination_offset_param_help'),+ 'visible_when' => ['pagination_style' => 'offset_limit'],+ ],+ [+ 'key' => 'pagination_page_param',+ 'label' => trans('admin/settings/sync_adapters.label_page_query_parameter'),+ 'required' => false,+ 'section' => 'pagination',+ 'placeholder' => 'page',+ 'help' => trans('admin/settings/sync_adapters.custom_pagination_page_param_help'),+ 'visible_when' => ['pagination_style' => 'page_number'],+ ],+ [+ 'key' => 'pagination_page_start',+ 'label' => trans('admin/settings/sync_adapters.label_first_page_number'),+ 'required' => false,+ 'section' => 'pagination',+ 'placeholder' => '1',+ 'help' => trans('admin/settings/sync_adapters.custom_pagination_page_start_help'),+ 'visible_when' => ['pagination_style' => 'page_number'],+ ],+ [+ 'key' => 'pagination_next_path',+ 'label' => trans('admin/settings/sync_adapters.label_next_page_url_path'),+ 'required' => false,+ 'section' => 'pagination',+ 'placeholder' => 'links.next',+ 'help' => trans('admin/settings/sync_adapters.custom_pagination_next_path_help'),+ 'visible_when' => ['pagination_style' => 'next_url'],+ ],+ // The field_paths widget renders in its own dedicated+ // fieldset that the shell inserts below the operational+ // checkboxes, not inside the schema-loop. No section here.+ [+ 'key' => 'field_paths',+ 'label' => trans('admin/settings/sync_adapters.custom_field_paths_label'),+ 'type' => 'field_map',+ 'required' => false,+ 'options' => self::fieldPathOptions(),+ 'help' => trans('admin/settings/sync_adapters.custom_field_paths_help'),+ ],+ [+ 'key' => 'extras_definition',+ 'label' => trans('admin/settings/sync_adapters.label_custom_extras_json'),+ 'type' => 'textarea',+ 'required' => false,+ 'section' => 'extras',+ 'placeholder' => '[{"key": "vendor_tag", "label": "Vendor Tag", "path": "tags.asset_tag"}]',+ 'help' => trans('admin/settings/sync_adapters.custom_extras_definition_help'),+ ],+ ];+ }++ /** @return array<string, string> */+ private static function authMethodOptions(): array+ {+ return [+ 'bearer' => trans('admin/settings/sync_adapters.custom_option_auth_bearer'),+ 'basic' => trans('admin/settings/sync_adapters.custom_option_auth_basic'),+ 'api_key' => trans('admin/settings/sync_adapters.custom_option_auth_api_key'),+ 'none' => trans('admin/settings/sync_adapters.custom_option_auth_none'),+ ];+ }++ /** @return array<string, string> */+ private static function pushMethodOptions(): array+ {+ return [+ 'disabled' => trans('admin/settings/sync_adapters.custom_option_push_disabled'),+ 'PATCH' => 'PATCH',+ 'PUT' => 'PUT',+ 'POST' => 'POST',+ ];+ }++ /** @return array<string, string> */+ private static function paginationStyleOptions(): array+ {+ return [+ 'none' => trans('admin/settings/sync_adapters.custom_option_pagination_none'),+ 'offset_limit' => trans('admin/settings/sync_adapters.custom_option_pagination_offset_limit'),+ 'page_number' => trans('admin/settings/sync_adapters.custom_option_pagination_page_number'),+ 'next_url' => trans('admin/settings/sync_adapters.custom_option_pagination_next_url'),+ ];+ }++ /**+ * Section titles + help copy for the credential schema. The+ * shell partial groups credential-schema entries by their+ * `section` key and renders each group inside its own <fieldset>+ * with these labels. Sections order is derived from first-+ * appearance in settingsSchema().+ */+ public function baseUrlSection(): ?string+ {+ return 'auth';+ }++ public function settingsSections(): array+ {+ return [+ 'auth' => [+ 'title' => trans('admin/settings/sync_adapters.custom_section_auth_title'),+ 'help' => trans('admin/settings/sync_adapters.custom_section_auth_help'),+ ],+ 'pull' => [+ 'title' => trans('admin/settings/sync_adapters.custom_section_pull_title'),+ 'help' => trans('admin/settings/sync_adapters.custom_section_pull_help'),+ ],+ 'pagination' => [+ 'title' => trans('admin/settings/sync_adapters.custom_section_pagination_title'),+ 'help' => trans('admin/settings/sync_adapters.custom_section_pagination_help'),+ ],+ 'extras' => [+ 'title' => trans('admin/settings/sync_adapters.custom_section_extras_title'),+ 'help' => trans('admin/settings/sync_adapters.custom_section_extras_help'),+ ],+ 'push' => [+ 'title' => trans('admin/settings/sync_adapters.custom_section_push_title'),+ 'help' => trans('admin/settings/sync_adapters.custom_section_push_help'),+ ],+ ];+ }++ /**+ * Extend the base validation rules with the Custom-Extras JSON+ * shape check. Blank passes through, malformed JSON or missing+ * key/path per entry surfaces the reason instead of silently+ * dropping every entry the way the runtime parser does.+ */+ public function validationRules(): array+ {+ $rules = parent::validationRules();+ $rules[$this->instance->slug.'_extras_definition'] = [+ 'nullable',+ 'string',+ new \App\Rules\CustomHttpExtrasJsonRule,+ ];++ return $rules;+ }++ /**+ * Admin-defined extras. Reads the extras_definition JSON blob+ * on this instance and exposes each entry as an extra field the+ * framework's mapping UI can route to a Snipe-IT custom field or+ * a native column.+ */+ public function extraFields(): array+ {+ $out = [];+ foreach ($this->extrasDefinition() as $extra) {+ $out[$extra['key']] = ['label' => $extra['label']];+ }++ return $out;+ }++ /**+ * Push is available whenever the admin picks a real HTTP verb+ * for push_method. Selecting "Disabled (pull only)" (the default+ * for fresh instances) is the opt-out and hides the push+ * controls on the settings page. Using the method as the switch+ * lets admins share the pull path for push (or leave both blank+ * to POST/PATCH the base URL itself) without accidentally+ * turning push off.+ */+ public function canPush(): bool+ {+ $method = $this->safeCredential('push_method');++ return $method !== '' && $method !== 'disabled';+ }++ /**+ * Admin-defined dot-path where composed notes should land in the+ * outgoing payload. Empty means the admin didn't wire up notes,+ * so the framework's composed-notes feature skips this instance.+ */+ public function notesFieldTarget(): ?string+ {+ $target = $this->safeCredential('push_notes_target');++ return $target === '' ? null : $target;+ }++ /**+ * Push Snipe-IT-authoritative field values to the admin's HTTP+ * endpoint. Payload is built by placing each push-directed+ * field's value at its configured dot-path via Arr::set, so the+ * same admin-defined field_* dot-paths that drove pull() also+ * drive the outgoing shape here. Fields the admin didn't+ * configure a dot-path for are silently skipped, matching the+ * pull side's "unmapped means unused" behavior.+ *+ * @param array<int, string> $changedFields+ */+ public function push(Asset $asset, array $changedFields = []): void+ {+ $externalSource = $this->pushPrologue($asset, $changedFields);+ if ($externalSource === null) {+ return;+ }++ if (! $this->canPush()) {+ return;+ }++ // Blank push_path is allowed. Combined with a non-blank base+ // URL it targets that base URL exactly, which some APIs+ // accept for record-scoped writes when the id is inside the+ // request body rather than the path.+ $pushPath = $this->safeCredential('push_path');++ $payload = [];+ $touched = [];+ $fieldPaths = $this->fieldPathMap();+ foreach ($this->pushDirectedFields() as $field) {+ if (! in_array($field, self::PUSHABLE_STANDARD_FIELDS, true)) {+ continue;+ }+ $path = $fieldPaths[$field] ?? '';+ if ($path === '') {+ continue;+ }+ $value = self::assetValueForSourceField($asset, $field);+ if ($value === null) {+ continue;+ }+ Arr::set($payload, $path, $value);+ $touched[] = $path;+ }++ $composed = $this->composeNotesForPush($asset);+ if ($composed !== '') {+ $notesTarget = $this->effectiveNotesTarget();+ if ($notesTarget !== null) {+ Arr::set($payload, $notesTarget, $composed);+ $touched[] = $notesTarget;+ }+ }++ if ($payload === []) {+ return;+ }++ $endpoint = rtrim($this->url(), '/').$this->resolvedPushPath($pushPath, (string) $externalSource->external_id);+ $method = strtoupper($this->safeCredential('push_method')) ?: 'PATCH';+ // Only real HTTP verbs get sent. Fall back to PATCH for+ // 'disabled' (shouldn't reach here because canPush() bails+ // upstream) or any unrecognized value.+ if (! in_array($method, ['PATCH', 'PUT', 'POST'], true)) {+ $method = 'PATCH';+ }++ if ($this->isPushDryRun()) {+ Log::channel('sync-adapters')->info(sprintf(+ '%s push [dry-run]: would %s %s with %s',+ $this->name(),+ $method,+ $endpoint,+ json_encode($payload, JSON_UNESCAPED_SLASHES),+ ));++ return;+ }++ $request = Http::acceptJson()->timeout(30);+ $request = $this->applyAuth($request);++ try {+ $request->send($method, $endpoint, ['json' => $payload])->throw();+ } catch (\Throwable $e) {+ Log::channel('sync-adapters')->warning(sprintf(+ '%s push failed: %s %s: %s',+ $this->name(),+ $method,+ $endpoint,+ $e->getMessage(),+ ));++ return;+ }++ Log::channel('sync-adapters')->info(sprintf(+ '%s push: %s %s wrote paths [%s]',+ $this->name(),+ $method,+ $endpoint,+ implode(', ', $touched),+ ));+ }++ /**+ * Substitute the {external_id} placeholder in the admin's push+ * path template. Kept as an explicit method so unit tests can+ * verify the substitution shape independent of the HTTP round+ * trip.+ */+ private function resolvedPushPath(string $template, string $externalId): string+ {+ if ($template === '') {+ // Blank template means "hit the Base URL directly." Return+ // an empty string so the endpoint assembly below just uses+ // rtrim($this->url(), '/'). Prepending '/' would add a+ // trailing slash the vendor may or may not accept.+ return '';+ }+ $path = str_replace('{external_id}', rawurlencode($externalId), $template);+ if (! str_starts_with($path, '/')) {+ $path = '/'.$path;+ }++ return $path;+ }++ /**+ * Snipe-IT's canonical source for each push-directed standard+ * field. Only the columns Snipe-IT owns authoritatively+ * (hostname, serial, asset_tag, model) are pushable, so this+ * returns null for anything else and the caller drops it from+ * the payload.+ */+ private static function assetValueForSourceField(Asset $asset, string $field): mixed+ {+ return match ($field) {+ 'hostname' => $asset->name,+ 'serial' => $asset->serial,+ 'asset_tag' => $asset->asset_tag,+ 'model' => $asset->model?->name,+ default => null,+ };+ }++ public function pull(): iterable+ {+ $fieldPaths = $this->fieldPathMap();+ $extras = $this->extrasDefinition();++ if ($fieldPaths['source_id'] === '') {+ // Without a source_id path the framework can't key records+ // back to their vendor row, so upserts collapse and every+ // sync pass overwrites the last one. Abort with a clear+ // log line instead of yielding un-keyed records.+ Log::channel('sync-adapters')->warning(sprintf(+ '%s pull aborted: Source ID Path is required. Set the "Source ID Path" input above Vendor Response Paths to the dot-path of your vendor\'s unique record id.',+ $this->name(),+ ));++ return;+ }++ $recordsPath = $this->safeCredential('records_path');+ $paginationStyle = $this->safeCredential('pagination_style') ?: 'none';+ $pageSize = max(1, (int) ($this->safeCredential('pagination_page_size') ?: 500));+ $limitParam = $this->safeCredential('pagination_limit_param') ?: 'limit';+ $offsetParam = $this->safeCredential('pagination_offset_param') ?: 'offset';+ $pageParam = $this->safeCredential('pagination_page_param') ?: 'page';+ // Explicit null/empty check because "0" is a valid pageStart+ // (zero-based APIs) but "0" ?: 1 would coerce to 1.+ $pageStartRaw = $this->safeCredential('pagination_page_start');+ $pageStart = $pageStartRaw === '' ? 1 : (int) $pageStartRaw;+ $nextPath = $this->safeCredential('pagination_next_path');++ $offset = 0;+ $pageNumber = $pageStart;+ $nextUrl = null;+ $pageIndex = 0;+ $globalIndex = 0;++ while ($pageIndex < self::PAGINATION_MAX_PAGES) {+ // Offset-limit style keeps re-hitting the same pull_path with+ // increasing offsets. Page-number style does the same with+ // an incrementing page counter (1-based by default, though+ // pagination_page_start lets 0-based APIs opt in). next-url+ // style follows the URL the previous response handed back.+ // First iteration of every style starts on the configured+ // pull_path.+ if ($paginationStyle === 'offset_limit') {+ $body = $this->fetchResponseBody(null, [$limitParam => $pageSize, $offsetParam => $offset]);+ } elseif ($paginationStyle === 'page_number') {+ $body = $this->fetchResponseBody(null, [$limitParam => $pageSize, $pageParam => $pageNumber]);+ } else {+ $body = $this->fetchResponseBody($nextUrl, []);+ }+ if ($body === null) {+ return;+ }++ $records = self::dotPathGet($body, $recordsPath);+ if (! is_array($records)) {+ Log::channel('sync-adapters')->warning(sprintf(+ '%s pull expected an array at records path "%s", got %s',+ $this->name(),+ $recordsPath,+ get_debug_type($records),+ ));++ return;+ }++ foreach ($records as $index => $record) {+ if (! is_array($record)) {+ $globalIndex++;++ continue;+ }+ $normalized = $this->normalize($record, $fieldPaths, $extras);+ if ($normalized === null) {+ Log::channel('sync-adapters')->info(sprintf(+ '%s pull skipped record at index %s: source_id path "%s" did not resolve to a scalar value',+ $this->name(),+ $globalIndex,+ $fieldPaths['source_id'],+ ));+ $globalIndex++;++ continue;+ }+ yield $normalized;+ $globalIndex++;+ }++ $pageIndex++;++ // Terminate: none = single page. offset_limit = last page+ // seen (fewer records than page_size). next_url = the+ // response body no longer contains a next-page URL.+ if ($paginationStyle === 'none') {+ return;+ }+ if ($paginationStyle === 'offset_limit') {+ if (count($records) < $pageSize) {+ return;+ }+ $offset += $pageSize;++ continue;+ }+ if ($paginationStyle === 'page_number') {+ if (count($records) < $pageSize) {+ return;+ }+ $pageNumber++;++ continue;+ }+ if ($paginationStyle === 'next_url') {+ $nextUrl = self::stringOrNull(self::dotPathGet($body, $nextPath));+ if ($nextUrl === null || $nextUrl === '') {+ return;+ }++ continue;+ }++ // Unknown style. Rare (validation should have caught it),+ // but fall through so the loop can't spin forever.+ return;+ }++ Log::channel('sync-adapters')->warning(sprintf(+ '%s pull halted after hitting the %d-page safety cap. Check your pagination configuration.',+ $this->name(),+ self::PAGINATION_MAX_PAGES,+ ));+ }++ /**+ * Issue the configured HTTP GET and return the decoded body.+ * Any auth-misconfiguration, network, or non-2xx response fails+ * soft: log a warning on the sync-adapters channel and return+ * null so the caller yields nothing rather than crashing the+ * sync run.+ *+ * $overrideUrl is used by next-url pagination to follow the+ * absolute URL the previous page returned rather than rebuilding+ * from base + pull_path. $queryParams is used by offset-limit+ * pagination to append pagination parameters to the standard+ * pull_path each iteration.+ *+ * @param array<string, mixed> $queryParams+ */+ private function fetchResponseBody(?string $overrideUrl = null, array $queryParams = []): mixed+ {+ if ($overrideUrl !== null) {+ $endpoint = $overrideUrl;+ } else {+ $baseUrl = rtrim($this->url(), '/');+ if ($baseUrl === '') {+ Log::channel('sync-adapters')->warning(sprintf(+ '%s pull aborted: base URL is empty',+ $this->name(),+ ));++ return null;+ }++ $pullPath = $this->safeCredential('pull_path');+ if ($pullPath !== '' && ! str_starts_with($pullPath, '/')) {+ $pullPath = '/'.$pullPath;+ }+ $endpoint = $baseUrl.$pullPath;+ }++ $request = Http::acceptJson()->timeout(30);+ $request = $this->applyAuth($request);++ try {+ $response = $request->get($endpoint, $queryParams)->throw();+ } catch (\Throwable $e) {+ Log::channel('sync-adapters')->warning(sprintf(+ '%s pull request failed: %s',+ $this->name(),+ $e->getMessage(),+ ));++ return null;+ }++ return $response->json();+ }++ /**+ * Attach the configured auth shape to the pending request.+ * Silent no-op on 'none' (or an unrecognized method), so a+ * misconfiguration surfaces as a 401 from the vendor rather than+ * a runtime error inside the adapter.+ */+ private function applyAuth(\Illuminate\Http\Client\PendingRequest $request): \Illuminate\Http\Client\PendingRequest+ {+ $method = $this->safeCredential('auth_method');++ return match ($method) {+ 'bearer' => $request->withToken($this->safeCredential('bearer_token')),+ 'basic' => $request->withBasicAuth(+ $this->safeCredential('basic_username'),+ $this->safeCredential('basic_password'),+ ),+ 'api_key' => $request->withHeaders([+ ($this->safeCredential('api_key_header') ?: 'X-API-Key') => $this->safeCredential('api_key_value'),+ ]),+ default => $request,+ };+ }++ /**+ * Turn one raw record from the vendor's payload into a+ * HostInventoryRecord. Every value walks through dotPathGet, so+ * missing keys just leave the corresponding field null and the+ * framework's normal null-guarding downstream handles the rest.+ *+ * @param array<string, mixed> $record+ * @param array<string, string> $fieldPaths+ * @param array<int, array{key: string, label: string, path: string}> $extras+ */+ private function normalize(array $record, array $fieldPaths, array $extras): ?HostInventoryRecord+ {+ // stringOrNull returns null for arrays / objects, so a+ // vendor payload that unexpectedly nests something at the+ // source_id path (or that returned the whole record because+ // the path was blank) yields null instead of a fatal (string)+ // cast on an array. Caller skips the record.+ $sourceId = self::stringOrNull(self::dotPathGet($record, $fieldPaths['source_id']));+ if ($sourceId === null || $sourceId === '') {+ return null;+ }++ $lastSeen = null;+ $lastSeenRaw = self::dotPathGet($record, $fieldPaths['last_seen']);+ if (is_string($lastSeenRaw) && $lastSeenRaw !== '') {+ try {+ $lastSeen = Carbon::parse($lastSeenRaw);+ } catch (\Throwable) {+ // Malformed date string, leave null rather than throw.+ }+ }++ $extraValues = [];+ foreach ($extras as $extra) {+ $raw = self::dotPathGet($record, $extra['path']);+ // Decode HTML entities on scalar extras for the same+ // reason we do it on standard fields above. Non-scalar+ // values pass through unchanged so downstream code (the+ // framework's mapping layer) can still stringify them.+ $extraValues[$extra['key']] = is_scalar($raw)+ ? html_entity_decode((string) $raw, ENT_QUOTES | ENT_HTML5, 'UTF-8')+ : $raw;+ }++ return new HostInventoryRecord(+ sourceKey: $this->name(),+ sourceId: $sourceId,+ hostname: self::stringOrNull(self::dotPathGet($record, $fieldPaths['hostname'])),+ hardwareSerial: self::stringOrNull(self::dotPathGet($record, $fieldPaths['serial'])),+ hardwareModel: self::stringOrNull(self::dotPathGet($record, $fieldPaths['model'])),+ manufacturer: self::stringOrNull(self::dotPathGet($record, $fieldPaths['manufacturer'])),+ primaryMac: self::stringOrNull(self::dotPathGet($record, $fieldPaths['mac'])),+ primaryIp: self::stringOrNull(self::dotPathGet($record, $fieldPaths['ip'])),+ os: self::stringOrNull(self::dotPathGet($record, $fieldPaths['os'])),+ osVersion: self::stringOrNull(self::dotPathGet($record, $fieldPaths['os_version'])),+ lastSeen: $lastSeen,+ assetTag: self::stringOrNull(self::dotPathGet($record, $fieldPaths['asset_tag'])),+ assignedUserEmail: self::stringOrNull(self::dotPathGet($record, $fieldPaths['assigned_user_email'])),+ assignedUserName: self::stringOrNull(self::dotPathGet($record, $fieldPaths['assigned_user_name'])),+ extra: $extraValues,+ );+ }++ /**+ * Walk a dot-separated path into a nested array structure. Empty+ * path returns the input unchanged, so an admin using the whole+ * response body as the records array can leave records_path+ * blank. Numeric segments (like "data.0.serial") index into+ * sequential arrays too, so an API that returns a list at the+ * root plus a wrapper object further down is representable.+ */+ private static function dotPathGet(mixed $data, string $path): mixed+ {+ if ($path === '') {+ return $data;+ }++ $current = $data;+ foreach (explode('.', $path) as $segment) {+ if (! is_array($current)) {+ return null;+ }+ if (array_key_exists($segment, $current)) {+ $current = $current[$segment];++ continue;+ }+ if (ctype_digit($segment) && array_key_exists((int) $segment, $current)) {+ $current = $current[(int) $segment];++ continue;+ }++ return null;+ }++ return $current;+ }++ private static function stringOrNull(mixed $value): ?string+ {+ if ($value === null) {+ return null;+ }+ if (! is_scalar($value)) {+ return null;+ }++ // Decode HTML entities before storing. Some APIs+ // (Snipe-IT's own /api/v1/hardware is one of them) run their+ // JSON string values through htmlspecialchars() in the+ // transformer, so a model name like `MacBook Pro 13"` shows+ // up on the wire as `MacBook Pro 13"`. Without decoding+ // we would round-trip the entity into the asset table and it+ // would display as literal text on the asset page. Decode is+ // idempotent for well-behaved APIs that never HTML-escape,+ // so this is safe as a default.+ return html_entity_decode((string) $value, ENT_QUOTES | ENT_HTML5, 'UTF-8');+ }++ /**+ * Wrapper around credential() that returns '' rather than+ * throwing when the key isn't stored yet. The base credential()+ * throws on missing values because most adapters treat that as+ * misconfiguration. Custom is more forgiving: half-configured+ * instances just yield empty fields on unmapped paths.+ */+ private function safeCredential(string $key): string+ {+ try {+ return (string) $this->credential($key);+ } catch (\Throwable) {+ return '';+ }+ }++ /**+ * Decode the field_paths JSON blob into a {snipe_field: path}+ * map, keyed by every option in fieldPathOptions() plus the+ * standalone source_id_path credential. Missing fields default+ * to '' so callers can `$map[$field] ?? ''` without an isset+ * guard. Malformed / empty storage returns the all-blank+ * baseline (with source_id populated from its own field when+ * set).+ *+ * @return array<string, string>+ */+ private function fieldPathMap(): array+ {+ $baseline = array_fill_keys(array_keys(self::fieldPathOptions()), '');+ // source_id lives outside the repeater as its own required+ // input, so merge it in here to give callers a uniform+ // $map['source_id'] lookup.+ $baseline['source_id'] = $this->safeCredential('source_id_path');++ $raw = $this->safeCredential('field_paths');+ if (trim($raw) === '') {+ return $baseline;+ }++ $decoded = json_decode($raw, true);+ if (! is_array($decoded)) {+ return $baseline;+ }++ foreach ($decoded as $key => $value) {+ if (is_string($key) && array_key_exists($key, $baseline) && is_string($value)) {+ $baseline[$key] = $value;+ }+ }++ return $baseline;+ }++ /**+ * Parse the extras JSON blob into a validated list. Non-array+ * entries and entries missing key/path are dropped silently so a+ * partially-malformed blob still yields the rest.+ *+ * @return array<int, array{key: string, label: string, path: string}>+ */+ private function extrasDefinition(): array+ {+ $raw = $this->safeCredential('extras_definition');+ if (trim($raw) === '') {+ return [];+ }++ $decoded = json_decode($raw, true);+ if (! is_array($decoded)) {+ return [];+ }++ $out = [];+ foreach ($decoded as $entry) {+ if (! is_array($entry) || ! isset($entry['key'], $entry['path'])) {+ continue;+ }+ $out[] = [+ 'key' => (string) $entry['key'],+ 'label' => (string) ($entry['label'] ?? $entry['key']),+ 'path' => (string) $entry['path'],+ ];+ }++ return $out;+ }+}diff --git a/app/SyncAdapters/SyncHostFromAdapter.php b/app/SyncAdapters/SyncHostFromAdapter.phpindex eb2f0aa9c0..df95f419c0 100644--- a/app/SyncAdapters/SyncHostFromAdapter.php+++ b/app/SyncAdapters/SyncHostFromAdapter.php@@ -466,7 +466,22 @@ class SyncHostFromAdapter$asset->status_id = self::resolveStatusId($instance);$asset->asset_tag = self::resolveAssetTag($record, $instance);$asset->company_id = self::resolveCompanyId($record, $instance);- $asset->save();+ // Asset uses ValidatingTrait, so save() returns false on+ // validation failure without throwing. Without this guard the+ // caller then wrote asset_external_sources with asset_id=null+ // and only surfaced the FK violation, hiding the real cause+ // (e.g. model_id is null because the adapter's model mapping+ // points at a field the vendor didn't return, or asset_tag+ // collided with an existing row). Raise the validation errors+ // so the sync loop's catch block logs the actionable message.+ if (! $asset->save()) {+ throw new RuntimeException(sprintf(+ 'could not save asset for %s record %s: %s',+ $record->sourceKey,+ $record->sourceId,+ implode('; ', $asset->getErrors()->all()) ?: 'unknown validation failure',+ ));+ }return $asset;}@@ -569,6 +584,20 @@ class SyncHostFromAdapter* {model} {source}. Extras (e.g. {extra.kandji_asset_tag}) can be* added later without touching callers.*/+ /**+ * Recognized placeholder tokens for asset_tag_pattern. Kept as a+ * public constant so the validation rule (AssetTagPatternRule)+ * can reference the same list without drifting from the+ * substitution logic below.+ */+ public const ASSET_TAG_PATTERN_PLACEHOLDERS = [+ '{serial}',+ '{external_id}',+ '{hostname}',+ '{model}',+ '{source}',+ ];+private static function renderAssetTagPattern(string $pattern, HostInventoryRecord $record): ?string{$substitutions = [