Demo City Fiber — User Manual

About this manual

The manual follows the layout of the application: a chapter for each sidebar tab and dialog, followed by keyboard shortcuts, administration, the data model and import, troubleshooting and a glossary.

What the application does

The Fiber Manager keeps the physical fiber plant of a city, utility, ISP or campus in one place and lets you work with it on a map:

• Map of facilities, cabinets, manholes and handholes, conduit colored by how full it is, and fiber cables by type.
• Search by ID, name, address, street, cable, circuit or device, with location cards that show what is available at a site.
• Splice editor: two cables side by side, buffer tubes and fibers in TIA-598 colors, with drawn splice lines. Connect, disconnect, splice a tube or a whole cable straight across, undo, and trace any fiber.
• Trace of any fiber from end to end with a hop list, length, an estimated loss budget and the recorded OTDR or power-meter result.
• A → Z dark fiber search between two locations, and fiber reservations.
• Circuits, the open conduit finder, printable reports, CSV export and data health checks.

The installation described here is a demonstration loaded with the fictional Demo City Fiber network: 11 sites (8 facilities and 3 cabinets), 67 manholes and handholes, about 8.2 km of conduit, 14 cables with 924 fiber strands, 382 splices, 10 lit circuits and 1 reservation.

Structures

A structure is any place you can stand: a facility, a cabinet, a manhole or a handhole. Every structure is a point on the map with a label, a name and, for buildings, an address. Facilities and cabinets also have a short site code (for example CH for City Hall or WT for the North Water Tower POP). Site codes are used in cable labels.

Inside a structure, equipment is nested: a rack holds splice enclosures and patch panels, and an enclosure holds splice trays. Active devices (routers, switches, media converters and so on) sit in racks. The location card lists all of them (see ).

Conduit and ducts

A conduit is one pipe or bundle between two structures. It has a material (for example HDPE or Schedule 40 PVC), a size in inches, a color, a placement (bore or trench) and a length. A conduit contains one or more ducts: innerducts or microducts identified by a position letter, such as CD-042.B. Each duct has a status: occupied, spare, reserved or damaged.

The fill of a conduit is the share of its ducts that are occupied. The map colors every conduit by fill:

Cables

A cable runs from its A end structure to its Z end structure through a sequence of conduit ducts called spans. Its length includes slack loops left in manholes. Cables are labelled A-Z.FiberCount+Letter, where the letter tells parallel cables apart: WT-WP.96A is the first 96-fiber cable from WT to WP.

Buffer tubes, strands and TIA-598 colors

The fibers in a cable are grouped in buffer tubes, usually 12 fibers per tube. Tubes and fibers are colored with the TIA-598 standard, in this order:

A single fiber is a strand. Strands are numbered 1 to the fiber count of the cable, and the number is what identifies the strand. Tube and fiber color are worked out from the number:

• tube = the strand number divided by fibers per tube, rounded up;
• fiber in the tube = the remainder, counting from 1.

With 12 fibers per tube, strand 37 is tube 4 (Brown), fiber 1 (Blue). The application shows it as PD-WT.144A #37, with the long form (tube 4 Brown / fiber 1 Blue) and the short code BR.BL (tube code, then fiber code). BL.OR is strand 2 and OR.BL is strand 13.

Splices, terminations and jumpers

Where cables meet inside a structure, fibers are joined in a splice tray inside a splice enclosure. Each join is a splice (a connection) between one strand of one cable and one strand of another. A splice is usually fusion; mechanical splices are also recorded. Splices can carry the measured splice loss, the date and the technician.

A termination puts a strand on a port of a patch panel. A jumper (patch cord) connects a patch-panel port to a port on a device, such as CH-CORE-01 Te1/0/1.

The rule that keeps the records consistent: at any one structure, each end of a strand has at most one splice or termination. The splice editor enforces this as you work (see ).

A splice where a fiber simply continues to the next cable, without being dropped at that site, is called an express splice. Express splices matter when you reserve dark fiber (see ).

Circuits and reservations

A circuit is a service carried on one or more strands, usually a transmit/receive pair. It is labelled CKT-### and has a name, a service type (for example SCADA, Public safety LAN, Internet transit), a bandwidth and an owner. Its status is one of:

• lit — in service, shown in green;
• reserved — fibers held for a future use until a hold-until date, shown in amber.

The data model also knows the statuses planned and decommissioned; the demo network uses lit and reserved. A circuit stores only its starting strands at the A end. The path itself is never typed in: it is found by tracing, so it always matches the splices on record.

Fibers that carry no circuit are dark. A reservation is a circuit with status reserved, created from the A → Z search (see ).

Traces and the loss budget

A trace follows a strand from splice to splice in both directions until it reaches a patch-panel termination, an open (unspliced) end, or a loop. The result is the list of cables, splices and end points the light passes through, the total length, and an estimated loss:

estimated loss = length (km) × fiber loss (dB/km)
               + fusion splices × fusion splice loss
               + mechanical splices × mechanical splice loss
               + connector pairs × connector pair loss

The assumptions are part of the network data and are always shown with the result. For Demo City Fiber they are:

A measured OTDR or power-meter result, when recorded, is shown next to the estimate (see ).

Verified and unverified records

Every record carries where it came from and how much it can be trusted:

On the map, a structure that is not verified has a dashed amber outline. Detail cards show a green verified pill or an amber unverified · source pill, and the identify popup adds unverified after the type. The Q1 data health check lists every unverified structure as a field-verification work list (see ). In the demo, NBUR.100A and W6.550 are unverified records from a legacy spreadsheet.

Splices you make in the splice editor are saved with lifecycle as-built, source web-editor and confidence verified.

Opening the application

The application is a set of web pages. Open index.html in a current browser (Microsoft Edge, Google Chrome, Firefox or Safari), either from the web address your administrator gives you or straight from a folder on disk.

While it loads, the map is empty. When the network data has loaded, the map draws the network and the sidebar shows network statistics.

The screen layout

Dialogs open over the main window for the splice editor, reports and the reservation form.

The top bar

Roles: Viewer and Editor

There are two roles:

• Viewer can see and search everything, trace fibers, run reports, export CSV and run data health checks.
• Editor can also change splices, reserve and release fiber, and save OTDR results.

As a Viewer, editing buttons are disabled: Connect, Disconnect, Tube straight across, All straight across and Undo in the splice editor (which also shows Viewer: read-only), Reserve… in A → Z results, Release reservation, and the OTDR form. If a change is attempted anyway, the message Viewer role: switch to Editor to make changes. appears.

The live totals banner and guided scenarios

A slim banner under the top bar shows the network's totals. It is always visible and updates the moment anything changes: a total that changed flashes briefly. Click lit circuits or reserved to list those circuits in the Circuits tab. On a narrow screen, swipe the banner sideways to see every total.

When the search box is empty, the Search tab shows the guided scenarios.

The Guided scenarios are staged examples on the fictional demo network. Each one jumps straight to a single tool, already set up, so you can see what it does at a glance. They are starting points, not limits: everything they open stays fully editable, and Reset demo data puts the network back.

The demo network is deliberately conventional so the tools read clearly: backbone fibers splice straight across, each cable lands on its own patch panel with port N carrying fiber N, and only a handful of simple exceptions exist. shows how the tool handles messier, real-world splicing.

Saving your work and resetting the demo data

In the demo there is no Save button: every change is saved as soon as you make it, in this browser's local storage. That includes splices, reservations, released reservations and OTDR results. When you open the application again in the same browser, the message Restored your saved demo edits. Use “Reset demo data” to start over. confirms that your changes were loaded.

Using the application on a phone or tablet

On screens narrower than 760 pixels the sidebar becomes a bottom sheet with three heights: peek (just the handle and the tab names, so most of the screen is map), half and full (up to just below the top bar).

• Drag the sheet by its handle or its tab strip to any height; it settles on the nearest of the three. A quick flick moves it one step.
• Tap the handle to step through peek, half and full. Tapping a tab while the sheet is at peek opens it to half; opening a detail card does the same.
• While an edit tool is on, the sheet steps aside and the tool's own panel takes its place at the bottom: compact at first (the title, the one control you need, and Cancel / Done), with the chevron in its title bar to show every option. Hints say tap and double-tap on a touch screen.
• The ☰ button opens a menu with the panel, Reset demo data and the user manual.
• The Legend starts collapsed; tap it to open.
• The splice editor and reports fill the whole screen. The fiber color codes and the keyboard hint are hidden to save room, and the splice editor's How to use folds into one row at the bottom: tap it to read it.

Panning and zooming

The map is limited to zoom levels 11 to 20, which keeps you within reach of the network. Facility and cabinet labels are always shown; manhole labels appear as you zoom in.

Home, scale bar and attribution

The home button (tooltip Zoom to whole network) fits the whole network in view. The scale bar at the bottom left shows distance in feet or miles. The attribution at the bottom right credits the basemap provider; on narrow screens it is collapsed behind a small button.

The Layers panel

Click Layers at the top right of the map to open or close the panel.

The Legend

Click Legend to open or close it. It is open by default on a computer and closed on a phone. It lists only what the map is showing: each section appears and disappears with its switch in Layers, and an Abandoned plant section appears when that layer is on. When it is longer than the space below Layers, it scrolls inside its panel, and the edge with more hidden behind it fades out: the bottom edge at first, the top edge once you have scrolled down.

Identifying features

Point at a feature to highlight it; the pointer changes to a hand. Click to identify it: a popup opens with a summary and buttons.

When several features overlap, the click picks in this order: facilities and cabinets, then manholes and handholes, then cables, then conduit. So clicking a manhole picks the manhole, not the cable passing through it. Zoom in to pick a line between structures.

Close the popup with its × button or by clicking an empty part of the map.

Map highlights

Search results, traces and the finders draw a highlight on top of the network and zoom the map to it. End points are marked with yellow tags such as A · CH and Z · WP.

Click Back in a detail card to clear the highlight.

Searching

Search matches any part of the text, ignoring upper and lower case, in these fields:

Exact label matches come first, then sites, cables and circuits, then other structures, devices, equipment and conduit. Up to 40 results are listed. If nothing matches, the panel suggests what to try: a site code (WT, CH), a cable label (PD-WT.144A), a manhole ID (W2.400), a street or a circuit name.

The location card

A location card describes one structure. Open it from search, from the Details button of an identify popup, or from a device or equipment result.

The cable card

Open a cable card from search, from Fibers & route in a cable popup, or from a cable link in another card. The map highlights the cable in blue with A and Z tags.

The conduit card

Open a conduit card from search, from Ducts in a conduit popup, from a duct link in a cable route, or from the open conduit finder.

Returning from a detail card

Click Back at the top of any detail card to return to the tab you were on. This also clears the map highlight. Detail cards refresh themselves when you edit splices, reserve fiber or save a test result, so the counts are always current.

Opening the splice editor

The splice editor works at any structure with a splice enclosure (facilities, cabinets and splice-point manholes such as MH7). Open it from:

• the Splice editor button in a structure's identify popup;
• Open splice editor on a location card;
• Splices at A (…) or Splices at Z (…) on a cable card;
• the edit link on a splice in a trace, or Splices at End A under a trace (the traced fiber is selected for you);
• Splice editor under Guided scenarios (Police Department).

The editor opens on the pair of cables with the most splices between them, with the cable that starts at this location on the right, so it reads “in → out”. It opens at tube 1; use Go to tube… to jump further down. If no cable ends at a structure, the message No cables end at this structure. appears instead.

Close the editor with the × button at the top right or Esc.

The splice editor window

Reading the fiber board

Each side lists the cable's fibers grouped by buffer tube: a 144-fiber cable has 12 tubes of 12 fibers, in the same TIA-598 color order as the fibers inside them. Each tube starts with a header such as T2 Orange, underlined in the tube color, that says what its fibers do here, for example 4 spliced · 8 on panel or 12 spliced. A tube with no lines across is not unfinished work: its fibers are spliced to a different cable or land on a patch panel, and the header says which.

Each fiber row shows:

Hover over a fiber for a tooltip with its full description, for example MH7-LB.24A #13, tube 2 Orange, fiber 1 Blue, spliced to CH-MH7.48A #25.

Choosing the cables to show

Where only one cable ends at a location, Right cable reads — only one cable here — and the board explains that its fibers are terminated on the patch panel. The tube and all-fiber buttons are then disabled.

Under the cable pairs, Splice trays lists each tray with the cable pairs it holds and how full it is. Click a tray to highlight its splices on the board (the same as choosing it in the All trays list); click it again to show all trays.

Selecting fibers

Click a fiber to select it. You can have one selected fiber on each side. Click a selected fiber again to deselect it.

The information panel then shows the most recently selected fiber:

End A and End Z update instantly as you connect and disconnect, so you can check a change before you leave the editor.

Connecting two fibers

On touch screens, tap a fiber on each side and then Connect: the fiber rows are larger there, sized for a thumb.

New splices are recorded as fusion splices, dated today, with you as the technician. Each one goes on the tray its buffer tubes are routed to, adding a tray when needed and the case has room (see ).

If one of the fibers is already spliced or terminated here, nothing is changed: see .

Disconnecting a fiber

A fiber that is neither spliced nor terminated here shows … is not spliced or terminated here.

Terminating a fiber on a patch panel

A fiber that lands in the building, rather than continuing on another cable, is terminated on a patch-panel port. You can move a fiber between the two.

Both changes are single steps that Undo reverses.

Splicing a tube straight across

Splicing a whole buffer tube at once is the usual way to splice a branch cable into a ring. Fiber 1 of the left tube is joined to fiber 1 of the right tube, fiber 2 to fiber 2, and so on.

Fibers that are already spliced or terminated are skipped, and the rest are spliced. The status line counts all three outcomes, for example All fibers straight across: nothing to change — 108 already straight across · 24 blocked because a fiber is spliced elsewhere or on a panel (flashing red). Blocked fibers flash red. Pairs already spliced to exactly the matching partner are counted as already straight across, not as blocked.

If the two tubes have a different number of fibers, only as many fibers as the smaller tube has are spliced.

Splicing all fibers straight across

Conflict checks

Every change is checked before it is made. A strand end can have only one splice or termination at a location, so Connect is refused when:

• both fibers are in the same cable (Both fibers are in the same cable.);
• a fiber is already spliced here (… is already spliced to ….);
• a fiber is terminated on a patch panel here (… is terminated on ….).

The status line turns red, starts with Conflict: and ends with Disconnect it first (a fiber connects once per side). Both fibers flash red. Nothing is saved.

Undo

Click Undo or press U (or Ctrl+Z) to reverse the last change. The button itself names that change before you click, for example Undo: Tube 3 Green → tube 2 Orange, and the status line confirms what was undone. You can undo repeatedly, back to the first change of the session.

Undo covers every change: splices, terminations, circuits, and everything built, edited, moved, abandoned or deleted with the edit toolbar, wherever in the application you made it. The edit toolbar also has Redo. It does not cover OTDR results.

Tracing from the splice editor

Select any fiber and the information panel shows its End A and End Z at once. Press T to refresh the panel for the last selected fiber without leaving the editor.

Using the keyboard

The splice editor can be used entirely from the keyboard. Each fiber column is a single Tab stop; inside it, use the arrow keys.

The letter keys do nothing while a cable or tube list has focus, so you can type to pick from a list.

The splice editor for viewers

Viewers can open the editor, change the cables shown, select fibers, read End A / End Z and use Trace. Connect, Disconnect, Tube straight across, All straight across and Undo are disabled. Editing keys show Viewer role: switch to Editor (top right) to change splices.

Real-world splicing: worked examples

The demo network is kept simple on purpose. Real plant is rarely that tidy: decades of repairs, re-feeds and contractors leave crossed fibers, tubes that change color between cables, and fibers that split off in the middle of a tube. The model handles all of it the same way, because every splice is a record that joins exactly one strand to another, and every path is traced from those records rather than typed in. These examples show how.

1. A drop cable spliced onto a different tube

In the demo: at the Police Department, fibers 13–16 of CH-PD.144A (tube 2, orange) are spliced to fibers 1–4 of the camera drop PD-CM1.12A (tube 1, blue). Branch cables almost always start at tube 1, so the color changes at the splice.

How the tool shows it: with both cables on screen, the four lines cross from orange to blue and are drawn slightly thicker. With another cable on the right, the rows read ↪ PD-CM1.12A #1; click it to follow the splice. The trace of fiber 13 lists the splice as crossed #13→#1 and still ends at the camera cabinet's media converter.

2. A rolled pair

In the demo: at the Water Treatment Plant, a repair crossed fibers 85 and 86 between WT-WP.96A and WP-PW.96A: 85 goes to 86 and 86 to 85.

How the tool shows it: two lines form an X in tube 8. A circuit on that pair still traces correctly end to end. If the pair was crossed by mistake, select one fiber, Disconnect both, and Connect them straight; End A and End Z update as you go.

3. A mid-tube tap

In the demo: at the Library, fibers 5–6 of MH7-LB.24A are spliced to fibers 1–2 of the traffic-signal drop LB-TS2.12A, while the rest of that tube lands on the library's patch panel.

How the tool shows it: the tube header reads 2 spliced · 10 on panel, and the two tapped fibers carry ↪ badges. A → Z search treats the tapped fibers as part of the signal circuit's path, not as free library fibers.

4. Fibers coiled in a manhole for later

In the demo: in the MH7 splice case, only tube 1 of CH-MH7.48A continues to the library and four fibers drop to the traffic signal. The rest stay coiled in the case.

How the tool shows it: those rows read open, and the tube headers count them (4 spliced · 8 open). When a new lateral is built, splice it with Tube straight across, or select individual fibers and Connect.

5. Where the tool goes beyond the demo

The same rules cover the messier cases found in legacy records, without special handling:

• A fiber crossed between two different tubes at several locations. Each location is its own splice record, and the trace follows them in order, however many there are.
• A cable re-fed from the other direction. Cable A and Z ends are fixed. A splice can join any end, so the trace walks correctly whichever way the fiber was re-routed.
• Accidental loops. A path that comes back on itself is stopped and reported as Loop detected instead of running forever.
• Conflicting legacy records. When imported spreadsheets claim two splices on one fiber end, the importer refuses them (rule V4) and the Data health report lists them for field checking, rather than guessing.
• Mixed color standards or fiber counts. Tube and fiber colors are derived from the strand number, so a 288-count cable with 24 fibers per tube, or a 6-fiber drop, draws correctly with no extra setup.

Placing a structure

Placing a structure on a conduit run

Click on a conduit to insert a handhole, manhole, vault, pedestal or pole into it. The structure lands exactly on the run, and the run is split in two at it: CD-042 now ends at the new structure, and a new run (for example CD-088) continues from it, with the same ducts and duct statuses. Cables in the run are not cut: they now pass through the new structure, with one more hop. The result offers Open a splice point on … for each of those cables, which turns the hop into a splice (see ). Cabinets and buildings sit beside the street, so they are never inserted into a run.

Laying conduit

For a quick straight run, open Or a straight run between two structures, pick From and To, and click Add straight conduit. Lay conduit from here on a location card fills in From for you.

Pulling cable

The route is the shortest one through conduit that still has a spare duct. If there is none, the route result says which conduit is full; lay conduit first.

At each end of the new cable:

Splice cases, trays and tube routing

A splice case holds a fixed number of trays; a tray holds a fixed number of splices (12 or 24). Each tray also lists the buffer tubes routed to it: in the field a tube is laid into one tray, and its fibers are spliced there.

Use the Splice cases and trays tool: click a structure on the map (or pick it in the flyout; Add splice case / Add tray / case on a location card does the same) to add a case or a tray by hand. The panel lists each case with its trays and how full they are. Add tray is refused once the case holds all the trays it can: add another case.

In the splice editor, each tube header has a tray list showing where the tube is routed, for example → ST3 16/24. Choose another tray to move the tube, and its splices here move with it (the tubes they join to are routed there too). Add tray in the editor toolbar adds a tray to the case here, or a case if there is none.

New splices go where their tubes are routed. A tube pair always goes onto one tray together: a tray already holding both tubes, then one holding either, then an empty tray, then any tray with room. If none has room, a new tray is added while the case has space; otherwise the splice is refused with a message to add a case. The status line says when a tube was routed or a tray added, for example added tray W4.150.SC1.T2; routed MH7-NC1.12A T1 Blue to W4.150.SC1.T2.

Editing, moving and reshaping

Click Select and edit in the edit toolbar, then click a structure, conduit or cable on the map. (Edit / move / remove on a location card, cable card or conduit card opens the same form.) The flyout shows its details as a form, what is connected to it, and how it can be removed.

Click Save changes to apply the form. Labels must stay unique. An occupied duct's status is set by its cable and cannot be changed here. Setting Confidence to verified is how a field check is recorded: the record leaves the field-verification list in .

Patch panels

The edit flyout of a structure lists its patch panels under Patch panels: label, number of ports and how many fibers are landed on it (and the highest port in use).

Fibers are landed on a panel's ports, and lifted off them, in the splice editor (see ). rule V10 also checks that no fiber sits on a port beyond its panel's size.

Rerouting a cable

A cable can be moved onto other conduit runs between the same two ends, for example around a damaged or full run. Its ends, splices and terminations do not change.

A run with no spare duct cannot be used: add a duct to it (conduit edit form) or pick another run.

Change history

The edit flyout of every structure, conduit and cable ends with its History: each change, newest first, with what changed (for example name E 12th St → Main St manhole), when and who made it. A structure's history includes its patch panels, splice cases and splices (as counts: 12 splices added); a conduit's includes its ducts; a cable's shows reroutes. The last line says since when, and from which source, the record has been on file. Show all lists more than the last eight changes.

The history is saved with your edits in the same place (this browser in the demo; see ) and survives a reload; Reset demo data clears it. Each entry records who made the change: in the demo that is the demo editor; when sign-in is added, the signed-in user's name fills the same field.

Abandoning and deleting

Plant that exists, or existed, is abandoned, not erased, so the record keeps its history:

• Abandon marks it out of service. It disappears from the map, routes and fiber searches, and stays on record. Turn on Abandoned plant in Layers to see it (dotted gray), and Restore to service brings it back.
• Delete removes a record completely. It is only for mistakes: records still planned, or created in this session. For anything else the button is disabled.

Both are refused while something still depends on the record, and the message says what:

The Connected to it list in the flyout shows these dependencies before you try. Every abandon, restore and delete is one Undo step.

Opening a splice point mid-cable

Most splicing happens where cable ends meet. The exception is a mid-span access: tapping fibers out of a cable that passes straight through a manhole or handhole without a splice.

Nothing changes end to end: every circuit on the cable still traces through, with one more splice in its loss budget. To tap fibers, select one, Disconnect it, and splice it to the new cable. The A-side cable keeps its record, so circuits and the A end are untouched. Records at the far end move to the Z-side cable. One Undo reverses the whole split.

Worked example: a new camera lateral

1. Place a cabinet NC1 near the MH7 manhole.
2. Lay conduit from MH7 to NC1: a 2" PVC lateral with 2 innerducts.
3. Pull cable MH7 → NC1, 12 fibers. NC1 gets a patch panel with all 12 fibers on it; MH7 already has a splice case, so it is ready to splice.
4. Click Splice it in at MH7. The splice editor opens with CH-MH7.48A on the left and the new cable on the right.
5. Pick T3 Green → T1 Blue and click Tube straight across. The 12 splices go onto a new tray with both tubes routed to it.
6. Select fiber 1 of the new cable: End A is City Hall's patch panel, End Z is NC1's. Trace or reserve it like any other fiber.

Starting a trace

Start a trace from any of these:

• a fiber chip in the Fibers grid of a cable card;
• a circuit in the Circuits tab, in search results or under Fiber service at this location (the circuit's first strand is traced);
• a fiber chip #n in an A → Z route;
• Trace or Show full trace on map in the splice editor;
• End-to-end trace under Guided scenarios.

Reading the trace view

The map highlights the path in green (lit), amber (reserved) or yellow (dark), marks every splice location with a dot, and tags the ends A · … and Z · ….

Totals and the loss budget

The length is the sum of the cable lengths on the path, including slack loops. The estimated loss uses the formula in . Expand Loss assumptions to see the calculation, for example:

0.35 dB/km at 1310 nm × 2.770 km = 0.97 dB · 0.1 dB per fusion splice · 0.5 dB per connector pair. Length includes slack loops. Recorded splice losses on this path total 0.10 dB.

The recorded splice losses are the values technicians entered for each splice. They are listed for comparison and are not part of the estimate.

Recording an OTDR or power-meter result

Finding dark fiber routes

The location lists contain every site with a site code, shown as code — name. You can also fill them from a location card with Use as A and Use as Z.

If A and Z are the same, the panel asks you to Pick two different locations. If no fiber connects the two sites through existing splices, the panel says so and suggests opening the splice editor at an intermediate location to build the path.

Reading the route results

Fibers are grouped into routes: all fibers that follow the same sequence of cables. Routes with free fibers come first, then those that are ready to use without opening splices, then the shortest.

Express splices and “Ready to use”

A dark fiber can pass through A or Z on an express splice and continue to another site. Such a fiber does reach both sites, but to use it between A and Z the splice at the end of the route must be opened so the fiber ends there.

The route card tells you how many express splices would need opening for its best free fiber. When you reserve, the application opens them for you, and the reservation's notes record it (Opened n express splice(s) at the route ends.). The reservation form also warns about it before you confirm.

Reserving fiber

A new reservation gets the next circuit number, the service Reserved capacity, today's date as reserved on, and the owner Demo City IT. If the route has fewer free fibers than requested, the message Not enough free fibers on this route. appears and nothing is reserved.

Releasing a reservation

The Circuits tab

Use the filter chips All, Lit and Reserved to narrow the list. Each circuit shows:

• a status tag (lit in green, reserved in amber) and a matching colored edge;
• the label and name, for example CKT-005 · Library public Wi-Fi backhaul;
• End A ⇄ End Z site codes, length, estimated loss, and for reservations the hold-until date.

Click a circuit to open its trace view, with the circuit report and test result. The list updates as soon as you reserve or release fiber.

Circuits in the demo network

Finding open conduit

Reading the results

Only ducts with status spare count as free; reserved and damaged ducts do not. Abandoned conduit is never used. If the two structures are the same, the panel asks you to Pick two different structures.; if no conduit connects them at all, it says These structures are not connected by conduit.

The Reports tab

The circuit report

Open it from the Reports tab, from Circuit report in a trace view, or from Guided scenarios.

The report contains:

• the circuit label, name, service and status;
• owner, bandwidth, A end and Z end (with the device), strands, total length, and for reservations who reserved it, when, until when, and notes;
• a Path table for each strand: every hop with its type (End A, Cable, Fusion splice, Mechanical splice, End Z), location, detail and length;
• the Loss budget table: fiber attenuation, splices and connector pairs, the estimated total, and the measured OTDR value if one is recorded;
• the OTDR test: measured loss, wavelength, date, technician and report file, or No test recorded yet.;
• signature lines for Tested by, Date and Approved, and a footer with the date and time it was generated.

Download CSV saves the path tables as CKT-###-circuit-report.csv with the columns circuit, strand, hop, type, location, detail, length.

The splice tray report

Open it from the Reports tab or from Splice report on a location card.

The report lists the enclosure, the number of trays, splices and terminations, and the cables. Then, for each tray, every splice in strand order with strand A and strand B (label, tube and fiber color swatches and code), type, loss, date and technician, and circuit. For each patch panel, every port with its strand, what it is patched to and the circuit.

Download CSV saves the splices as <location>-splice-report.csv with the columns location, tray, strand_a, code_a, strand_b, code_b, kind, loss_db, date, technician, circuit.

The splice diagram

A printable drawing of one splice location for the crew working in it. Open it with Print diagram in the splice editor, Splice diagram on a location card, or Splice diagram on the Reports tab.

It contains:

• the location: label, name, address, latitude and longitude, lid size, and the number of splice cases, trays, splices and panel terminations;
• Cables here: each cable with its type, fiber count (tubes × fibers per tube), which end is here (Z end = coming in, A end = going out), the other end, and how many of its fibers are spliced, on a patch panel or open here;
• for each splice case, each tray as a diagram: fibers coming in on the left, fibers going out on the right, one line per splice. Each fiber shows its label, its colour code (tube.fiber), its tube colour and its fiber colour with its number in the tube. A line that changes height is a fiber that changes position (a rolled pair or a tube moved to another). Green lines are lit circuits, dashed amber are reserved, gray are spliced but dark; a dot marks a fusion splice and a square a mechanical one. The circuit label is at the right. The tray heading lists the buffer tubes routed to it. A tray of more than 36 splices continues in a second block;
• each patch panel: every port in use, with its fiber, colour code, what it is patched to and the circuit;
• the TIA-598 colour code (1 Blue to 12 Aqua) and signature lines for Spliced by, Date and Checked.

It prints on the printer's normal page (portrait), each tray kept whole on a page. Download CSV saves one row per splice as <location>-splice-diagram.csv: location, case, tray, in_strand, in_code, out_strand, out_code, kind, loss_db, circuit.

The map book

A set of printed map pages a crew can take into the field. On the Reports tab, pick the Area and the Page scale, then click Open map book.

• Area: Whole network, or Current map view (zoom the map to the area first).
• Page scale: 1 in = 100, 200, 400 or 800 ft. The area is cut into a grid of squares, one printed page each, at that scale. Columns are lettered from the west (A, B, C …) and rows numbered from the north (1, 2, 3 …), so a square is named like B3. Squares with no plant get no page.
• Page 1 is the index: the whole area with the grid on it, each square named with its page number, and the legend.
• Each map page shows one square: facilities, cabinets, manholes and handholes with their labels (site names too), splice cases ringed in orange, conduit coloured by fill, cables by type with their labels, and street names. Arrows at the edges name the page that continues on that side. Under the map: a key map with this square highlighted, the legend, a scale bar in feet and metres, the scale and a north arrow.
• The book ends with a location index: every structure (sites first, then by label) and the square it is on.

The book prints on Letter paper in landscape: print it at 100 % (no "fit to page") and the scale bar is true. Abandoned plant is included only when Abandoned plant is on in the Layers panel. The map pages are drawn from the network itself, without the basemap, so they print sharp in colour or gray and need no internet connection. Download CSV saves the location index (location, name, type, page, lat, lon).

Printing and saving a report as PDF

Close the report with the × button or Esc.

CSV exports

Click a button in the CSV export card to download the current data, including your changes. The message Exported n … rows. confirms the download. File names start with the organisation name from the top bar (demo-network in the demo).

GeoJSON export

The GeoJSON export card downloads the network as map layers for a GIS (QGIS, ArcGIS Pro, or any web map): Structures (points), Conduits and Cables (lines), or All three in one file with a layer property. Coordinates are WGS 84 longitude/latitude (the GeoJSON standard). Each feature carries the record's details (label, type, lifecycle, confidence, source, last update) and a few derived values: cable ends and splices at a structure, duct fill and cables in a conduit, the A and Z ends and conduit runs of a cable.

Shapefiles and Esri file geodatabases are exported and imported with the administration tools rather than in the browser; see .

Running the checks

The rules

The importer runs three more rules that need the original files: V7 (every reference resolves), V8 (a splice or termination is at a structure where the strand's cable has an end) and V9 (a duct holds at most one cable and its status matches). See .

Acting on the results

• Q1 is a work list: send a crew to check each listed structure, then update its confidence to verified in the source data.
• Errors in V1–V6 come from the source data, not from the editor: the splice editor prevents V4 problems as you work. Correct the source records and re-import.

Application

Splice editor

This manual

Files and folders

Deployment modes (config.json)

config.json sits next to index.html and selects how data is loaded and saved:

{
  "mode": "demo",
  "dataUrl": "assets/data/demo-network.json",
  "apiBase": "api/",
  "storageKey": "fiberDemo.edits.v1",
  "orgName": "Demo network",
  "demoBadge": true
}

Deploying on IIS as a drop-in folder

web.config reference

Updating the application

Because scripts and styles are cached for 7 days, each <script> and stylesheet tag in index.html carries a version, such as app.js?v=1.0. When you replace JavaScript or CSS files, increase that number in index.html so browsers fetch the new files. index.html itself is never cached.

To publish a new network file, replace the file named by dataUrl. It is not cached, so users get it on the next page load. In demo mode, saved browser edits made against the previous file are then ignored.

Identity and Windows Authentication

The Viewer/Editor switch exists only in demo mode and is not security. In production the user's identity always comes from the host, never from the page:

• On an intranet, use IIS Windows Authentication (domain accounts), or put a sign-in provider (for example Entra ID / OpenID Connect) in front of the REST API.
• The API returns the user's name and role from GET {apiBase}me, enforces the editor role on POST changes, and records who made each change.
• The page only shows the name and hides editing controls for viewers.

Closed-network setup

Users' browsers need outbound access to:

• cdn.jsdelivr.net — the OpenLayers map library (ol.js and ol.css, version 10.2.1);
• server.arcgisonline.com — the three basemaps.

Where demo edits are stored

Each browser profile on each computer has its own copy. Reset demo data deletes the edits key.

The REST interface

All data access goes through one storage-adapter interface in assets/js/store.js (load(), save(change), reset(), identity(), readOnly). The rest adapter expects a server with three endpoints:

All requests are sent with credentials. If the server rejects a change, the user sees Server rejected the change (status). Reload to resync.

Design principles

1. One structure table. Every place you can stand is a structure with a point: facility/POP, manhole, handhole, vault, pole, cabinet, pedestal.
2. Containment, not columns. Racks, splice enclosures, splice trays and patch panels are equipment inside a structure, nested by parent (structure › rack › enclosure › tray, or structure › rack › patch panel).
3. Pathways are separate from cables. A conduit runs between two structures and holds ducts; a cable occupies one duct per span.
4. Strands have stable IDs. cableId:N. Tube and fiber color are derived; BL.OR is display, never a key.
5. Connections are first-class rows. Splices, terminations and jumpers are records. End-to-end paths are derived by tracing, never typed in.
6. Circuits reference strands, not paths.
7. Every record carries provenance: ID, label, lifecycle, source, confidence, created and updated by and when.
8. Geometry is GeoJSON in WGS 84 (EPSG:4326). The source coordinate system is kept, and importers reproject on the way in.

Entities

Naming conventions

Internal IDs (st-0001, cb-0003, …) are never shown as the main name and never re-used, so labels can be renamed without breaking references.

Status values

CSV import templates

The templates/ folder has one blank CSV per entity, each with example rows. Rows refer to each other by label; the importer assigns the internal IDs. Import them in this order (each file only refers to labels from files before it):

Mapping from legacy spreadsheets

A typical legacy fiber spreadsheet maps into the model as follows (full detail in docs/IMPORT-MAPPING.md). The first step of any import is a column-mapping pass onto the template headers.

Every sheet is cleaned the same way: values are trimmed, invisible characters removed, non-breaking spaces replaced, text normalized; coordinates are range-checked and swapped latitude/longitude pairs repaired. Legacy rows default to confidence unverified until checked in the field.

Running an import

Shapefiles and Esri file geodatabases are imported with import_gis.py, which turns them into the same templates and runs this importer; see .

Importing and exporting shapefiles and file geodatabases

tools\import_gis.py reads a folder of shapefiles or an Esri file geodatabase (.gdb folder), turns its layers into the template tables above, and runs the importer on them, so a GIS import gets the same cleaning, checks and report as a spreadsheet import.

%LOCALAPPDATA%\roamrock-tools-venv\Scripts\python.exe tools\import_gis.py client.gdb out\network.json --csv out\tables
%LOCALAPPDATA%\roamrock-tools-venv\Scripts\python.exe tools\import_gis.py shapefiles\ out\network.json

Layer names are matched without regard to case; field names exactly, without regard to case, or by their first ten characters (shapefiles cut field names to ten, so from_structure arrives as from_struc). Fields that match no template column are listed and skipped. A client's own geodatabase will use its own names: rename them to the templates in a copy first.

tools\export_network.py network.json out\ writes the reverse: the template CSVs, GeoJSON, a shapefile folder and network.gdb. tools\test_gis.py runs the whole round trip on the fictional demo network and checks nothing is lost. The GIS tools need pyshp and pyogrio in the tools Python environment; the browser application needs neither.

The map is blank or shows an error

• The map library could not load (offline?). Reload when connected. — the browser could not reach cdn.jsdelivr.net. Check the internet connection or proxy, or host OpenLayers locally (see ).
• Could not load the network data. Check config.json (mode / dataUrl / apiBase). — the network file or API could not be read. Check that dataUrl points to an existing file, that the server serves .json (keep web.config on IIS), or that the API answers in rest mode.
• The network draws but the background is plain dark — the basemap tiles are blocked. Every tool still works.

Editing buttons are grayed out

• You are in the Viewer role: click Editor in the top bar (demo mode).
• In static mode the application is read-only for everyone.
• In the splice editor, Connect needs one fiber selected on each side, Disconnect and Trace need a selected fiber, and Undo needs a change made in this session.
• Tube straight across and All straight across need two cables; they are disabled where only one cable ends.

There is no Splice editor button

The button appears only for structures with a splice enclosure. Plain manholes and handholes on the conduit route have none; cables pass through them without splices.

My changes are gone

• Someone clicked Reset demo data in this browser.
• You are using a different browser, browser profile or computer: demo edits are stored per browser.
• The browser's site data was cleared, or the window was private.
• A new network file was published; edits made against the old file are not loaded.

Connect says “Conflict”

One of the fibers is already spliced or terminated at this location, or both fibers are in the same cable. Read the status line, which names the fiber and its current partner, disconnect it first, then connect again. See .

A → Z finds no route

A → Z only follows splices that already exist. If no fiber runs between the two sites, build the path: open the splice editor at each intermediate location and splice a tube or fibers through, then search again. Choose sites on the same ring to see results quickly.

The measured loss is far from the estimate

The estimate uses fixed assumptions (see ). A difference of more than 0.5 dB is flagged investigate. Check the recorded splice losses on the trace, connector cleanliness at both ends, and whether the measurement was at 1310 nm.

The printed report includes the map, or is empty

Use the Print / PDF button in the report window rather than the browser's own print command with no report open. The print layout shows only the open report.

The map is rotated

Holding Alt+Shift while dragging, or twisting two fingers on a touch screen, rotates the map. Reload the page to return to north-up.

Can I open the application straight from disk?

Yes. Double-click index.html. The data loads from the .js copy, config.json is not read (demo mode applies), and the browser still needs internet access for the map library and basemap. This manual also works from disk.

Terms