Load the functional-location tree from Excel

On Maintenance → Settings → Import you can load a site’s whole functional-location tree (unit → technology → sub-system → … → position) from one xlsx or CSV file instead of creating the elements one by one. It runs in two steps: first a Check, which writes nothing but tells you exactly what would happen; then the Import, which commits on an all-or-nothing basis.

Before you start

Permission: cmms:manage (manage maintenance). Without it the Import tab is not available.
Prerequisite: the Maintenance module is on, and you have access to at least one site. The import loads into one site’s tree; with several sites, you pick the target at the top of the page.
The level ladder is set up: the tree is built on the site’s level ladder (Settings → Levels). The template is generated from it, so set the ladder first.
The data stays yours: the file is not stored — only its name and fingerprint go into the audit log.

Steps

Open Maintenance → Settings → Import. With several sites, choose the target site — both the template and the import apply to it.
Click Download template. The first sheet of the downloaded xlsx (Functional locations) holds the header; the second sheet (Guide) has a short description and the list of equipment types (code and name).
Fill in the template: one path per row, going down the levels. The columns are explained below.
In the Upload block pick the file (.xlsx or .csv) and, if needed, the Default plant.
Click Check. Read the report (see below), fix the file, and repeat until it is clean.
When the report says “The check passed — the file can be imported.”, click Import. The button stays disabled until the current file has a clean check; after changing the file or the plant you must check again.

What the columns mean

Headers ignore accents, upper/lower case and punctuation. The safest way is to start from the downloaded template.

Column	What to enter
Level columns — two per level: the level’s label (e.g. `Technology`) and `… code` (e.g. `Technology code`)	The node’s name and (if it has one) its code. An empty level is skipped — the depth may vary from row to row. If only the code is filled in, the code is used as the name too.
Operation criticality, HSE criticality	The criticality of the row’s deepest node (the one lowest in the row).
Equipment type	The equipment type’s code or name (from the Guide sheet). An unknown or ambiguous name is an error.
Description	The deepest node’s description.
Properties (e.g. `Rated power [kW]`)	The properties defined for the site — the header is the property’s label (optionally with the unit). The value must fit the type.

Good to know:

Criticality, equipment type, description and properties go to the row’s deepest node; the higher levels only give the hierarchy.
The file does not decide the site or the plant. You choose them on the page; there is no column for them and the file cannot override them.
The Default plant is applied only to newly created nodes under a parent that has no plant binding yet; an existing plant binding is not changed and is inherited. Choosing “None” means the import assigns no plant.
Property values are typed: a number may use a decimal comma; a date is YYYY-MM-DD (an Excel date cell works too); a boolean is yes/no. An invalid value is an error.
A cell is always text: an Excel formula is never evaluated. If a name or code starts with = it is stored as text, and you get a warning.
Format: for xlsx the first sheet is read; CSV must be UTF-8, and the delimiter is detected. The file extension must match its content.

What the Check report tells you

The check runs exactly the same path as the import and rolls everything back at the end — so the report shows the real result, not an estimate.

Counts (for the whole file, in nodes): Rows · New (would be created) · Updated (exists and would actually change) · Unchanged (exists and would not change) · Rows with errors · Blank rows (completely empty rows are skipped).
Errors: they name the row (“Row 12: …”) and the problem. While there is even one error, the Import does not run — see the next section.
Warnings: they do not block the import but are worth a look. Examples: conflicting values for the same node in the file (the last one applies), a property that does not apply to the node (skipped), or a formula-like value (stored as text).
Unrecognised columns (skipped): such a column is left out, and the report lists it by name — so a mistyped header does not vanish silently. If the same role appears twice, you get a file-level error.
Per row: every row shows whether it is new, updated or unchanged. The screen shows the first 300 rows and says when the list is cut; the counts always cover the whole file.

The most common errors

Message (meaning)	What to do
unknown equipment type	Fix the name or code using the Guide sheet’s list.
the equipment-type name is ambiguous	Use the equipment type’s code.
several nodes with the same name/code under the parent	Add a code that tells them apart, or merge the duplicate in the tree.
the existing node is at a different level	The import never re-levels — the tree already has this element, at another level. Fix the file, or move the element in the tree first.
the level ladder does not allow it	See the ladder rules below.
invalid value for the property’s type	Fix the value (number, date, yes/no).
cell too long	A cell may hold at most 300 characters.
no level column filled in	None of the row’s level columns is filled in — delete the row or enter the path.

All or nothing

The Import runs in a single transaction. If even one row is faulty, nothing is written — you never end up with a half-loaded tree. The report lists the faulty rows by number; fix them and check again. The import re-checks the whole file on the server instead of trusting an earlier result: if the tree changed in the meantime, it decides on the current state.

After a successful import you see “Imported. The tree has been updated.”, and the import leaves an audit trail (file name, fingerprint, counts).

Running it again: the same file twice

The import is idempotent: loading the same file twice gives the same tree — the second run reports 0 new, 0 updated nodes.

The code is the identity. The system looks for the node under its parent, at the same level: by code (case-insensitive) when it has one, otherwise by name. An existing element is never created again.
A code can be added later. If you first loaded the tree with names only and then load the same paths with codes, a coded row is attached to the code-less node of the same name (shown as an update) — no new node is created.
Matching order (for a coded row). 1. by code under the same parent; 2. if there is no such code: the code-less node of the same name gets the code; 3. otherwise a new node is created. Two nodes with the same name but different codes (e.g. two “Pump” nodes: P-91 and P-92) can sit side by side — a fresh file loads both.
Only values that really differ are written. If you change a description or criticality in Excel and load again, the node is updated; the rest stay unchanged. For a node found by code, the name you give replaces the old one.
An empty cell never deletes. The import does not blank existing data — to delete, use the editor in the app.
You can continue in pieces. Pieces loaded one after the other give the same tree as loading everything at once: for a conflicting value the last one applies within a file too, just as it does across two consecutive loads.

Limits

The page shows them up front; the server enforces them:

at most 5000 data rows (the header does not count) — split a bigger file;
at most 80 columns;
at most 300 characters in a cell;
at most 4 MB of file size.

Only a limited number of checks/imports can be started within a short time (5 minutes); if you hit it, try again shortly. Two simultaneous imports into the same site queue up.

The level-ladder rules

The tree is built on the site’s level ladder, and the import obeys exactly the same rules as manual editing:

A child’s level is always deeper than its parent’s. A child at the same or a higher level is an error.
A level may be skipped. A row may jump along the ladder (e.g. from technology straight to position) when the skipped levels’ columns are empty.
There is nothing beyond the end of the ladder. No child can be placed under the deepest level.
No silent re-levelling. If an element already exists in the tree but at a different level than the file says, the import reports an error instead of moving it.
The order of the level columns in the file does not matter: the path is assembled in the ladder’s order, not the column order.

You can edit the ladder on Settings → Levels. A level that is in use cannot be archived — so the structure of a loaded tree cannot be pulled apart.

If it worked

The Check report is clean, the counts match what you expect (new/updated/unchanged), after the Import the number of nodes shown as New appears in the functional-location tree, and checking the same file again shows 0 new, 0 updated.

Common problems

The Import button is grey. The current file has no clean check yet. Run Check; repeat after changing the file or the plant.
“The header has no column matching the site’s level ladder.” None of the level columns could be recognised. Start from the downloadable template and do not rename the level labels.
“The site has no level ladder — set it up on the Levels tab first.” Set the ladder up on Settings → Levels.
The file cannot be read. Upload an xlsx or a UTF-8 CSV file; the extension must match the content.
Every equipment type is “unknown”. Enter the equipment type’s code instead of the name, as on the Guide sheet.
One column’s data did not come in. Probably a mistyped header: the report names it under “Unrecognised columns (skipped)”; fix it according to the template.

Once the tree is in place, the upcoming due dates are shown by the article What is due in the coming weeks: the due-date calendar.