JIRA - Visma Severa Integration Instructions

Integration links two systems together and it's important to know how to do it. Also, integration has options for different behavior.

Atlassian JIRA

The hierarchy in JIRA is following:

You create a project and then create issues for it, and you can add sub-tasks for an issue. The user interface in JIRA does not allow adding sub-tasks for a sub-task.

When you transfer cases/phases from Severa to JIRA then the limitation about sub-tasks matters. JIRA allows or denies sub-tasks for a sub-task, based on few things (JIRA version, do you run your own instance or from the cloud, or do you have third party add-ons in use), so you have to know the limitation, but this is only a problem when you transfer cases from Severa to JIRA.

Visma Severa

The hierarchy in Visma Severa is following:

You create a case for a customer and you can add phases to it and each phase can have sub-phases and they can have sub-phases. The hierarchy is unlimited.

Because JIRA does not know a customer, integration cannot create a case in Severa.

Integration

The integration does not transfer anything until it's configured to link the systems together. You can instruct a Severa case to be linked with a JIRA project.

JIRA as a source of phases (JIRA Project = Severa Case)

This is the most simple and logical solution.

Following use cases are supported:

Do following:

Now JIRA is the source of almost all data, and you will need to use Severa only to create a case, possibly update work types for the phases added by integration and create invoices. When you have a big project in JIRA and it will have many issues then the case will have as many phases.

Lets assume that you have this in JIRA:

And this in Severa:

After the integration runs this will be in Severa:

When you edit the names of issues/sub-tasks or add more issues/sub-tasks then they will be transferred to Severa. When you delete issues/sub-tasks then the integration will not delete them from Severa. When you add phases to Severa they will not be transferred to JIRA. They will be linked together when you add issue/sub-task with same name in JIRA.

Issue Type to Phase Mapping

When you want to use issue types in Severa then you can enable this feature in configuration or in case.

Lets assume that you have these issue types in JIRA and you use them in your project:

Then you define this rule: (New Feature, Bug)=Development

And, lets assume that you have these issues in JIRA:

After the integration runs this will be in Severa:

Sales and Support have zero work estimates, but Development has estimate calculated from the issues. When you enter work logs for those issues, they will be transferred to correct phase.

Tempo's billing account based project selection in Severa

This option is useful when you have multiple customers and billing accounts associated with a single project in Tempo. Integration maps Tempo's billing accounts to projects in Severa. When worklog's issue is not associated with a billing account then these worklogs will be added to a single project which you need to specify.

You need to enable Tempo and enter few details for correct behavior.

Please, give a billing account category which defines billable work. The worklog will be added to the project in Severa whose short name is the same as the billing account key. When the project does not exist in Severa then the project will be created for the customer based on its business id. When the customer does not exist in Severa then the customer will be created in Severa.

Optionally you can enter a name of the work type which will be used for each hour entry in Severa when the worklog is associated with billable work. Integration's normal work type selection logic will be used for non-billable work.

The integration will transfer worklogs of all projects in JIRA/Tempo except when you list project keys. This is useful during testing.

Work logs - Hour entries

The integration transfers all work logs of the projects which have been linked with cases/phases. The hour entry will be associated with a phase which is associated with the work log's issue. If issue is not linked with a phase then the hour entry will be associated with parent issue/phase. If phase could not be found then the hour entry will not be transferred. If in this case the issue's project is associated with a case then the hour entry will be associated with that case.

When you use issue type to phase mapping then the logic is different. Please, see above.

Lets assume you have this in JIRA:

Lets assume that you have this in Severa:

When you enter work log for "Configuration", it will be assocaited with phase "Configuration". When you enter work log for "Logging" then it will be associated with case "Core" ("Logging" is not in Severa, but parent of "Logging" is linked with a phase). When you enter work log for "IoC" then it will not be transferred to Severa, because the issue is not linked with a phase. If you have linked a case "Integration" with a project "Integration" then hour entries of "IoC" will be associated with case "Integration".

Tempo Servlet

When you use a version of Tempo which does not store worklogs in JIRA, but stores them inside Tempo then you must select that option in configuration. Integration will use Tempo's Machine-To-Machine API therefore you have to configure allowed IP-addresses in Tempo's Access Control. You can find the IP addresses on configuration page. Also, you need to configure Tempo API Security Token.

Tempo API does not support incremental change log for worklogs, but it supports getting differences since last transfer during specific timeframe. Timeframe is for worklog's entry date and not for its update date. For this reason you can specify how many days to transfer. During testing specify only few days to limit the affected worklog entries. Once testing is complete then you can specify higher value. If you specify e.g. 30 days and then someone changes two months old worklog then it will not be included. The bigger the number the slower the process might be.

Before you begin using Tempo as a worklog source it's good to test it with one user. For testing period specify username to transfer from Tempo instead from JIRA. When the username is specified then the integration will transfer other users from JIRA and only the mentioned username from Tempo. Make sure you spell the username correctly. When it's incorrect then the effect is the same as if Tempo integration is not in use.

Tempo Cloud

When your JIRA is hosted by Atlassian and you use Tempo then getting worklogs from JIRA does not work as expected. The user will always be 'Tempo Timesheets'. In this situation you must enable Tempo Cloud and enter bearer token. That token can be created in Tempo - Settings - Data Access - API integration. Make sure you have permissions to read worklogs of the people you want to sync to Severa.

Work types

When integration transfers work logs from JIRA as hour entries to Severa then it will use following logic for work type:

Absences

Absences are entered as activities in Severa. When your organization enters absences in JIRA they can be transferred to Severa as activities. To do so, enable "Transfer absence worklogs to Severa" and enter the keys of the projects which has issues for absences. For correct mapping, please match issue's summary with activity type's name. Only activity types in category "Absences" will be used. For example if you have activity type with name "Sick leave" then create an issue with summary "Sick leave" in the project which contains absences.

When the integration has transferred an absence worklog to Severa and you delete the absence worklog from JIRA then the integration will delete the activity from Severa. If your JIRA does not support getting deleted worklogs then the integration does not delete activities from Severa.

Moving JIRA instance

When you have run integration against JIRA instance which is hosted by Atlassian and want to move JIRA into your own host then you have to verify few things before you do the move. First, disable integration. Then make sure that you create a clone of the JIRA data. Integration stores identifiers to its database to be able to link data between JIRA and Severa. For this reason it's very important that the new instance has the same identifiers for issues and worklogs as the original. Once you have the new JIRA instance ready then enter its host address in configuration and save. Then enter few projects to analyze and save. Now you can enable integration. Integration does not execute integration, but enters into analyze mode. Integration will analyze that all issues and worklogs of the projects to analyze can be mapped to same data in Severa. Integration will send email about the results. Once you receive a first email, please disable integration. If you do not disable integration, it will analyze the projects on each execution. Examine the results in the email and decide the next step. You can test other projects too, or if all seems right then empty the projects to analyze, save and enable integration.

It's also possible to run the integration, but not transfer worklogs to Severa. When you check Analyze work logs then the integration runs normally except it will not transfer work logs to Severa. Instead it will collect all changes (add, update and delete) and send them by email. The changes are attached as csv file. Once you receive the email then disable integration. Then you can examine the results and if you realize that the csv file does not contain duplicate work logs then you can uncheck the Analyze work logs, save the configuration and enable integration.