Skip to main content

AI Import Technical Reference

This page documents how AI Import currently works in code.

Code Locations​

  • Backend routes: backend/routes/import.js
  • Backend controller: backend/controllers/import/importController.js
  • Backend service: backend/services/import/importService.js
  • Import targets: backend/services/import/targets/*.js
  • Import models: backend/models/import/*.js
  • Frontend service: frontend/src/services/import/importService.ts
  • Frontend UI: frontend/src/components/Import/*.tsx

End-to-End Flow​

  1. Upload file (/analyze) or provide text description (/analyze-description).
  2. Parse rows and infer column profile.
  3. Call AI for mapping suggestions against target schema.
  4. Save staging payload in ImportStaging.
  5. User edits mappings in ImportWizard.
  6. Preview transformed rows via /preview.
  7. Execute import via /execute.
  8. Poll ImportJob until terminal status.
  9. Optionally save mappings as template (ImportTransformMap).

API Endpoints​

Base: /api/import (auth + tenant validator applied to all routes)

  • POST /check-templates
  • POST /analyze
  • POST /analyze-description
  • POST /preview
  • POST /resolve-ci-types
  • POST /execute
  • GET /templates
  • DELETE /templates/:id
  • GET /jobs/:id
  • GET /history
  • POST /jobs/:id/cancel
  • GET /targets
  • GET /targets/:targetType/schema
  • GET /staging/:id
  • DELETE /staging/:id
  • POST /quick-import/parse (backend-only path)
  • POST /quick-import/execute (backend-only path)

Data Models​

ImportStaging​

  • File metadata, profile, AI suggestions, preview rows, compressed raw rows.
  • TTL index: 7 days.
  • Tenant-scoped ObjectId.

ImportTransformMap​

  • Reusable mappings/defaults/options and source signature.
  • Unique per tenant by name.
  • Tenant-scoped ObjectId.

ImportJob​

  • Status/progress/results/errors + mapping snapshot + approval snapshot.
  • TTL index: 30 days.
  • Tenant-scoped ObjectId.

Target Dispatch​

targetRegistry routes transformed rows to:

  • CI
  • License
  • Account
  • Contact

For CI target, optional per-row type detection can run from Hardware Catalog (manufacturer+model).

Transform Support​

Backend applyTransform() currently implements:

  • none
  • lowercase
  • uppercase
  • trim
  • extractNumber
  • parseDate
  • parseBoolean
  • mapValue
  • reference

Known Behavior Notes​

  • autoDetectType in ImportWizard is enabled by source-column-name checks for manufacturer + model.
  • Quick import endpoints exist but are not used by the main wizard.
  • Job progress fields are present, but row-level progress is not incremented per row in target imports.
  • Approval hash is generated and verified inside the same execute request path.
  • User guide: documentation/docs/modules/cmdb/ai-import.md
  • CMDB field architecture: docs/CMDB/CI-Fields-and-Attributes.md
  • Detailed internal reference: docs/CMDB/AI-Import-Technical-Reference.md