Xiber NetOS — Data & Import Guide

Data model, system-of-record boundaries, CSV/XLSX import workflow, and validation rules.

System of Record Boundaries

What NetOS Owns

What NetOS Does NOT Own

NetOS will pull from these systems (Sonar revenue, LibreNMS monitoring links, Wisdm geometry) and push to them (Monday.com renewal tasks, DocuSeal termination notices) — but those systems remain the source of truth for their respective domains.

Data Model

Core Entities

Carrier ── Circuit ── Contract
              │
              ├── Endpoint snapshots copied from selected sites
              ├── LifecycleEvent
              ├── Invoice ── InvoiceLineItem
              └── RenewalDecision

InfrastructureAsset ── SubtendedLink ── Customer
        │                  │
        │                  ├── Circuit cost source
        │                  └── RFLink cost source
        ├── ElectricalService
        └── InfrastructureDocument

Customer ── ElectricalService
RFSystemCatalog ── RFLink ── RFLinkDocument

Circuit Natural Key

(carrier_id, carrier_circuit_id)

This composite key prevents duplicate circuits when importing the same carrier inventory multiple times. If a row matches an existing natural key, the circuit is updated rather than duplicated.

Manual circuit entry should use Infrastructure and Customer site selectors. Imported endpoint fields remain supported for bulk onboarding, carrier inventory loads, and legacy records, but the preferred operating workflow is to create or correct the Infrastructure/Customer site first and then select that site on the circuit.

Key Enums

CSV/XLSX Import

Import Templates

The import page now has separate downloadable templates:

Use separate files when the records have different lifecycles. Circuits are matched by provider plus carrier circuit ID; infrastructure is matched by Xiber infrastructure label.

Circuit Required Fields

These two fields form the circuit natural key. All other fields are optional but recommended.

If xiber_circuit_label is omitted, NetOS generates it using Provider Short Name Service Type A Loc -> Z Loc when the provider has a short name, otherwise Carrier Service Type A Loc -> Z Loc. DIA and broadband use the same pattern without a Z location because they are single-site services. Generated labels are truncated to fit the circuit label field and receive a numeric suffix only when needed for uniqueness.

Recommended Fields

Contract Fields (Optional)

Infrastructure Fields

Infrastructure imports cover facilities and structures that have their own cost, agreement, and renewal lifecycle. Electrical utility accounts are tracked separately under Electrical Services after the infrastructure or customer site exists.

Manual Bulk Maintenance

After import, users can make broad operational corrections from the UI.

Circuit Bulk Actions

URL: /circuits

Select rows with the checkboxes in the first column. The header checkbox selects all currently visible filtered rows.

Infrastructure Bulk Actions

URL: /infrastructure

Select rows with the checkboxes in the first column. The header checkbox selects all visible rows.

Bulk deletes are soft-deletes. They set deleted_at and preserve the record for audit/history.

Import Workflow

What Happens on Re-Import

When a row matches an existing circuit by natural key (carrier, carrier_circuit_id), or existing infrastructure by xiber_infrastructure_label:

• All provided fields are updated to the new values
• Fields not present in the import are left unchanged
• This is an upsert, not a replace

Validation Rules

Current limitations:

• No inline editing of staged rows (must fix CSV and re-upload)
• No diff preview before updating existing circuits
• No explicit confirmation for financial field overwrites from CSV/XLSX
• Column mapping is heuristic-only (AI-assisted mapping planned)

API Import Examples

Preview (upload and detect mapping):

curl -H "x-user-role: exec" \
  -F "file=@examples/sample_circuits.csv" \
  http://localhost:8000/api/v1/imports/circuits/preview

Response:

{
  "import_job_id": "abc123",
  "detected_mapping": {
    "Carrier": "carrier_name",
    "Circuit ID": "carrier_circuit_id",
    "MRC": "mrc_usd"
  },
  "headers": ["Carrier", "Circuit ID", "Type", "BW", "MRC", ...],
  "sample_rows": [...],
  "total_rows": 45,
  "valid_rows": 42,
  "invalid_rows": 3
}

Commit (import valid rows):

curl -H "x-user-role: exec" \
  -X POST \
http://localhost:8000/api/v1/imports/circuits/{import_job_id}/commit

Infrastructure imports use the same pattern:

curl -H "x-user-role: exec" \
  -F "file=@netos-infrastructure-import-template.csv" \
  http://localhost:8000/api/v1/imports/infrastructure/preview

curl -H "x-user-role: exec" \
  -X POST \
  http://localhost:8000/api/v1/imports/infrastructure/{import_job_id}/commit

Response:

{
  "inserted": 38,
  "updated": 4,
  "invalid": 3,
  "errors": [
    {"row": 12, "field": "mrc_usd", "error": "not a valid number"},
    {"row": 23, "field": "carrier_name", "error": "required field missing"},
    {"row": 31, "field": "service_type", "error": "unknown value: 'wavelength'"}
  ]
}

Sample CSV

Files:

• /templates/netos-circuit-import-template.csv
• /templates/netos-infrastructure-import-template.csv

carrier_name,carrier_circuit_id,xiber_circuit_label,service_type,bandwidth_mbps,status,mrc_usd,nrc_usd,a_endpoint_name,a_city,a_state,z_endpoint_name,z_city,z_state
Lumen,DHEC.123456,XIB-LUM-0001,wave,10000,active,2500.00,5000.00,Xiber HQ,Columbus,OH,Cologix COL1,Columbus,OH
Zayo,ZY-789012,XIB-ZAY-0001,dark_fiber,100000,active,4200.00,15000.00,56 Marietta St NW,Atlanta,GA,Equinix AT1,Atlanta,GA

Common circuit purpose values include backhaul, backup, customer_dedicated, internet, dr, and management. Use backup for MFC backup circuits, such as broadband service backing up a primary fiber or RF path.

Endpoint Coordinates

Map rendering and geographic topology require endpoint coordinates.

Coordinates are stored as PostGIS geometry. The seed data includes coordinates for all sample endpoints. When importing circuits, endpoints are auto-created as stubs without coordinates — add coordinates later via the API or UI to make them appear on the map.

Contract Data

Contracts are linked to circuits and/or infrastructure assets. Key fields:

Current state: Sample contracts are created by the seed script. PDF extraction and side-by-side approval are not yet implemented. See Roadmap for the PDF ingestion plan.