Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: ActionableAgile/jira-to-analytics
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v1.0.0
Choose a base ref
...
head repository: ActionableAgile/jira-to-analytics
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: master
Choose a head ref

Commits on Dec 8, 2016

  1. Copy the full SHA
    0d68287 View commit details

Commits on Dec 21, 2016

  1. minor refactor

    johnrjj committed Dec 21, 2016
    Copy the full SHA
    691dc1a View commit details
  2. Copy the full SHA
    9f0a1b9 View commit details
  3. v1.1

    johnrjj committed Dec 21, 2016
    Copy the full SHA
    ab8e58b View commit details
  4. 1.1.0

    johnrjj committed Dec 21, 2016
    Copy the full SHA
    7f0c6c6 View commit details
  5. hotfix

    johnrjj committed Dec 21, 2016
    Copy the full SHA
    7b70a05 View commit details
  6. Taking out console logs

    johnrjj committed Dec 21, 2016
    Copy the full SHA
    078bf5c View commit details

Commits on Dec 22, 2016

  1. Copy the full SHA
    da363cd View commit details
  2. Fixing imports

    johnrjj committed Dec 22, 2016
    Copy the full SHA
    a8dc6c9 View commit details
  3. Renaming types

    johnrjj committed Dec 22, 2016
    Copy the full SHA
    e625f95 View commit details
  4. Moving furniture

    johnrjj committed Dec 22, 2016
    Copy the full SHA
    cfe7596 View commit details
  5. Update README.md

    johnrjj authored Dec 22, 2016
    Copy the full SHA
    405b7c1 View commit details
  6. Minor refactor

    johnrjj committed Dec 22, 2016
    Copy the full SHA
    68de01a View commit details
  7. Copy the full SHA
    09c122b View commit details
  8. Final refactor for 1.2

    johnrjj committed Dec 22, 2016
    Copy the full SHA
    ad9384f View commit details
  9. Bug fix to make immutable

    johnrjj committed Dec 22, 2016
    Copy the full SHA
    b5d9b6e View commit details
  10. Copy the full SHA
    7834284 View commit details

Commits on Dec 25, 2016

  1. Added additional error check

    johnrjj committed Dec 25, 2016
    Copy the full SHA
    77daefa View commit details

Commits on Mar 30, 2017

  1. Update README.md

    ActionableAgile authored Mar 30, 2017
    Copy the full SHA
    fe284e3 View commit details

Commits on Nov 29, 2017

  1. Fix issue fetching

    Dirklectisch committed Nov 29, 2017
    Copy the full SHA
    acdaf9a View commit details

Commits on Dec 7, 2017

  1. Merge pull request #46 from Dirklectisch/45

    Do not ignore offset en batchsize
    johnrjj authored Dec 7, 2017
    Copy the full SHA
    952c6bb View commit details
  2. Add team configuration to config file (#47)

    Add team (project grouping) configuration support to extractor
    Dirklectisch authored and johnrjj committed Dec 7, 2017
    Copy the full SHA
    830a713 View commit details

Commits on Feb 9, 2018

  1. Copy the full SHA
    0160dd5 View commit details

Commits on Apr 25, 2018

  1. Copy the full SHA
    d1f6222 View commit details
137 changes: 78 additions & 59 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,19 @@
# README #


**Please Note:** This tool is offered AS-IS with no implied warranty nor support from ActionableAgile, its partners, or subsidiaries. ActionableAgile has made this utility available via open source in the hope that the community will make contributions to this project in order to improve it. Please do not contact ActionableAgile with any support questions as, unfortunately, we will be unable to help you.

# ActionableAgile Analytics Tool

## Overview ##
The purpose of this software is to extract flow data from Jira and put that data into a proper format for use with the ActionableAgile™ Analytics tool (for more information on the ActionableAgile™ Analytics tool, please visit [https://www.actionableagile.com](https://www.actionableagile.com) or sign up for a free trial of the tool at [https://www.actionableagile.com/cms/analytics-free-trial-signup.html](https://www.actionableagile.com/cms/analytics-free-trial-signup.html).)
The purpose of this software is to extract flow data from Jira and put that data into a proper format for use with the ActionableAgile™ Analytics tool (for more information on the ActionableAgile™ Analytics tool, please visit [https://www.actionableagile.com](https://www.actionableagile.com) or sign up for a free trial of the tool at [https://www.actionableagile.com/cms/analytics-free-trial-signup.html](https://www.actionableagile.com/cms/analytics-free-trial-signup.html).)

This program reads in a well-formed config file (see The Config File section below), connects to Jira and extracts data using the Jira REST API according to the parameters specified in the config file (see the Extraction Procedure Section below), and writes out a CSV file or JSON file that can be directly loaded into ActionableAgile™ Analytics (see The Output File section below).
This program reads in a well-formed config file (see The Config File section below), connects to Jira and extracts data using the Jira REST API according to the parameters specified in the config file (see the Extraction Procedure Section below), and writes out a CSV file or JSON file that can be directly loaded into ActionableAgile™ Analytics (see The Output File section below).

## Installation
There are two options for running this extract utility: either as a standalone exectuable or as a nodejs app.

#### Option 1: Using the Standalone Executable
Download the "jira-to-analytics.exe" and the "config.yaml" files from the releases page for this repository (https://github.com/actionableagile/jira-to-analytics/releases) and put both files in the same directory. Which local directory you choose doesn’t matter as long as the two files are co-located.
Download the "jira-to-analytics.exe" and the "config.yaml" files from the releases page for this repository (https://github.com/actionableagile/jira-to-analytics/releases) and put both files in the same directory. Which local directory you choose doesn’t matter as long as the two files are co-located.
> NOTE: This executable file will work regardless of what operating system you are using.
Edit the config file and customize it for your specific Jira instance according to the instructions in this README. Open a command prompt and run it by simply typing ```jira-to-analytics.exe``` (no additional command line parameters are needed to test the app at this point, though you can add additional command line parameters as detailed below). If the program succeeds, the output data file will be written in the same directory as the executable file.
@@ -22,7 +24,7 @@ Edit the config file and customize it for your specific Jira instance according
Download the "jira-to-analytics.js" and the "config.yaml" files from the releases page for this repository (https://github.com/actionableagile/jira-to-analytics/releases) and put both files in the same directory. Which local directory you choose doesn’t matter as long as the two files are co-located. Edit the config file and customize it for your specific Jira instance according to the instructions in this README. Open a command prompt and run it by simply typing ```node jira-to-analytics``` (no additional command line parameters are needed to test the app at this point, though you can add additional command line parameters as detailed below). If the program succeeds, the output data file will be written in the same directory as the javascript file.

## Using the Application
> NOTE: There has been an update to the YAML file format. Please see the [config.yaml][config-yaml] file to see an example of the new schema. For those that wish to continue to use the old version of the schema, please enable the legacy flag (```--legacy```).
> NOTE: There has been an update to the YAML file format. Please see the [config.yaml][config-yaml] file to see an example of the new schema. For those that wish to continue to use the old version of the schema, please enable the legacy flag (```--legacy```).
##### Configurable settings/flags
These flags are the same whether you are using the standalone executable or node form of the extraction tool.
@@ -31,32 +33,32 @@ These flags are the same whether you are using the standalone executable or node

```-o``` specifies output file name (must end with .csv or .json, defaults to data.csv)

```-l``` or ```--legacy``` will enable the old version of the YAML (from the GO version of the application).
```-u``` specifies the username for the connection to Jira (by default the username in the config.yaml is used)

```--leankit``` will switch the extract source to LeanKit.
```-p``` specifies the password for the connection to Jira (by default the password in the config.yaml is used)

```--leankit --setup``` will start a smart wizard to generate the LeanKit configuation file
```-l``` or ```--legacy``` will enable the old version of the YAML (from the GO version of the application).

For example, to run the node version of the tool with a legacy config file named myconfig.yaml and exporting data to mydata.csv:

```node jira-to-analytics -i myconfig.yaml -l -o my.csv```
```node jira-to-analytics -i myconfig.yaml -l -o my.csv```

Or as another example, to run the exe version of the tool without a legacy config file named myconfig.yaml and exporting data to mydata.csv:

```jira-to-analytics.exe -i myconfig.yaml -o my.csv```
```jira-to-analytics.exe -i myconfig.yaml -o my.csv```


##Config File##
## Config File ##
In order for this utility to run properly, you must create a config file that contains the parameters of your Jira instance, and the necessary details of your workflow. The config file is what tells the executuable what Jira instance to connect to, what data to grab, and how to format the resultant file to be uploaded into the ActionableAgile Analytics tool.

The config file we use conforms to the YAML format standard (http://yaml.org/spec/) and is completely case sensitive. You can find an example config file here: [https://github.com/ActionableAgile/jira-to-analytics/blob/master/typescript/config.yaml](https://github.com/ActionableAgile/jira-to-analytics/blob/master/typescript/config.yaml). Feel free to follow along with that example as we run through the details of each section of the file.

The file itself is broken up into the four sections:
The file itself is broken up into the four sections:

Connection
Criteria
Workflow
Attributes
Connection
Criteria
Workflow
Attributes

### The Connection Section ###
The Connection Section of the config file is simply named "Connection" (without the quotes). Each line of the this section contains the name of a connection property followed by a colon (:) followed by the required value. This section has two required fields:
@@ -71,21 +73,21 @@ And one optional field:
An example of what this section might look like is:

```
Connection:
Domain: https://www.myjiradomain.com
Username: MyUsername
Password: MyPassword
Connection:
Domain: https://www.myjiradomain.com
Username: MyUsername
Password: MyPassword
```

#### OAuth Support
OAuth is now supported. You must get the access token and access token secret on your own by completing the OAuth authorization.
OAuth is now supported. You must get the access token and access token secret on your own by completing the OAuth authorization.

This application's OAuth configutation requires five inputs:
Domain, Consumer Key, Private Key, Token, and Token Secret:
**Domain**: The url to the domain where your Jira instance is hosted
**Consumer Key**: This is the user-specified application key inside JIRA
**Private Key**: Your private key for the JIRA OAuth
**Token**: OAuth Access Token
Domain, Consumer Key, Private Key, Token, and Token Secret:
**Domain**: The url to the domain where your Jira instance is hosted
**Consumer Key**: This is the user-specified application key inside JIRA
**Private Key**: Your private key for the JIRA OAuth
**Token**: OAuth Access Token
**Token Secret**: OAuth Access Token Secret

```
@@ -106,7 +108,7 @@ Connection:
### The Criteria Section ###
The Criteria Section of the config file is simply named "Criteria" (without the quotes) and contains optional Jira attributes that can use to control your data set. Each line in this section contains the name of the Jira attribute you want in your data followed by a colon (:) followed by its corresponding value in your Jira instance. The fields in this section that we support are:
- Projects: a list of the names of the Jira Projects you are querying
- Project: a list of the names of the Jira Projects you are querying
- Types: a list of the names of the Jira issuetypes you want to extract
- Filters: a list of the names of the filters you want to apply
- Start Date: a date filter in the format YYYY-MM-DD which will exclude issues with resolved dates before the provided date (optional)
@@ -115,19 +117,19 @@ The Criteria Section of the config file is simply named "Criteria" (without the
An example of what this section might look like would be:
```
Criteria:
Project:
Criteria:
Project:
- My Project1
- My Project2
Filters:
- My Project2
Filters:
- Filter1
- Filter2
Issue types:
Issue types:
- Epic
- User Story
Start Date: 2001-01-23
End Date: 2019-12-30

```
>NOTE: The fields in this section are optional
@@ -140,41 +142,41 @@ Dev: Development Active, Development Done, Staging
will tell the software to look for the Jira statuses "Development Active", "Development Done", and "Staging" and map those statuses to a column in the output data file called "Dev". The simplest form of this section is to have a one-to-one mapping of all Jira statuses to a corresponding column name in the data file. For example, assume your Jira workflow is ToDo, Doing, Done. Then a simple Workflow section of the config file that produces a data file that captures each of those statuses in a respectively named column would be:
```
Workflow:
ToDo: ToDo
Doing: Doing
Workflow:
ToDo: ToDo
Doing: Doing
Done: Done
```
Sometimes Jira issues are created with a certain status, and there is no event that corresponds to a move into that status, so there is no date at which the work item entered the corresponding workflow stage. You can designate that an item be created in a certain workflow stage by adding (Created) to the list of Jira statuses. For example, in the previous example if you wanted to designate that items enter the ToDo workflow stage when they are created, you would change the workflow section of the config file as follows:
```
Workflow:
Workflow:
ToDo:
- ToDo
- (Created)
Doing:
- Doing
Done:
- ToDo
- (Created)
Doing:
- Doing
Done:
- Done
```
Again, please refer to the sample config file for an example of what the workflow section looks like.
Again, please refer to the sample config file for an example of what the workflow section looks like.
>NOTE:: The Workflow section requires a minimum of TWO (2) workflow steps, and the names of the workflow steps must be specified in the order you want them to appear in the output CSV. The expectation is that all Jira issue types that are requested will follow the exact same workflow steps in the exact same order.
### The Attributes Section ###
The Attributes Section of the config file is simply named "Attributes" (without the quotes) and is another optional section that includes name-value pairs that you want included in your extracted data set. They may be Jira custom fields that are unique to your Jira instance, or certain standard Jira fields that we support. Each line in this section contains the name you want to appear as the attribute column name in the CSV file, followed by a colon, followed by the name of a Jira custom field or a supported standard field, like this:
- CSV Column Name: ID of the custom field
- CSV Column Name: ID of the custom field
- CSV Column Name: Supported field name
If the returned JSON contains an array, the content of each element is extracted normally. If there are multiple non-empty values, all the values are joined with an escaped comma and surrounded by square brackets like this: [red\,green\,blue]
Here are the standard Jira fields that you can use:
Here are the standard Jira fields that you can use:
- status
- issuetype
- priority
@@ -187,23 +189,40 @@ Here are the standard Jira fields that you can use:
An example of what this section might look like is:
```
Attributes:
Team: customfield_10000
Regulatory Requirement: customfield_10001
Status: status
Type: issuetype
Level: priority
Attributes:
Team: customfield_10000
Regulatory Requirement: customfield_10001
Status: status
Type: issuetype
Level: priority
```
These fields will show up as filter attributes in the generated data file (please visit [https://www.actionableagile.com/format-data-file/](https://www.actionableagile.com/format-data-file/) for more information).
>NOTE:: None of the fields in this section is required--in fact, this section as a whole is optional.
### Teams ###
The teams section of the config file allows you to assign projects keys to team names, which can then be filtered on in the application.
An example of what this section might look like is:
```
Teams:
TeamOne:
- ABC
- EFG
TeamTwo:
- HA
- HE
- HO
```
### Advanced Settings ###
The extraction tool also supports more customization and extensibility.
The extraction tool also supports more customization and extensibility.
To enable this, add an more additional section to your JIRA config:
To enable this, add an more additional section to your JIRA config:
```
Feature Flags:
```
@@ -212,7 +231,7 @@ Feature Flags:
```MaskName```: Masks the 'name' of your JIRA stories, for when JIRA stories contain sensitive data. To turn this feature on, add the following code to your Feature Flags section:
```
MaskName: true
MaskName: true
```
As an example, a config with the MaskName feature flag enabled would look like:
@@ -222,7 +241,7 @@ Feature Flags:
```
##### For a complete config example, please see the provided sample config.yaml #####
### LeanKit Automatic Configuration
Run the tool with the --leankit and --setup flags
@@ -237,12 +256,12 @@ The program will read in the properly formatted config file (see The Config File
If all goes well, the extraction program will write out a CSV or JSON file that contains all extracted data to the same directory where the program is running.
## Output File ##
If successful, the output data file will be written in the same directory in which this utility was run. The output file follows the format required by the ActionableAgile Analytics tool as specified here: [https://www.actionableagile.com/format-data-file/](https://www.actionableagile.com/format-data-file/).
If successful, the output data file will be written in the same directory in which this utility was run. The output file follows the format required by the ActionableAgile Analytics tool as specified here: [https://www.actionableagile.com/format-data-file/](https://www.actionableagile.com/format-data-file/).
If the output file is a CSV file, it can be loaded directly into the ActionableAgile Analytics tool from the Home tab using the Load Data button.
### Version
1.1.1
### Version
1.1.1
### Todos
@@ -257,7 +276,7 @@ MIT
[//]: # (These are reference links used in the body of this note and get stripped out when the markdown processor does its job. There is no need to format nicely because it shouldn't be seen. Thanks SO - http://stackoverflow.com/questions/4823468/store-comments-in-markdown-syntax)
[config-yaml]: <https://github.com/ActionableAgile/jira-to-analytics/blob/master/typescript/config.yaml>
[config-yaml]: <https://github.com/ActionableAgile/jira-to-analytics/blob/master/config.yaml>
[mocha]: <https://mochajs.org/>
[typescript]: <https://www.typescriptlang.org>
[repo]: <https://github.com/ActionableAgile/jira-to-analytics/>
Loading