Upload Node Attribute Data to Update Existing Nodes

You have a spreadsheet of values for poles that are already on your map, and you want those values on the nodes without manually adding each one. That is what Upload Node Attribute Data is for.

What is this?

Upload Node Attribute Data takes a spreadsheet and writes the values in it onto nodes that already exist in the job you have open. Each row in your file points at one existing node, and each remaining column becomes an attribute value on that node. It is an update only. It does not create new nodes, and it does not move nodes into sub jobs. If you need to seed brand new locations onto the map, that is Upload Node Data, covered in the Pre-Design Manual.

When would I use it?

• You exported the job, filled in or corrected values in Excel, and want to push the whole sheet back onto the poles at once.
• A client or utility partner sent you a spreadsheet keyed to pole tags, and those values need to land on your nodes.
• A field crew captured something outside Katapult Pro (a permit number, an account ID, an inspection result) and you want it on the matching poles.

What the upload does to your existing values

Read this part before you upload, because it surprises people.

Each attribute you upload replaces the existing attribute. It is not a merge. If a node already has a value for pole_height that came from the field, and your spreadsheet has a pole_height column, the uploaded value takes the place of what was there. Anything else that was stored on that same attribute goes with it.

A blank cell clears the attribute. If a row has your identifier filled in but leaves a column empty, Katapult Pro writes an empty value to that attribute. This is on purpose, so you can blank out a field in bulk. It also means that leaving a cell blank is not a way to skip an attribute. To leave an attribute alone, delete that column from the spreadsheet entirely.

How do I use it?

Prepare your spreadsheet

Save your file as .csv, .xlsx, or .xls.

There are no required columns for this upload, but there is one hard requirement: at least one column has to hold a value that already exists on the nodes in your job (a unique attribute), so Katapult Pro can tell which node each row belongs to. Pole tag, SCID, and latitude and longitude are the usual choices.

Name your other column headers to match the attributes in your job model, in lower case with underscores instead of spaces (for example pole_height, proposed_riser). Headers are matched without regard to capitalization. Anything that does not match an attribute in your model has to be mapped by hand in the next step.

The formatting conventions for each attribute type (dropdowns, checkboxes, tables, dates, pole tags) are the same as they are for Upload Node Data, and the Pre-Design Manual has the full reference with an example file. Three of them come up often here:

• Pole tag uses Company::Tag Text::Owner, three parts separated by double colons. The last part answers whether that company owns the pole, so yes, true, 1, or y all read as owned, and anything else reads as not owned. The company name is corrected against your company picklist automatically.
• Table attributes use table_name::column_name as the header. Several :: columns that share the same table name combine into one multi row table on the node.
• Checkbox attributes read empty, 0, false, f, no, and n as unchecked, in any capitalization. Anything else checks the box.

Two more behaviors worth knowing while you build the file. A leading asterisk on a header, as in *reference_number, writes that value to the job metadata instead of to the node, which is handy for stamping something job wide. And if you deliberately repeat a header, for example two note columns, the second value is stored alongside the first rather than overwriting it.

Drag the file onto the map

With the job open, drag your file from your computer onto the map. The upload dialog opens with a tile for each kind of import: Upload Node Data, Upload Node Attribute Data, Upload Connection Data, Upload Connection Attribute Data, Upload Wire Data, and Custom Import.

Click Upload Node Attribute Data.

Leave the Use address instead of coordinates checkbox unchecked. It appears in this dialog, but it is built for the Upload Node Data path and is not supported for attribute uploads. Match on latitude and longitude, node_id, or one of your own attributes instead.

Fix any unmatched headers

If a header in your file does not line up with an attribute in the job's model, the dialog opens a Fix Headers section and shows Error: Some attributes don't exist in these models. Import stays blocked until every unmatched header is resolved.

You have two ways to clear it: map the header to the right attribute using the dropdown, or leave it unmapped so that column is ignored. If the attribute genuinely does not exist in your model yet, add it in the Model Editor and upload the file again.

Pick your unique identifying attribute column

Next, find the Unique Identifying Attribute Column dropdown, under the heading Select a unique attribute to identify each node. This is how Katapult Pro decides which existing node each row updates, and nothing imports until you choose one.

You have three kinds of choices:

• latitude and longitude. This option appears on its own when your file has both a latitude and a longitude column. A row matches a node when both coordinates land within roughly 1.1 meters of it. Keep in mind that in this mode the coordinates themselves are not updated on the node, even if your file has slightly different numbers. Only your other columns are written.
• node_id. The most dependable identifier, because node IDs are unique inside a job. Most people get them from the Node Attributes with IDs XLSX export of the same job in the Download Manager or from the API, since node IDs are not shown on the map. Latitude and longitude can be updated in this mode.
• Any other column you choose. Pole tag, SCID, an account number, or any custom attribute your company uses. Latitude and longitude can be updated in this mode too. The column you pick as the identifier is used for matching only, so its values are never written onto the node as an attribute.

Read the match results

As soon as you pick an identifier, the dialog reports what it found at the top. Warnings let you continue. Errors do not.

• X nodes are matched and ready to be updated. Your file lined up. Compare that count against the number of rows you expected before you continue.
• No matches were found in the job. Nothing in the column you picked matches any node in this job. Usually the wrong column, the wrong job, or a formatting difference.
• The imported row with column name X and cell value Y does not match any nodes in this job. One specific row could not be placed. The rest of your rows still import.
• ...is matched to more than one node in this job. The value you are matching on is not unique inside the job. Every matching node will be updated with that one row, which is rarely what you want. Pick a more specific identifier.
• A duplicate unique identifying attribute exists. Two rows in your spreadsheet carry the same identifier. The second one wins when it lands on the node. If the message mentions a blank value, one or more rows are missing an identifier.

Add the data to your job

When the match count looks right, click Add to Job. Your values are written to the matched nodes.

Double click one of the updated nodes to open the Node Info panel and confirm the values landed where you expected. If Attribute History is turned on for your company, the panel's Attribute History section shows what the upload changed. See Attribute History: The Basics.

Uploading connection attributes

Upload Connection Attribute Data works exactly the same way, on connections instead of nodes. Everything above applies, with three differences:

• The latitude and longitude option appears when your file has latitude1, longitude1, latitude2, and longitude2 columns.
• You can match on conn_id, which is the connection's own unique ID, the way node_id works for nodes.
• Connections do not carry their own coordinates, so no coordinates are ever updated. They take their position from the nodes on either end.

Tips and troubleshooting

• "I uploaded the file but nothing happened." Almost always the Unique Identifying Attribute Column was never chosen. Add to Job stays disabled until it is. Look for the Select a unique attribute to identify each node section in the dialog and confirm a column is selected.
• The values in my identifier column look right but nothing matches. Check for a formatting difference between the file and the job: extra spaces, different capitalization on attribute values, or leading zeros that Excel stripped out of a pole tag. Then confirm you are in the intended job. It is easy to drop a file into the wrong one.
• My existing values disappeared. Expected behavior, since each uploaded attribute replaces what was there. Restore from a job snapshot if you need the earlier values back.
• I need to update nodes in sub jobs. Attribute upload only touches the job you have open. job_name, job_path, and app_type columns are the sub job routing fields for Upload Node Data, and they are ignored here without a warning. Open each sub job and run the upload there, or use the API.
• Nothing is happening after I check "Use address instead of coordinates." That checkbox is not supported on this path. Leave it unchecked and match on coordinates, node_id, or one of your own attributes.
• Still stuck? Reach out to support@katapultengineering.com with your file and the job name.