Used old v1 of the plugin?
If you used old v1.x version of the SITO plugin please redo the complete configuration again because the synchronization works now in another, more stable way.
In this documentation you’ll find everything you need to config your Sync Issue To Outlook for your Jira.
Please follow these guide and check every step. This tutorial is designed for Office 365, but if one step differs from Exchange Server, an alternative solution is suggested.
1. Activate EWS
Exchange Web Services (EWS) provides the functionality to enable client applications to communicate with the Exchange server. For further informations please refer to the official Microsoft site. For Office365 this is usually activated by default.
2. Establish connection between Jira and Exchange
First of all we have to establish the connection between your Jira instance and the Exchange server. Start by filling the Email and Password. Then by clicking "Get Exchange Web Service URL" you get the Server-URL which is needed for the API. In the above image you can see the API URL for Office 365.
Furthermore you have to define the default timezone of your Exchange Server. The backwards compatibility needs to be "Yes" if you are using Exchange 2007.
Note: For Office365 you need at least "Plan E3" for the above user.
3. Configure impersonation
What's "Impersontation"? This is a functionality added by Microsoft so a single user can create appointments (and other items) for another user without Sharing or Login. For this process a Role ApplicationImpersonation is needed for the users which is defined in your "Exchange Configuration" (see above).
Connect to Exchange Online Powershell
If you are using Office365 you have to connect to the Exchange Online Powershell. Otherwise you have to open the Exchange Server Powershell (you can skip this step). Please open Windows Powershell as Administrator in your Windows environment and insert the following commands step-by-step:
|# Allow remote scripts (downloaded from Office365)|
|# Create credentials for your Office365 user (the same as in "Exchange Configuration")|
|$UserCredential = Get-Credential|
|# Create the session|
|$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection|
|# Connect to the session|
|Import-PSSession $Session -DisableNameChecking|
It does not work for you? Please refer to the original resource: Connect to Exchange Online PowerShell
Add role to Exchange user
If you are running within the Exchange CLI (Office365 or Exchange Server) you can add the role to the users which you have used in "Exchange Configuration":
|# Enable custom organization so the Role can be added via CLI (this is usually enabled in your company)|
|# Replace [email protected] with the Exchange user you have used in "Exchange Configuration"|
|New-ManagementRoleAssignment -User:email@example.com -name:impersonationAssignmentName -Role:ApplicationImpersonation|
|# Office365-only: Close the session|
If you need more customization you can refer to the following original resources:
4. Test your configuration
If you have done all above please navigate to "Configuration Testing". There you will find an email input and the detected Server-URL. Just try the button "Check" and check your calendar. There you can find a calendar entry.
Don't worry. None of your JIRA-Users will be able to use sync functionality until they have the permission to do so. Therefore you can choose a list of groups which can use the feature - and which not. Select the groups to fit for your needs an press the button to save the configuration.
- Whitelist: Each user, which is in a selected group is potentially allowd sync issues to outlook. Except...
- Blacklist: Each user, which is in a selected group here is definitley not allowed to use the feature. Even if the user is in a selected group of Whitelist.
Best practice: Normally you want to enable the feature for all your users. If all are in one group just enable it in Whitelist. For single users which are not allowed you could create a separate group. Add the specific users to that group and set the group on the blacklist.
6. Custom field "Period of Time"
Now that you have configured SITO to access EWS we move on the enable the new custom field. This is a new type of custom field and is shipped with our plugin.
To enable Sync Issue To Outlook for your users it must be created once. And really only once.
How to create a custom field please refer to the official Atlassian Documentation. Be sure to use our new custom field type "Period of Time". If you are searching our custom field type be sure to search in category "All"
After creation you can define your own name or you simply name it Period of Time - as we did here.
Please be sure to enable it on relevant screens (please refer to Atlassian Documentation).
Best practise: Place the new custom field beneath the field 'due date'. Refer to the official Atlassian Documentation.
7. Try and share
Now that every thing is configured in Administration we can go on with our users. In the meantime your users may have already discovered the new custom field and wondering what to do with it. If they used it already - even better!
The only thing left to do for you is to share information how to enable it for their own outlook calenders. But please try it on your own first, so that you can assist to your users.
This is found on Documentation for Users or the user itself can find it within the custom field "Period of Time".
Do you have problems with your Impersonation or Config testing? In the following section you will find different solutions how to resolve issues.
If you encounter any issues regarding Jira SITO and your Exchange service you can try if your service and Impersonation is setup correctly through a program "EWSEditor" (Github).
- Download latest EWSEditor here
- Unzip the downloaded file to your filesystem
- Navigate to the extracted folder and open the file "EWSEditor.exe"
- "File" > "New Exchange Service..."
- Check if EWS works
- Check if Impersonation works
If you get the message "Failed to get a mailbox session for [email protected]" in the configuration testing view (when entering another email as the Jira SITO user) check your Office365 paid plan. The Jira SITO user (which has the Impersonation rights) needs to be at least on E3 plan.