Skip to main content
Official Document Center

Document Center.

contains core instructions, deployment parameters and FAQs for EasyOps and Asset Sonar.

Project A

EasyOps Documentation

Knowledge Base

Full stack operation and maintenance knowledge base

Key points:supports offline retrieval and classified browsing, adapting to network-free computer room scenarios.

Network Engineering

Huawei/H3C/Cisco command quick check, OSPF/STP troubleshooting.

Weak current security

IPC debugging, access control wiring diagram, monitoring black screen and PTZ fault location.

Desktop operation and maintenance

Windows troubleshooting, printer sharing issues, DNS/IP repair.

Linux/server

Shell common commands, RAID maintenance, firewall configuration and reinforcement.

Cloud native

Docker/K8s common commands, Pod exception diagnosis and deployment quick check.

database

MySQL / Redis operation and maintenance manual, slow query and backup and recovery guide.

Toolbox

Engineering Toolbox

Key points:on-site high-frequency capabilities are hierarchically organized according to "calculation + diagnosis + query + operation and maintenance" to facilitate rapid positioning of tools.

Security Storage

NVR hard drive capacity estimate

subnet mask

IP Range and Broadcast Computing

PoE power consumption

Terminal power supply budget

Fiber attenuation

Link dB loss estimation

network diagnosis

TCP Ping / Port Scan / LAN Scan

Network Operation and Maintenance Center

HTTP Detection/WOL/Tool Aggregation

Network Query Center

DNS / Whois(RDAP) / OUI

SSH tool

connection management/status polling/quick command

first initialization instructions

Key points:needs to be connected to the Internet for the first time to download about 15MB of core data. It can be used offline after the initialization is completed.
local priority:Knowledge base, collections, history, and scan results are stored locally on the device by default, and core data is not uploaded.
secure storage:Sensitive configuration items are saved using system security capabilities (such as Keychain) to avoid clear text exposure.
Project Divider

Project B

Asset Sonar Documentation

Deployment and Configuration

Copy the managed package to the enterprise USB drive, configure Snipe-IT once, and run the endpoint workflow directly from the USB drive.

Important reminder

Asset Sonar uses a managed portable delivery model. Before deployment, verify the Snipe-IT connection, account permissions and field mappings.

01Environmental requirements

  • Windows 7 SP1, Windows 10 or Windows 11; x86 and x64 are supported
  • No separate .NET Desktop Runtime installation is required; the portable package contains the compatible runtimes
  • Run as administrator to read complete hardware and system information
  • Snipe-IT API Key (with at least asset read and write, component/accessory association permissions)
  • The client is reachable from the Snipe-IT network (allowed by HTTP/HTTPS and reverse proxy policies)

02profiles.json example (multiple environments)

{
  "Profiles": [
    {
      "Name": "Production",
      "ApiUrl": "http://snipeit.company.local/api/v1",
      "ApiKey": "YOUR_PROD_API_KEY",
      "TagPrefix": "AS-",
      "EnableComponents": true,
      "EnableAccessories": true,
      "Location": "HQ",
      "Company": "JianXiu Tech"
    },
    {
      "Name": "Lab",
      "ApiUrl": "http://snipeit-lab.local/api/v1",
      "ApiKey": "YOUR_LAB_API_KEY",
      "TagPrefix": "LAB-",
      "EnableComponents": false,
      "EnableAccessories": false,
      "Location": "LAB",
      "Company": "JianXiu Tech"
    }
  ]
}

It is recommended that the API Key be handed over to the system security mechanism for safekeeping and not be stored in plain text on a shared machine for a long time.

02.1accessories/components/model configuration reference

is used to unify the mapping naming of "components, accessories, and models" in Snipe-IT to avoid association failures or duplicate creation during synchronization.

{
  "ActiveProfile": "默认",
  "Profiles": {
    "默认": {
      "InternalUrl": null,
      "ExternalUrl": null,
      "ApiKey": null,
      "Department": null,
      "AssignName": null,
      "AssignUser": null,
      "AssignPassword": null,
      "EmailSuffix": "example.com",
      "ASSET_TAG_PREFIX": "DOZ",
      "CATEGORY_ID_MAP": {
        "笔记本电脑": 4,
        "台式机": 3,
        "显示器": 5
      },
      "COMPONENT_CATEGORY_ID_MAP": {
        "处理器": 7,
        "内存": 9,
        "硬盘": 10
      },
      "ACCESSORY_CATEGORY_ID_MAP": {
        "键盘": 15,
        "鼠标": 16
      },
      "CATEGORY_CODE_MAP": {
        "笔记本电脑": "BJB",
        "台式机": "TSJ"
      }
    }
  }
}
  • It is recommended to pre-build the target in Snipe-IT first Model、Component、Accessory, do batch synchronization again.
  • The naming should be kept unique and stable to avoid synonyms causing duplicate objects (such as 16G / 16GB）。
  • is launched for the first time, it is recommended to sample 10 units to verify the mapping before expanding the batch.

03Recommended operating procedures (production environment)

  1. preparation stage (before going online)
    • Confirm that the currently selected Production Profile to avoid mistakenly writing the test environment.
    • Verification ApiUrl、ApiKey, component/accessory switches are consistent with the scope of this inventory.
    • First use a prototype machine to verify connectivity (can scan, synchronize, and write back key fields).
  2. scanning stage (first local, then synchronized)
    • performs a local scan, focusing on checking whether the serial number, model number, and asset tag are complete.
    • Fill in or mark null value fields first to avoid directly synchronizing dirty data to the asset library.
    • It is recommended to build tasks in batches according to departments/floors (for example, 30~50 units per batch).
  3. verification stage (sampling verification)
    • Sampling 3~5 units per batch, checking the mapping of asset tags, serial numbers, models, and location fields.
    • Confirms that the behavior of "Asset update exists/Asset new does not exist" is as expected.
    • If fields are found to be misaligned, correct the mapping configuration before continuing with subsequent batches.
  4. Synchronization stage (grayscale advancement)
    • synchronize in small batches first (10~20 units are recommended for the first batch), and observe the error code and failure rate.
    • Expand the batch after confirming it is stable to avoid rollback pressure caused by a one-time full import.
    • Export a snapshot (CSV/PDF) immediately after each batch is completed and record the batch number.
  5. exception handling stage (stop loss first)
    • When a large-scale failure occurs, subsequent batches will be suspended and no full rerun will be performed.
    • is processed according to error code groups (401/403 permission, 404 path, 409 conflict, 422 field).
    • is repaired, only failed objects are retried, and successful objects are not written repeatedly.
  6. Closing stage (archiving and review)
    • archives "scan snapshot + synchronization results + exception list + operation log".
    • Record the configuration changes and problem handling conclusions, and update the team SOP.

04filtering and denoising suggestions

"IGNORE_KEYWORDS": [
  "VMware", "Virtual", "Hyper-V", "Loopback", "Bluetooth",
  "WAN Miniport", "Teredo", "Docker", "vEthernet"
]

is used to filter virtual network cards, tunnel adapters and temporary interfaces to reduce invalid asset noise.

05Export and Archiving Suggestions

  • It is recommended to export CSV + PDF at the same time during the inventory stage to facilitate system reconciliation and manual signature retention.
  • naming suggestions:site-dept-date-batch, for example hq-it-2026-04-08-b01。
  • Put "scan snapshot + synchronization results + exception list" into the same archive directory to facilitate audit review.

Frequently Asked Questions and Troubleshooting

It is recommended to read "Phenomena → Cause → Treatment Steps" first, and troubleshoot in order to quickly locate the problem.

1) The serial number cannot be scanned or the model number is empty?
Common reasons: insufficient permissions, abnormal WMI service, and missing device BIOS information.
  • Run Asset Sonar as administrator.
  • Check whether the WMI service (Winmgmt) is normal.
  • Confirm in BIOS/UEFI that the serial number field is not cleared.
2) Unable to connect Snipe-IT (401/403/404)?
First confirm that the API address contains /api/v1, check the Key and permissions again.
  • 401: API Key is incorrect or expired.
  • 403: Insufficient Key permissions (no write/association permissions).
  • 404: Path error, reverse proxy does not forward API route.
3) Duplicate assets appear after synchronization?
duplication usually comes from "serial number inconsistency" or "historical dirty data".
  • Prioritize "serial number + asset tag" as the primary key strategy.
  • Manually fill in historical empty serial number assets or mark them for archiving.
  • First run a batch in the test environment to confirm the duplication strategy before launching it into production.
4) Component/accessory association failed?
is more common when the target object does not exist or the ID mapping fails.
  • Confirm that the target components and accessories exist in Snipe-IT and can be allocated.
  • Check whether it is enabled in profiles EnableComponents / EnableAccessories。
  • Check the object name and ID in the failure log, correct the mapping and try again.
5) The scanning speed is slow or the UI is stuck?
recommends reducing concurrency, narrowing the scan scope, and filtering virtual devices.
  • First perform hardware main field collection, and then perform extended field supplementary scanning.
  • Exclude virtual network cards and invalid interfaces to reduce noise.
  • Execute large batch inventory in batches (by department/floor).
6) Is the exported file garbled or has misaligned fields?
is usually caused by differences in encoding or regional settings.
  • CSV It is recommended to use UTF-8 (including BOM) import table tool.
  • Unify date format and decimal point rules to avoid localization differences.
  • When transferring across teams, give priority to using the PDF archive version to prevent deformation.
7) Why is there "partial success and partial failure"?
This is a normal protection strategy in batch processing scenarios: successful items are dropped into the library first, and failed items are put into the retry queue.
  • First export the failure list and process it in groups according to error codes.
  • Once permissions/mappings/networks are fixed, just retry the failed batches.
  • avoids full re-run and reduces the risk of repeated writing and dirty data.
8) How to safely go online in the production environment?
recommends the "grayscale online" method:
  1. First test run in Lab Profile and verify field mapping.
  2. The production environment first selects a small range of assets for the first batch of synchronization.
  3. Expand the scope after confirming that there are no abnormalities, and retain the export snapshots of each batch.

error code quick check (HTTP/common errors)

is used to quickly determine where to start with "configuration problems, permission problems, and network problems".

error code/phenomenon Typical reasons Priority processing steps
401 Unauthorized API Key is wrong, expired or revoked Regenerate Key and confirm that the request header format and Profile are effective
403 Forbidden Insufficient Key permissions (no writing/association) Add assets, components, and accessories related permissions to Key
404 Not Found URL path error, missing /api/v1 Fix ApiUrl, check reverse proxy forwarding rules
409 Conflict Asset tag or serial number conflict Press the primary key to remove duplicates first, and then perform incremental synchronization.
422 Unprocessable Entity Field format does not meet API requirements Check required fields, length, enumeration value and date format
429 Too Many Requests Too high request frequency triggers current limiting Reduce concurrency and increase backoff retry and batch intervals
500 / 503 Server exception or maintenance window Keep failed batches, retry at intervals and contact the server administrator
Connection timeout/TLS failure The network is unreachable and the certificate chain is abnormal. Test connectivity first, then verify certificate and time synchronization

Troubleshooting Runbook (on-site execution version)

When synchronization is abnormal, it is recommended to execute in the following order to reduce misjudgments and repeated operations.

Phase A: Basic Connectivity

  1. Check whether ApiUrl is accessible (including /api/v1）。
  2. Verifies DNS resolution, port policies, and proxy rules.
  3. Confirm that the device system time is accurate to avoid TLS verification failure.

Phase B: Permissions and Configuration

  1. Verify API Key validity and role permissions.
  2. Confirm that the correct environment (Lab/Prod) is selected in Profile.
  3. Check whether the component/accessory switch is consistent with the mapping.

Phase C: Data Quality and Deduplication

  1. Check serial number, asset tag, and model fields on a sample basis.
  2. Clean up historical empty serial numbers and duplicate assets.
  3. Create an "error code → handler" tracking table for failed batches.

Phase D: Recovery and Replay

  1. Only retry failed batches to avoid full reruns.
  2. Export the "success/failure list" and archive it.
  3. Record the root cause and repair plan, and update the team SOP.

5-minute quick troubleshooting card (emergency on duty)

is suitable for scenarios where "the scene is urgent, restore first and then dig deeper". Triage the problem first, and then enter the complete runbook.

1st minute

See error code

First distinguish between 4xx / 5xx / timeout and decide whether to use permission or network lines.

2nd minute

Verify URL and Key

Confirm /api/v1, Profile, API Key and permissions correct?

3-4 minutes

Small batch retry

only retries failed objects and does not do full reruns to avoid amplifying the impact.

5th minute

Leave evidence

Export failure list + log fragments, report and hand over according to work order template.