Uploading CSV or Excel Data

Uploading a CSV or Excel Data file is just one of many options for loading data into ActionableAgile Analytics.

Uploading the file

You begin by navigating to the Data icon in the top right of the gray navigation bar. When you click on the icon, the first option will be “Excel or CSV File”

Open

After you click on the item in the dropdown, a window with a drop area will appear:

Option 1: drag and drop your file

Open

Option 2: click in the drop area and your file browser will open

File type check

We have now added a file type check, this means that if the file you are trying to load is not supported, ActionableAgile will show the below warning and error messages:

• Missing fields: the frame will turn red and a cross will signal that the file is incorrect. An error message will be displayed to explain why the file cannot be loaded. To fix the file, check the section: File Format Requirements.
  
  

• Configuration error: if the file contains unsupported files or the dates are incorrect (ie. backward flow), the items won’t be loaded.

  You can find more information in the header and in the source data chart in the error view. To fix the file, check the section: File Format Requirements.

File Format Requirements

We accept xlsx (Excel 2007 or later) as well as properly formatted .csv (comma separated) files. If using an xlsx file, the data must be located on the first worksheet of the Excel workbook and the workbook cannot contain any extraneous non-empty worksheets. If using a .csv file, the file must conform to the CSV format: https://datatracker.ietf.org/doc/html/rfc4180 .

Both file types must also conform to the following data formatting rules:

• The first row of any file must be the column names for each of the data fields. Column titles cannot have new lines, unclosed quotes, or special characters.

• The first column must be an item ID field and must have uppercase “ID” somewhere in the column name.

• The second column is optional, but if included, it must be called “link” and must contain a hyperlink. This hyperlink could be to the item’s location in your Agile tool. If you don’t have this information in your data, add an empty column with the name “link”.

• The third column is optional, but if included, it must be the item’s title (or name or description) field and must have the word “title” or “name” somewhere in the column name.

• The next set of contiguous columns must be the sequential steps of your workflow. The contents of these columns are the date the item entered each workflow step. A backlog step is optional, but if you include it, it must be the first column of your workflow, and it must have the word “backlog” somewhere in the column title. See the section below labeled “Workflow Stages” for more information.

• You can have any number of generic columns after the workflow steps. If included, each of these columns will be treated as an “attribute” field that can be filtered on (e.g., work item type, project id, team name, etc.).

  • Right now, to allow the app to differentiate between generic attributes and workflow steps, the first of these columns should NOT be a date column. We are looking to make this unnecessary in future.

  • If you include a column that will contain an array of values like labels or components, please use a pipe separator. eg. “[label1|label2|label3]” so that we can properly separate them into individual values in the Item Filter.

• Blocked time, for ActionableAgile to give you insights on your blocked time you need to make sure to add 2 columns (see example below in the data extract):

  • Blocked days (only take in consideration full days, if an item was blocked and unblocked on the same day, it will not be taken into consideration in the calculations)

  • Blocked (yes if currently blocked, no if not currently blocked)

Here’s a tabular description of the instructions above:

Here is an example of ActionableAgile export:

Workflow states

Any workflow stages named “Backlog” & “To do” will be immediately identified as “Not started” stages (they will be unchecked by default in the global chart control Workflow Stages. If those are not found then it will not identify any “Not started” stage by default. You can override this default by unchecking the desired workflow stages in the Global Chart controls.

The last workflow stage will be considered the “Done” workflow stage by default.

All other workflow stages will be considered as “In Progress”. ActionableAgile currently requires two or more of these workflow stages. For example:

If you only have three total workflow stages including a “Not Started” workflow stage and it doesn’t make sense to add another In Progress workflow stage, you’ll need to change the name of the 1st workflow to be something other than “Backlog” or “To do” as below:

Additional Tips

Remove any unnecessary columns like these

• Long-form text fields like Descriptions, comments. These aren’t very usable in ActionableAgile and can break your file format easily.

• Fields that you won’t use for filtering. They just add clutter and possibilities for breaking your file format.

If you are using Excel for your data file, there are a few things you may want to consider:

• We recommend that you use minimal formatting for your file. Things like freezing panels, hiding rows, hiding columns, etc. can from time-to-time cause problems with the data load process.

• If you ever do have problems loading your file, then remember that you can always save your Excel file as a CSV and upload the CSV. This approach fixes many of the formatting errors mentioned above.

Here’s a picture of what the Excel file might look like:

Backward flow movement

The dates in the file should always increase to reflect a left to right movement in your flow. However, an item might have been moved prematurely and went back on your board, this is what is called “backward flow movement”. If an item is moved backwards in the flow, let’s say from step C to step B, it is considered never to have been in step C at all. All of the time in step C will be added to the time in step B. It will get a new timestamp for step C when it reenters that workflow stage.

In the example below, you can see that the dates in red are older than the date on their right which shows backward flow movement:

If you load your data as shown above, you will receive this warning message by ActionableAgile:

In this case, you need to correct your file and change the dates, to reflect the last time it moved to each stage.

Template Files

A template file that can be modified for your own data

Excel

Open

CSV

Open

The tool’s demo sample data

Excel

Open

CSV

Open