dragndrop_hld/SPLICING_MAPPING.md

Splicing Field Mapping Guide

This document maps shapefile fields to Verofy API fields for splicing.

Data Analysis Summary

Source: Map Project ID 15685 Total Splicing Records (from API): 0 (no existing data in this map) Total Splicing Records (from shapefile): 100 Date Retrieved: 2025-12-09

Shapefile Structure

From splicing.shp:

Field Name	Data Type	Sample Values
AKA	String	"EUR_CBSP_005_600D", "EUR_Z05_MST_018", "EUR_Z05_SP_004_450D"
Type	String	"Splice", "MST"
Group 1	String	"Zone 02", "Zone 03"
Group 2	String	"EUR_Z05 225-228", null
Latitude	Float	40.778622
Longitude	Float	-124.144169
UID	Integer	0, 1, 2, ...

Unique Values Analysis

Type values found:

• "Splice" (majority)
• "MST" (Mechanical Splice Terminal)

Group 1 values:

• "Zone 02"
• "Zone 03"

Group 2 values:

• Various zone identifiers like "EUR_Z05 225-228"
• Many null values

Verofy API Structure

Based on /map-splice API endpoint and pattern from similar models:

Field Name	Data Type	Required	Sample Values
id	Integer	Auto	(auto-generated)
mapProjectId	Integer	Yes	15685
name	String	Yes	"EUR_CBSP_005_600D"
latitude	String	Yes	"40.778622"
longitude	String	Yes	"-124.144169"
typeId	Integer	Yes	1 (Splice), 2 (FTP), 3 (MST)
statusId	Integer	Yes	1 (Planned), 2 (Splicing Required), 3 (Splicing Completed)
group1	String	No	"Zone 02"
group2	String	No	"EUR_Z05 225-228"
locked	Integer	No	0 (unlocked), 1 (locked)
custom	Integer	No	0

Field Mapping

Direct Mappings

Shapefile Field	API Field	Transformation
AKA	name	Direct copy (string) - This is the primary identifier
Latitude	latitude	Convert float to string
Longitude	longitude	Convert float to string
Group 1	group1	Direct copy (string)
Group 2	group2	Direct copy (string)

Type Mapping (Lookup Required)

The shapefile Type field (string) must be mapped to API typeId (integer) using the MapSpliceType reference:

Shapefile Type Value	API typeId	Type Name in Verofy
"Splice"	1	Splice
"FTP"	2	FTP (Fiber Termination Panel)
"MST"	3	MST (Mechanical Splice Terminal)

Generated/Default Values

API Field	Value	Notes
mapProjectId	User provided	Required parameter
name	{AKA} or "Splice-{UID}"	Use AKA field, fallback to generated name
statusId	1	Default to "Planned"
locked	0	Default to unlocked
custom	0	Default value

Unused Shapefile Fields

Field	Usage
UID	Used only as fallback if AKA is empty

API Endpoint

Endpoint: POST /v1/map-splice/create Authentication: Bearer token required Success Response: 201 Created

Example API Request

Example 1: Splice Point

{
  "mapProjectId": 15685,
  "name": "EUR_CBSP_005_600D",
  "latitude": "40.778622",
  "longitude": "-124.144169",
  "typeId": 1,
  "statusId": 1,
  "group1": "Zone 02",
  "group2": null,
  "locked": 0
}

Example 2: MST Point

{
  "mapProjectId": 15685,
  "name": "EUR_Z05_MST_018",
  "latitude": "40.783264",
  "longitude": "-124.142093",
  "typeId": 3,
  "statusId": 1,
  "group1": "Zone 02",
  "group2": "EUR_Z05 225-228",
  "locked": 0
}

Implementation Notes

1. Type Lookup: The current verofy_uploader.py incorrectly maps Type to type (string field). It should map to typeId (integer) using the MapSpliceType reference lookup.

2. Reference Data: Load MapSpliceType references from MapSpliceType_references.json.

3. AKA Field Importance: The AKA field contains meaningful identifiers that should be preserved as the name. Examples:

   • "EUR_CBSP_005_600D" - Cabinet splice point
   • "EUR_Z05_MST_018" - Zone 5 MST #18
   • "EUR_Z05_SP_004_450D" - Zone 5 splice point #4

4. Error Handling: If a Type value from the shapefile is not found in the lookup table:

   • Log a warning with the unknown type
   • Default to typeId: 1 (Splice) as it's the most common type
   • Continue processing rather than failing

5. Status Default: Default to statusId: 1 (Planned) for new imports. This can be updated later based on actual splicing progress.

Status Reference

statusId	Status Name	Description
1	Planned	Splice location is planned but not yet worked
2	Splicing Required	Location identified, splicing work needed
3	Splicing Completed	Splicing work has been completed

Default to statusId: 1 (Planned) for new imports.

Type Reference

typeId	Type Name	Description
1	Splice	Standard fiber splice point
2	FTP	Fiber Termination Panel
3	MST	Mechanical Splice Terminal

Key Differences from Current Implementation

Current (Incorrect):

splicing_data = {
    "type": str(row['Type'])  # ❌ Wrong - sends string
}

Corrected:

splicing_data = {
    "typeId": type_lookup.get(row['Type'], 1),  # ✅ Correct - sends integer ID
    "statusId": 1,  # ✅ Added required field
    "locked": 0     # ✅ Added default field
}