Loading External Data

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

 

 

Uploading the file

You begin by navigating to the header and open the Data Set dropdown. You can then click on “Load External Data”.

The below drag and drop window will then open with 2 loading options:

Loading options

Option 1: drag and drop your file

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:

Option 1: Drag and Drop

  • Non-supported format: the frame will turn red and a cross will signal that the file is incorrect. The file won’t be uploaded.

 

Option 2: File browser

  • Non-supported format: you won’t be able to select the file, it will be greyed-out

  • 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

The best way to get the acceptable file format for your Jira data is to load a Jira project, board, or filter and then export the raw data via CSV format. That way you will know what format the tool expects.

However, if you’d like to create your own from scratch, it must conform to the CSV format: https://datatracker.ietf.org/doc/html/rfc4180. It 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.

  • 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 are adding 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:

    • 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:

ID

link

title

<workflow steps>

<additional columns>

ID

link

title

<workflow steps>

<additional columns>

required

optional

optional

required.
create one column for each workflow step in linear order. The name of the columns will be the name of the workflow stages.

optional
columns representing different attributes of your work. Each column will be a select list in your item filter global and chart controls.

Arrays should be pipe delimited (value|value)

Here is an example from a Jira extract:

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:

TO DO

DOING

RELEASE READY

RELEASING

DONE

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:

TO DO NOT STARTED

DOING

DONE

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.

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.

For more details, read the blogpost dedicated on this subject: Moving card backward on your Kanban board

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.

Sample Files

The tool’s demo sample data

A template file that can be modified for your own data