How to import a CSV into a flowchart tool

A worked example, stage by stage

1. The rows arrive in file order

   Four lines of the export become rows 1 to 4: the Start "Land on the site from a campaign or search", then "Record the source, campaign and landing page", the decision "Does the visitor start a trial?" and the End "Left before the trial started". Only Box text and Shape have landed, so there are boxes and no arrows. The row numbers are file order: line 2 of the file is row 1, because line 1 was the header.

2. Line to fills in the arrows

   The Trial rows arrive and the connections come with them. Row 10, "Is the first key action done within 7 days?", holds three numbers in one Line to cell (13, 11 and 12), and row 11, "Send the day-7 setup reminder with a booking link", points back at 9, which is how a loop is written. Those are positions in the file, so re-sorting the export after this column is filled in is what breaks an import.

3. Line text labels each exit

   Row 17, "Does the trial convert before it expires?", pairs Line to "20,18" with Line text "Buys a plan,Expires unpaid", matched by position, first to first. Both columns are comma-separated lists living inside a single field, which is exactly why a CSV writer has to quote them. Unquoted, that label is two fields, and every value to its right lands one column across.

4. The two lane columns

   Horizontal lane carries the journey stage (Awareness, Trial, Activation, Conversion, Retention) and Vertical lane the owner: Customer, Marketing, Product, Sales and Support. Most exports already hold both under other names, as a stage field and an owner field. So the swimlane version of this chart costs one rename in the header line rather than any new data.

How it works

1. Open the file and look at the first line

   Open the .csv in a text editor rather than in Excel, because Excel hides precisely the things that go wrong. The first line has to be the header. Delete a report title, a generated-on line, any blank line above the header and any totals row at the bottom, then save.

2. Rename the headers to the editor's column names

   Shape, Box text, Line to, Line text, Line style, Horizontal lane, Vertical lane, Parallel with, Notes and Link. The names are what is matched, so the order they sit in does not matter and a column you do not have can simply be absent. A header that is not one of those names ("Next step", "Step type") lands as an ignored extra rather than as an error, which is why a missing arrow is nearly always a header problem.

3. Check the delimiter and the encoding

   A file exported by an application set to a European locale is usually semicolon-separated, and it arrives with the whole line sitting in one column. Re-export and choose the comma. Save as UTF-8 while you are there: from Latin-1 or UTF-16, accented and non-Latin labels come through as mojibake, and re-exporting is faster than retyping every label.

4. Quote every field that contains a comma

   Line to and Line text are comma-separated lists inside a single field, so a well-formed file always quotes them: "20,18" and "Buys a plan,Expires unpaid". The same goes for a Box text such as "Approve, then file". An unquoted comma splits the row, and everything to its right lands in the wrong column with nothing to tell you it happened.

5. Drop the file on the spreadsheet area, or paste the text

   Open a new chart, then either drag the .csv onto the spreadsheet area underneath the canvas or paste the CSV text straight into it. No wizard, no column mapper and no field-matching screen appears; the rows appear in the table and the diagram renders from them. If you are unsure about the file, try it in a scratch chart first.

6. Check four things the moment the rows land

   One: the row count equals the number of lines in the file minus the header. Two: row 1 is your first step, not your header text. Three: a Line to number you already know (the one that loops backwards is the easiest to spot) lands on the step you meant. Four: the branch labels sit on the arrows you expect. From then on, edit the table rather than the file.

Frequently asked questions

Is there an import wizard or a column mapper?

No. There are two ways in and each is a single action: drop the .csv onto the spreadsheet area under the canvas, or paste the CSV text into it. Columns are matched by header name, so there is nothing to configure and no field-matching step to get wrong. When a column looks as though it did nothing, the cause is the header name rather than a setting you missed.

Do I have to delete the columns QueryChart does not use?

No. Unrecognised columns are carried and ignored, so an export carrying ticket ids, timestamps, a cost centre and four reporting columns can go in exactly as it came out. Keeping them costs nothing and preserves the link back to where the rows came from. The only column work worth doing first is renaming the ones you do want matched: Box text, Line to, Line text, Shape and the two lane columns.

My file arrived as a single column. What happened?

The delimiter is not a comma. Exports from applications set to a European locale are usually semicolon-separated, and a tab-separated file saved with a .csv extension behaves the same way. Re-export and choose the comma rather than replacing the separator by hand, because Line to and Line text hold comma-separated lists that a blanket replace would destroy. Save as UTF-8 at the same time: a wrong encoding shows up as mojibake in the labels, never as an error.

The rows imported but no arrows appeared.

Line to is either empty or holding something other than row numbers. The usual causes are an export whose next-step column carries the source system's own ids (STEP_014) instead of positions in the file, or a header named something that was not matched, in which case that column landed as an ignored extra. Both are fixed in the table: type the row numbers into Line to and the arrows appear as you go. /csv-to-flowchart shows what a file that works looks like.

Can I re-import the file later to update the chart?

Nothing links the chart back to the file it came from (there is no refresh, no sync and no connector), so importing again is another paste rather than an update. Treat that as a decision made once: after the import the chart is the definition of the process, and the export becomes a snapshot of how it looked that day. If the source data really does change weekly, it is almost certainly a log of instances rather than a definition of steps, and only the steps belong in the chart.