How to structure a CSV file for flowcharts
How to structure a CSV so it imports as a flowchart: the header row first, header names matched instead of column positions, one row per step, and the delimiter, encoding and quoting rules that decide whether it parses at all.
A CSV becomes a flowchart when its first line is a header row naming QueryChart's columns, every line under it is one step, and the file is comma-delimited UTF-8 with any field containing a comma quoted.
The short version
- The header row must be the first line of the file, not the third, under a report title.
- Header names are matched, not column positions; unrecognised columns are carried and ignored.
- One row per step, not one row per record. An export is usually a log, not a definition.
- Comma-delimited UTF-8. A semicolon file from a European locale arrives as a single column.
- Quote any field containing a comma, a quote or a newline; write a literal quote as two quotes.
The file is the interface, so the file has to be right
CSV is not a spreadsheet. It is a plain text file with one line per row and a delimiter between fields, and it carries no cell types, no formatting, no formulas and no second tab. That is why every system exports it: a helpdesk, an ERP, an HR system and a database console all produce one, and none of them agree on much beyond the commas. It is also why an import either works immediately or fails in a way that looks like nothing happened.
QueryChart reads the file by header name. The first line has to be the header row, and the names on it are matched against the editor's own columns (#, Shape, Box text, Line to, Line text, Horizontal lane, Vertical lane) rather than against positions, so the order of your columns does not matter and a column QueryChart does not recognise is carried along and ignored. Drop the .csv onto the spreadsheet area of a chart, or paste the rows in. There is no import wizard and no column-mapping screen to work through, which is the trade: the mapping lives in your header row instead of in a dialog.
The rest is the part people lose an afternoon to, and none of it is about diagrams. A file saved on a machine whose list separator is a semicolon is not a comma-separated file. A field holding a comma has to be quoted or it becomes two fields. A byte order mark is invisible in every editor and still rides along on the first header name. A step reference of 007 comes back from a spreadsheet round trip as 7. These are file problems, and they are worth fixing before you think about shapes at all; /guides/how-to-define-flowchart-connections-in-csv covers what goes in the connection columns once the file itself parses.
The example below is a support ticket triage exported the right way: eighteen rows, one per step, built up column by column. Read it as a file rather than as a picture: the diagram is what you get when the columns are right, not what you have to work at. If you want a file that is already correct to copy the structure from, take one from /templates/csv.
One CSV, read column by column
A support ticket triage as eighteen rows. Open the spreadsheet panel to see which column of the file each stage fills in.
Header row and one line per step
The first line of the file names the columns; every line under it is one step. Rows 1 to 6 run from "Submit a ticket" to "Set the priority from impact and urgency", each on its own line with nothing but a label. This is the minimum a file needs to import at all, and it is also the point at which most exports are already wrong, because they hold one line per ticket rather than one line per step.
The Shape column
Shape is a value the parser matches, so it is spelled exactly: Start on row 1, Process on row 2, Decision on rows 3, 5, 7 and 9. "Enough detail to work the ticket?" and "Did the fix work?" are diamonds because the cell says Decision, not because of the question mark. A value the parser does not recognise falls back to Process silently, which is how a decision ends up rendered as a rectangle with its branch labels still attached.
Line to and Line text, quoted
Row 5, "Reply received before the chase window closes?", has Line to 6,18 and Line text "Reply received,No reply": two lists paired by position, both of which contain a comma, so both fields are quoted in the file. Row 13's Box text, "Fixed, or working around it?", is quoted for the same reason: the comma belongs to the label, not to the format. Strip those quotes and the row gains a field and the whole line shifts one column to the left.
Lane columns and the finished file
The last two columns are matched by name like every other one: Horizontal lane carries Raise, Triage, First line, Escalation and Close, Vertical lane carries Requester, Service desk and Specialist team. With them filled in the same eighteen lines render as a swimlane diagram, ending at "Ticket closed" on row 17 and "Closed, no reply from the requester" on row 18. Nothing about the file changed except two more columns of plain text.
How it works
Export one plain table
Whatever system the data comes from, export the grid and nothing else. Report titles, a date stamp, a logo line, merged headings, subtotal rows and a trailing blank line all end up as lines in the file, and every one of them is read as a step. If the export has a "raw data" or "unformatted" option, that is the one.
Make the header row line one
Open the file in a text editor rather than a spreadsheet and look at the first line. It must be the header. Exports that begin with two or three metadata lines are common enough that this is the first thing to check, and deleting those lines is the whole fix.
Rename the headers to QueryChart's column names
Set the header cells to Shape, Box text, Line to, Line text, Horizontal lane and Vertical lane. Matching is by name, so the columns can be in any order and you can leave your own columns (ticket id, system, cycle time) in the file untouched; they are carried and ignored rather than rejected.
Collapse the rows to one per step
An export is normally a log: one line per ticket, per order, per case. A flowchart needs one line per distinct step, so pivot or de-duplicate first and keep the volumes for later analysis. A file with four thousand lines is a data set, not a process, and importing it produces four thousand boxes.
Number the steps and fill in Line to
Line to holds the 1-based position of the destination line, counting the data lines only, so the first step under the header is 1. It is not the ticket id, the step code or anything from the source system. Where a step leads to two places, put both numbers in the one field separated by a comma and quote the field.
Fix the delimiter and the encoding, then drop the file in
Save as comma-delimited UTF-8, then drop the .csv onto the spreadsheet area of a new chart. Read the first render as a check on the file: the row count should match your step count, and every column should have landed where you expect. A file that arrives as one wide column is a delimiter problem, not an import failure.
Mistakes to avoid
A semicolon file with a .csv extension
On a machine whose regional list separator is a semicolon, "Save as CSV" writes semicolons and the file still ends in .csv. It arrives as one column with every value inside it. Re-export with commas, or replace the separators in a text editor before importing.
The header row is not the first line
Report exports habitually put a title, a date range and a blank line above the data. QueryChart reads line one as the header, so those lines become the column names and your real header becomes a step. Delete everything above the header.
A comma inside a branch label
Quoting protects a field from the CSV parser, but Line text splits on commas itself in order to pair labels with destinations. A branch labelled "Yes, with approval" therefore becomes two labels no matter how it is quoted. Rename the branch instead: short labels are better on a diagram anyway.
Leading zeros and long numbers after a round trip
CSV has no types, so whatever you open it in decides. Open and re-save in a spreadsheet and 007 becomes 7, a sixteen-digit reference becomes 4.12346E+15 and 3/4 becomes a date. Edit the file in a text editor, or import the column as text, and check the values that were codes rather than numbers.
Import your CSV as a flowchart
Open the support triage example, download its CSV to see the exact column names and quoting, then drop your own file over it.
Related guides
Drawing quantities instead of steps?
Flowchart CSVs describe steps and connections. If your columns are source, target and value, you have the data format for a Sankey diagram instead.
Frequently asked questions
Does the column order in my CSV matter?
No. Matching is on the header name, so Box text can be the fourth column and Shape the last. What matters is that the names are the ones the editor uses (Shape, Box text, Line to, Line text, Horizontal lane, Vertical lane) and that they sit on the first line of the file. Columns QueryChart does not recognise are carried along and ignored, so there is no need to strip your ticket ids, systems or timings out first.
Which delimiter and encoding should the file use?
Commas and UTF-8. Semicolons are the usual failure: on a machine with a European list separator, Excel's "CSV" is semicolon-delimited, and the file then imports as a single column. Encoding shows up as mangled accented characters: save as "CSV UTF-8" rather than plain CSV. If every column maps except the first one, suspect a byte order mark: it is invisible in an editor but it is attached to the first header name, so that name no longer matches.
How do I write a field that contains a comma?
Wrap the whole field in double quotes: "Fixed, or working around it?". A literal double quote inside a quoted field is written as two quotes. Line breaks inside a quoted field are legal too, though a box label rarely needs one. The two connection columns almost always need quoting, because "6,18" and "Reply received,No reply" both contain the delimiter by design: that is what pairs the labels with the destinations.
My export has one row per ticket, not one row per step. Can I use it?
Not directly. A transaction log describes what happened thousands of times; a flowchart describes what is supposed to happen once. Reduce it to the distinct steps first (a pivot on the activity or status column is usually enough) and keep the volumes separately, because they are the interesting half of a process analysis. /guides/how-to-convert-csv-to-process-map walks through that reduction on an export of exactly this shape.
Which columns are actually required?
Box text alone will import: you get a column of unconnected boxes. Add Line to and it becomes a flowchart, because that is the column holding the relationships. Shape, Line text and the two lane columns are refinements: decisions rendered as diamonds, branches labelled, steps assigned to phases and owners. If you would rather start from a file that is already structured correctly, the sets at /templates/csv are downloadable CSVs of working charts.