Documentation for Administrators

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.

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)
Set-ExecutionPolicy RemoteSigned
# 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
view raw shell.ps1 hosted with ❤ by GitHub

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)
Enable-OrganizationCustomization
# Replace [email protected] with the Exchange user you have used in "Exchange Configuration"
New-ManagementRoleAssignment -User:user@example.com -name:impersonationAssignmentName -Role:ApplicationImpersonation
# Office365-only: Close the session
Remove-PSSession $Session
view raw role.ps1 hosted with ❤ by GitHub

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.

5. Permissions

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".

Need help?

Interested in this product but have some questions? Feel free to contact me.

TOP