This part of the wiki describes processes and functionalities of Epicflow system integration with JIRA.

All topics are set in step by step order to make process of integration intuitive and native.

JIRA account creation

As a first step JIRA account for integration with Epicflow must be created. User should posses read and write rights to the defined projects for import into Epicflow and additionally rights to operate with API.

A permission can be granted to a group, project role, or issue role that the user is a member of, or granted directly to a user. For additional information about different approaches please refer to official JIRA documentation.

The most common permissions are:

• Administer the Cloud site: Users in the site-admins group have this permission.
• Administer Jira: Granted by the Jira Administrators global permission. Users in the administrators group have this permission.
• Administer a project in Jira: Granted by the Administer projects project permission for a project. This can be granted to a user, a group, a project role, and more.
• Access a project in Jira: Granted by the Browse projects project permission for a project. This can be granted to a user, a group, a project role, and more.
• Access Jira: Granted by the Jira Users global permission. Users in the [product]-users (for example, jira-software-users) group have this permission.

For additional information please refer to official documents regard Manage groups and Managing global permissions for details.

Account creation can be performed with the next set of rights:

Admin rights

• Log in with the administrator account to the JIRA environment
• Go to Site administration and Invite user by selecting corresponding button at the top right corner, located at Users page of USER MANAGEMENT block.
• If it’s applicable for you, select the products from the Application access list that it should have access to. In this case, at least choose Jira Core.
• Specifies next set of groups:
  • administrators
  • site-admins
  • jira-developers
  • jira-users
  • users
•  Specify separate email for the user
• Click Invite user and proceed with invitation email to accomplish user creation.

Read-write rights

The difference to the previously described option will be only in the scope of set groups:

• jira-developers
• jira-users
• users
• <other groups> specially created to define read-write access to the projects prepared for the import into Epicflow system.

Read rights only

For this approach you would need to define only a set of

• <other group(s)> specially created to define read access to the projects prepared for the import into Epicflow system.

In case of necessity to use Epicflow system in configuration when it doesn’t write anything back to JIRA and has only one way synchronization from JIRA to Epicflow, please communicate with Epicflow team to proceed with it. A special mode can be activated for such needs.

 

API Tokens

API tokens is the must for JIRA authentication usage when configure connection between Epicflow and JIRA system.

For two steps verification  REST API token must be used.

Create an API token

To create an API token

• Log in to your JIRA environment https://<Company_Name>.atlassian.net
• Go to your Profile by selecting “Profile” option in context menu appearing on left mouse click over your Account Icon at the left bottom corner.
• Click over “Atlassian account” link to be redirected on “Manage your account” page and select “Security” tab.

Screen #1 – JIRA-API token creation

• In API token chapter select “Create and manage API tokens” and as soon as you are at “Manage your account” -> API tokens confirm token creation by left click over “Create API token” button.

Screen #2 – JIRA-API token creation

Screen #3 – JIRA-API token creation

• After label identification your system will grant you token which you would need to use for the Import.

JIRA scope Filter

As a step of preparation you would need to create a filter (query) in JIRA to define the scope of projects, epics and tasks defined for the Import itself.

• Log in to the JIRA environment with previously created account.
• Choose the JIRA icon “Issues and filters”
• Select “Search issues”
  • If basic search is shown instead of advanced search, click Advanced (next to the icon).
• Enter your JQL query. As you type, Jira will offer a list of “auto-complete” suggestions based on the context of your query.
  • Note, auto-complete suggestions only include the first 15 matches, displayed alphabetically, so you may need to enter more text if you can’t find a match.
• Press Enter or click to run your query. Your search results will display in the issue navigator.

To limit the scope and decrease the load on your system we would recommend to use query similar to the next one:

category = Epicflow AND NOT updatedDate < “YYYY/MM/DD”

where “YYYY/MM/DD” defines period not higher than one year.

Please note that category should be defined and set separately.

• Save you filter by pressing “Save As” button located above the inserted JQL query.
  • Note, if you have used any different account than that which is going to be used for the Import you would need to share your filter with it. For that
    • go to the Filters list and locate your previously stored JQL query filter.
    • select “Edit filter details” from the context menu at the right side in-front of the current filter.
    •  share your filter with required user, group or project and save.

For additional information please refer to official JIRA documentation regard JQL(JIRA Query Language).

First data Import

• Before start, please, verify with your Epicflow System Administrator that your account has required permissions to access and configure Import page.
• Login into Epicflow system and navigate to the menu item “Import”, which is located at the bottom part of the left menu column. You’ll be automatically redirected to the Connection configuration page.

Connection

Screen #4 – JIRA – Connection

• At first Step you have to specify your Jira Instance, Username, and JIRA token and press “Next” button.
• At a next step, you have to configure and define Scope and Projects.

 Scope and Projects

Screen #5 – JIRA – Scope and Projects

Bellow you’ll find description for all settings of this configuration part.

• Jira Scope – select previously created JIRA Scope Filter.
  • Note, that selection of the “Whole Jira Scope” option will force the system to work with whole set of available data, which is NOT RECOMMENDED. In such way you create unnecessary load on Epicflow and JIRA systems. Even if you would like to import everything from JIRA it will be better to limit amount of data to the last year via separate filter creation. 
• Project Field Mapping – defines what you would like to have as a project in Epicflow: 
  • Project – Each separately created project in JIRA will be imported as a Project to the Epicflow
  • Epic – Each Epic will be presented as a separate project in the Epicflow
  • Query – Each selected query will be defined as a separate project in the Epicflow

• If you put a tick on Automatic Import, the system will automatically import any newly appeared projects from the defined scope if related projects have no shared tasks between projects. Be aware, that in case you have unchecked any Project in the Projects list (despite the automatic import button is on), the project won’t be imported to the system neither now, not later automatically, unless it’s selected again.
• On pressing “Expand” text, to the right side from the “Field Mapping” label, Epicflow will expand additional block with the advanced configuration settings. All settings are grouped into the separate blocks:
  • “Common fields” – defines set of parameters used for mapping of appropriate fields in JIRA to particular fields in Epicflow system. Usually you don’t need to change them. 
    • ID – defines which parameter (Key or ID) will be used as a primary ID in Epicflow
    • Name – defines name of the issue which can be either ID or Key or Summary or Description etc.
    • Notes – usually this field contains Description but again you can redefine it accordingly.
    • Task Predecessors – defines type of connection used to define link between issue and its predecessor. By default it’s “blocks” but a multiple one can be selected in case of need.
    • Tags – only one possible option – “Labels”. Used for budget tasks identification.
  • “Task Fields” – next block of parameters defines mapping for values which should be used as Original and Remaining work 
    • Original Work – Original Estimate is a default setting which shouldn’t be changed
    • Remaining Work– Remaining Estimate is a default setting which shouldn’t be changed
  • “Parent field” – here you can defines parameters which must be accepted as a Start Date of the Project or End Date.
  • “Milestone fields” – additionally to the previous block you can also set milestones’ parameter.
  • “Compound task fields” – if you are using multiple assignment for one issue with identification of different roles required to finish the task you may use this part to configure such relation and work separation between two defined assignee.
    • Compound issue type – defines type of issue (Bug, Sub-task, Task, etc.) which need to be processed as compound task (separated accordingly into two related tasks)
    • Second assignment field – usually as a second assignee QA engineer is defined.
    • Work ratio – defines ratio of work between first and second assignee. In result initial estimation will be divided accordingly to the defined value (30, 40, 50, 60 or 80)
    • First assignment done status – defines status of the issue when first assignee has finished his part and second assignee should be involved.
    • Second assignment done status – defines issue status when all work is done and issue is accomplished.
    • First Assignment prefix – special prefix, automatically added to the task name, used to identify compound task of the first assignee in Epicflow system.
    • Second Assignment prefix – special prefix, automatically added to the task name, used to identify compound task of the second assignee in Epicflow system.
    • Work – this parameter is used to define field which is used for estimation of Compound tasks. It could be or Story points or Task progress or compound issue estimation parameters.
    • Time unit – unit of measure: hours, minutes or seconds
    • Second assignment group field – if any field is used for the second assignment group identification you can configure it here.
    • Default group for second assignment – Group name from JIRA which must be used in Epicflow for the second assignment
  •  “Budget fields” – part for budget tasks configuration. Please refer to Budget section for additional information regard topic
    • Enable budget processing – deselecting this field will switch off budget processing for the whole list of projects but you can switch it on later in Project Card for a specific project.
    • Use ‘relates to’ as link to budget – besides specially defined rules, how tasks can be connected to the specific budget task, you can also specify such connection directly by the setting up link of “relates to” type. Can be configured for each project separately in the Project Card.
    • Identifier of budget tasks – key which should be used for budget tasks identification. Also can be configured for each project separately in the Project Card.
    • Budget mark text – marker for the task to make it more convenient for end user to identify such. Can be configured for each project separately in the Project Card.
  • “Backlog fields” – this part defines work with backlog and additional configuration of the sprints. All settings can be configured separately for each project at Project Card.
    • Import backlog – defines if we should import tasks from the backlog
    • Set default start/end dates for new sprints – will enable automatic calculation of start\end dates for the upcoming not started sprints in accordance to bellow settings.
    • Interval between sprints, working days – parameter is applied for the future automatically calculated sprints.
    • Default sprint duration – parameter is applied for the future automatically calculated sprints.
    • Max parallel sprints – amount of sprints which should be started in parallel.
  • “Version as Milestone fields” – allows you to use additional milestones for oyu project such as :
    • Use release date as Milestone
    • Use start date as Milestone
  • “Jira Status fields” – this part helps to define additional business rules what to do with remaining hours for tasks which has been transferred to “Done” status.
    • Set remaining to 0 for `Done` tasks
    • Add remaining to spent for `Done` tasks

 

• As Scope and Field Mapping is configured you can proceed with refinement of the Projects list. By selecting and deselecting projects you can define those which will be imported into the system. Nevertheless this list, as all other settings, can be edited later.

Groups and Users

Screen #6 – JIRA – Groups and Users

• Third step will require your attention to configure and define Groups and Users for the import.
  • Import Users – Epicflow allows you to choose all users from the Jira system or users from the selected scope of Projects.
  • Group assignee – defines source of group assignee
  • Group Field Mapping and Prefix –  It will allow you to specify the Component and the Prefix which should be used to refine the groups list.

Closer to the top of the screen, you’ll see the list of Groups with the specified number of Users in the loop and a separate field displaying the names of the users and groups they belong to.

• Review this section to determine the right relation of users to groups and select those which are needed to be imported into the Ecpiflow. Be aware that all deselected users will appear in the unmapped area and you still will be able to draw them to the process later on.

You can either remove a group relation or add a new one to a specific user by simple left mouse click. 

Finalize Import

Screen #7 – JIRA – Finalize Import

• Now, on condition that everything’s configured correctly, you can finalize the import by left mouse click over the “Import” button. Be aware that even that this action cannot be undone Import settings can be reconfigured later as needed. 

Having imported your Jira data into the Epicflow system will redirect you to the Pipeline page with all projects imported into the system.

Second Import Configuration

If previously your system was already configured to connect with a different JIRA instances you’ll see a list of such connections as soon as you visit Import page. 

Screen #8 – JIRA-import Connections list

• To create a new connection to the external JIRA system, press “New connection” button. As result you’ll be automatically redirected to the Connection configuration page . All you would need to do is to cover all steps as during First Import Configuration described above.

Edit connection

To edit any previously created connection you would need to

• navigate to the Import page.
• by calling a context menu as on screenshot select option “Edit”. As result you’ll be redirected to the Connection Configuration page.
• going step by step you will be able to edit configuration but for final apply of such changes all steps must be covered and “Import” button should be clicked as designed.

Screen #8 – JIRA-import Edit Connection

The system will allow you to specify new rules and add projects you’d like to import OR remove an established connection from the list. At the end you’ll be asked to confirm your actions and in case you approve, all changes will be implemented.

Delete connection

To delete any previously created connection you would need to

• navigate to the Import page.
• by calling a context menu as on screenshot select option “Delete”.You’ll be asked for confirmation of your action.
• As soon as you confirm your action Connection link will be removed as well as all projects related to that with the corresponding resource pool and mapping links. Nevertheless internal Epicflow users and groups will remain.Repeat Conneciton configuration will be treated by system as a new one and no historical or configuration data will be restored.

Data optimization

To optimize Epicflow output and bring it closer to JIRA you’ll have to complete the following steps:

• As a first step you’ll have to invest some effort in verifying your data in Jira.

It includes:

• Tasks and their dependency network verification 
• A rough time and cost estimate of each task
• Resource groups assigned to complete each task or Components identification for each task
• Projects, epics and versions deadlines where applicable
• Create a separate account for JIRA integration.
• Grant access for the created account to a required scope of projects.
• (Optional) If you would like to have Epicflow updated in real time mode also add account to the groups “administrators” and “site-admins”. Otherwise JIRA to Epicflow update will be done on hour basis.