This article describes the whole process of Project Online <> Jira (two way) integration scenario configuration.
The article describes the configuration process taking into account every little detail while configuring it. Even though the article is quite big, the configuration process should not take longer than 15-25 minutes.
In order to quickly configure this integration scenario we recommend opening three windows in your browser at once:
- your Jira environment (sign in to the applications with the account that have administrator permissions);
- your Project Online environment (sign in to these applications with the account that have administrator permissions);
- Integration Hub application.
It will be much easier to have these windows opened during integration scenario configuration so you could switch between them and configure as required, following the steps below.
Start creating the integration scenario
1. Launch Integration Hub app and navigate to Integration > Scenarios. Click on New Integration.
2. Click on the Jira box to narrow your search and Select Project Online & Jira (Two-way synchronization of Project Online project tasks with Jira issues).
This will take you to the Integration Scenarios page.
Create connection to Project Online
3. Click New next to the Connection field and enter your Project Online PWA URL to which you would like to establish a connection.
In Project Online connection there are three authentication options:
-
OAuth
The 'OAuth' authentication type is a standard and preferred option. When it is used, Integration Hub is authorized to access your resources without sharing credentials. The access token is issued to the Integration Hub app by the authorization server, with approval from your side. Integration Hub then uses the access token to access and process your Project Online data and stores the refresh token for continuous integration.
Please note: If you are creating the first Integration Scenario in your Integration Hub tenant and choosing the OAuth authentication type, there might be a problem with the connection to Project Online. If a problem occurs, as a workaround, we recommend creating the first scenario using SharePoint credentials. When the first scenario is created, later on, you can change the authentication type of this scenario for the OAuth authentication type as well, if required. -
SharePoint Online credentials
If the ‘SharePoint Online credentials’ authentication type is selected a connection will be set up via login and password to a connected SharePoint account. In this case, the credentials are stored and protected in the Integration Hub app. Login to the PWA and please make sure that the account used for running integrations has the necessary set of permissions. -
SharePoint On-premise credentials
This type is used for Project Server 2019 and is available for Integration Hub on-premises version only. If this type is selected a connection will be set up via login and password to a connected SharePoint account. In this case, the credentials are stored and protected in the Integration Hub app. Login to the PWA and please make sure that the account used for running integrations has the necessary set of permissions.
Please note: The Project Server you add as a URL in the login field should be within the same domain as the virtual machine where Integration Hub on-premises is installed.
In the example below OAuth authentication type is selected.
In the window that appears click the Trust it button to trust the application.
Setup Project Online for integration
4. Next, it is required to create the necessary custom fields on the Project Online PWA. In the Parameters section, create the required custom fields used for integration (Sync with Jira, Jira Issue Type, Jira Project) by clicking Create button:
- Sync with Jira. The task-level Flag custom field that identifies if a project task should be synchronized with a Jira issue. This field is required for integration.
- Jira Issue Type. The task-level lookup custom field that determines Jira issue type ('Improvement', 'Task', 'New Feature', 'Bug', 'Epic', 'Story', 'Sub-task' ). This field is not required for the integration to work. If the field name is not provided, the 'Task' issue type will be used.
- Jira Project. The project-level Text custom field defines the name of the destination project in Jira.
- Jira Task Project. The task-level Text custom field defines the name of the destination project in Jira. This field is not required for the integration to work. If the field is not provided, the destination project will be chosen by the name equal to the project name in Project Online.
Please note: The Jira Project and Jira Task Project are optional for the integration. Since Integration Hub matches project by project name, you may not use the Jira Project field if the names of the projects in JIRA and Project Online are 100% equal.
Alternatively, you may choose the existing custom fields from the drop-down (if they were created previously).
Please note: Master Projects are not supported for integrations.
5. Click on Verify to check if the necessary fields exist.
6. Click Next.
The next step will be to add the created custom fields to the required PDPs and Views in Project Online.
To synchronize the task level entities between Project Online and JIRA, we need to add the custom fields Sync with Jira and Jira Issue Type to the required view in Project Online first. This way we will be able to manually flag the tasks we need to synchronize.
1. On your PWA, click on Settings and choose PWA Settings from the menu.
2. Select the Manage Views option.
3. Choose Task Summary in the list of available views (or select a different project task view).
4. Under the Fields section, find the Synch with Jira and Jira Issue Type fields in the Available fields list on the left, choose and move it to the Displayed fields list by clicking on Add.
Click Save.
Next, we will add the Jira Project field to Open Project Online PDP. Open Project Online => Server Settings => Project Detail Pages.
This field is required only in case you have different project names in Project Online and Jira for the projects that you would like to synchronize data between.
Add field Jira Project to the PDP of the Project which will be synchronized. For example, it can be Project Information or a similar PDP.
Open the selected PDP for editing.
Select to edit the PDP page.
Select to edit the web part.
Click Modify.
Add Jira Project field to the web part. Click Ok and Apply to save the changes. Stop editing the page.
Setup Jira for integration
In the next step, it is required to configure the Jira site. Integration Hub cannot create custom fields in Jira automatically, so we will need to add two custom fields to Jira manually.
Open Jira environment.
1. The account used for synchronization should be a member of a default Administrators group.
2. The account used for synchronization should use the default 'English (US)' locale.
3. Jira legacy mode must be Disabled (is Disabled by default in Jira).
4. Time tracking feature should be enabled.
5. Custom field with the name Sync with Project Online should exist in Jira - the custom field that identifies whether a Jira issue should be synchronized with a Project Online project task. Below you will find the instructions on how to add and properly configure this field.
6. Please also ensure, that all the necessary fields - Due Date, Time tracking Summary, Assignee, Issue Type - are added to the project screens.
Creating and configuring Sync with Project Online custom field
1. In the JIRA navigational menu (located on the left side of the page), navigate to Settings > Issues > Custom fields.
2. Click on Create custom field button in the upper right corner of the page.
3. Scroll down the list of custom fields and choose Select List (single choice) and click Next.
4. Enter the name of your custom field (Sync with Project Online) and add Yes and No options. Please note: These options are case register sensitive, type them with a capital letter, as on the example.
5. Click on Create.
6. On the next screen associate the field Sync with Project Online with screens in Projects you want to synchronize, then scroll the page down and click Update.
7. Navigate to your project (the one you plan to synchronize with Project Online) and verify that the Sync with Project Online field is present on all the project screens.
One more field should be added to Jira, if the names of your Jira project and Project Online project do not fully correspond. Project Online Project Name field is used for cases when your projects that are included in integration from Project Online and Jira have different project names. In this case, a Project Online Project Name field is created in Jira. This is a Short text plain (text only) custom field that defines the name of the destination project in Project Online Project for successful synchronization. As this field is created and added to the required screens, it is required to provide the Project Online project name in this field for successful synchronization.
Create connection to Jira
Now we need to set up the connection between Integration Hub and Jira.
Click New to provide a Jira account and establish a connection to Jira.
In the JIRA App Details section, click New and enter the credentials needed to authenticate to your JIRA account:
- Site Url: enter your JIRA URL.
- User Name: enter the name of the JIRA account which will be used for integration.
- Password (JIRA API Token): enter your JIRA API Token.
Please note: For Jira Server login and password can be used instead of Jira API Token.
Please note: To get JIRA API Token, follow these steps:
- Open JIRA, click on the User profile logo in the bottom left corner of the page and choose Profile.
- On the Profile page, click the Account settings button.
- Click Security in the navigational menu located at the left part of the page.
- Find the API Token section and click on the Create and manage API tokens link.
- On the API Tokens page, click the Create API Token button. Enter any name for your API token and click Create.
- Copy token value from Your new API token window.
- Return to Integration Hub and paste it into the Password field.
8. In the Parameters section, choose the custom field which will be used as Sync to PO field.
Please note: Sync with Project Online is the custom field (Select List (single choice) type with Yes/No options) that identifies whether an issue should be synchronized with a Project Online project task. This field is required for the integration and should be manually created in your JIRA environment and added to the appropriate screens.
9. Click Verify configuration to check for possible issues.
10. Click Next to continue to the Mapping page.
Setup Project Online & Jira fields mapping
The Fields mapping allows you to define JIRA issue fields and Project Online project fields which will be synchronized. As you can see, JIRA Summary field is mapped by default to the ProjectName field in Project Online.
Please note, that some fields are already mapped by default. To add another mapping:
1. Click on Add Mapping.
2. Choose a JIRA issue field in the dropdown list on the left.
3. Сhoose a corresponding ProjectOnline project field on the right. Optionally, you can also choose the synchronization direction.
4. Click Next to proceed to the Schedule page.
Please note: To learn more about the possible field mappings, please read this article.
Integration schedule configuration
The Schedule page allows choosing between the manual (on demand) or scheduled (daily or weekly) synchronization between your list and your project.
Please note: Since this particular scenario is commonly used to extract the already existing issues from JIRA, it is necessary to properly set the Synchronization Start Date. Integration Hub will only synchronize the JIRA issues created after the Synchronization Start Date.
After you have configured the integration schedule, click Done to return to the Scenarios page.
You will see two integration scenarios that can be launched:
- Sync Project Online Tasks to Jira issues;
- Sync Jira issues to Project Online tasks.
Congratulations! The integration scenario configuration was performed successfully!
When the integration is configured, data synchronization will be performed automatically (on demand or by schedule) for all projects where the required fields are added and set up for synchronization. You can configure as many projects as required for data synchronization.
Now let's launch the first synchronization and make sure that everything works as expected.
For the details instructions on how to run your first integration please refer to the Running your first integration article.