User guide

 

 

General Info

 

Each project administration section gets a new menu after add-on installation.

(Project settings → MS Teams Settings)

 

Connector has 2 modes based on their functionality:

Events - sends notifications to MS Teams channel triggered by events in Jira.

Reports - sends scheduled reports on issues

 

Project administrator can easily switch between modes by clicking on the corresponding button:

 

This feature is available for each user individually.

Navigate to the MS Teams Connector under the profile picture to access menu page.

Personal configuration access:

 

Events mode

 

Here project administrators have the ability to set up connection between current Jira project and required MS Teams channel.

Each project can have limitless number of configurations for MS Teams channels. To create a new setting, find “New Setting” and fill in the required information.

There are 3 main blocks in any configuration tab:

  1. Webhook URL

  2. Filter

  3. Events

 

Channel

 

Even though “Channel" block is not marked out, it contains the basic fields for settings creation:

Title* - is the field containing the name of the setting. Value is also used as setting tab header.

Webhook URL* - field for the link to MS Teams channel.

 

Requirements:

Link must be retrieved from “Incoming Webhook” connector in MS Teams.

Link cannot be used in several settings of the same project.

* - field marked as mandatory

 

To find out if the link is correct use "Test connection" button. If you see test notification in your channel, link is correct.

Filter

 

By default if any selected event (see Events section below) takes place in any issue in project - a notification will be immediately sent to MS Teams channel (or sends Reports based on the corresponding settings). If you want to limit the number of monitored issues, 2 modes of filtering are available: Basic and Advanced.

 

You can switch between filtering modes by clicking on the corresponding toggle. Note that only one filtering mode can exist at a time.

 

Label next to the toggle element will give a hint on what filter mode is configured for current setting.

 

 

Filter update will take effect immediately after saving settings and will erase another filter mode if configured.

 

 

Basic filter mode is designed to help user build own filter like a constructor.

To start building own filter click on “Add filter“ select list to select required field as criteria. You can filter issues both by system field values like “Reporter”, “Summary” or by your custom field values.

 

After selecting the required field, it will be displayed for further data input. You can add several values into one field for filter to work by “any of” principle.

 

For example:

Selecting several priorities will trigger event notification in issues with both "Medium" and "High" priority.

 

If user selected several fields as filter criteria only those issues will trigger notifications that match at least one value for both fields.

 

For example:

 

 

Issue with "High" priority in status "Open" will trigger notification.

Issue with "High" priority in status “Closed" will not trigger notification.

 

 

Advanced filter mode is based on JQL expressions and has wider range of filtering possibilities unlike the basic mode.

 

All filters work only within the current project!

 

Author

 

As administrator you can narrow down notification on events depending on who is their author. i.e. Who performed the action from the selected events list (see Events section below).

For example you can set up notifications to be sent only if they are performed by some core users (like managers or team leads) or a specific team. This can be done by defining specific users or via user groups.

Or you can exclude notifications of events performed by specific users simply mentioning them in the field “Exclude users”.

 

Events

 

In order to get notifications, you must define which of them you are interested in. Possible events are listed and grouped according to their common area of effect: comment, issue, worklog or versions.

If any of the event takes place in issues in the configured filter, a notification will be sent to MS Teams channel.

 

 

You can enable the whole event group turning on the toggle element next to it or pick each event individually.

 

 

 

 

 

Events will trigger notification only for those issues, that match filter for current configuration. Any event in issues that do not follow the configured filer will be ignored.

 

Event

Description

Event

Description

Comment

Comment added

Event triggers notification when a new comment is left in issue.

Comment edited

Event triggers notification when comment in issue is edited.

Mentioned users

Event triggers notification when an "@-mention" is used in issue comment.

Issue

Issue created

Event triggers notification when issue is created in project.

Please note, that event will only work if newly created issue matches the configured filter.

Issue updated

Event triggers notification when issue is edited.

Issue assigned

Event triggers notification when issue assignee is changed.

Issue deleted

Event triggers notification when issue is deleted.

Issue moved to project

Event triggers notification when issue is moved from another project to the current one.

Please note, that event will only work if moved issue matches the configured filter.

Issue moved from project

Event triggers notification when issue is moved from current project to the another one.

Please note, that event will trigger notification regardless of the configured filter!

Issue resolution changed

Event triggers notification when issue resolution is changed.

After event activation a select list will appear. You can select specific resolutions you want to be notified of.

Issue status changed

Event triggers notification when issue status is changed.

After event activation a select list will appear. You can select specific resolutions you want to be notified of.

Worklog

Worklog added

Event triggers notification when time is logged on issue.

Worklog updated

Event triggers notification when logged time on issue is edited.

Worklog deleted

Event triggers notification when logged time on issue is deleted.

Versions

Note, this block of events is not related to configured filter.

i.e. Notification will be sent regardless of the configured filter!

Version created

Event triggers notification when new version is created in project.

Version released

Event triggers notification when project version is marked as "Released".

Version unreleased

Event triggers notification when project version changes its state from "Released" to "Unreleased"

Version updated

Event triggers notification when new changes to project version details are made.

Version merged

Event triggers notification when two project versions are merged into one.

Version archived

Event triggers notification when project version is moved to "Archive".

Version unarchived

Event triggers notification when project version is moved from "Archive".

Version deleted

Event triggers notification when version is deleted from project.

Sprint

Sprint Started

Event triggers notification when sprint related to current project was started.

Sprint Completed

Event triggers notification when sprint related to current project was completed.

 

Extra fields

 

Each card has its own set of fields, yet for some events you can set up additional fields to display in the cards sent to MS Teams channel.

 

 

 

 

You can see an icon next to some events, clicking on which would open a drop down list of fields. Search and select the field which value you want to be displayed in the card sent to MS Teams channel.

 

 

 

 

 

After all settings have been set, save them to apply changes. As soon as they are saved, notification will start reaching your channel.

 

 

Reports mode

 

This mode allows administrators to send scheduled reports to MS Teams channel.

To to set up a report project administrator must take 3 simple steps:

  1. Select Report Type

  2. Configure issue filter

  3. Set up the schedule

 

I. Report type

Report type

Description

Report type

Description

Custom sprint

Sends report on issues in the selected Sprint(s).

Active sprint

Provides reports on issues in currently active Sprint(s).

Issue count

Lists issues matching the selected filter.

Progress

Shows aggregated progress state of issues in filter.

No transitions

Lists issues that have status not changed.

(Based on Minimum overdue)

No updates

Lists issues that have not been updated.

(Based on Minimum overdue)

Some reports require filling extra field to make this report work.

For example "Custom Sprint" report requires selecting the specific Sprint related to current project while "No transitions” and "No updates” reports demand setting a "Minimum overdue”.

Minimum overdue - is the time delay since last event occurrence and current time. If selected report events happened before the minimum overdue period, it will not be included into report.

 

You can select report’s owner. Each report must have an owner as his/her permissions will be counted while building report. i.e. if report owner has no permission to view the issue it will not be included into the report.

If no owner is set - current user will be set as report owner.

 

 

II. Filter

Issue Filter functionality is identical to the one in the Events, but relates to Reports only.

Please see instructions here.

 

 

III. Schedule

This section is designed to create schedule when reports are to be sent to the MS Teams channel.

 

First, pick the period of the report schedule. Then fill in the additional fields depending on the selected period.

 

Each period has a different set of fields that help to adjust the correct time for sending report. You can see the fields corresponding to each of the periods below:

Period

Hour

Minute

Day of week

Mode

Day of month

Period

Hour

Minute

Day of week

Mode

Day of month

Daily

 

 

 

Weekly

 

 

Monthly

 

First day of the month

 

Last day of the month

 

Custom day of the month

Once in

 This type of period has a unique set of fields and logics behind it:

 

While period types like Daily, Weekly and Monthly send reports only once in a specified day and time, the "Once in" type lets you get reports more frequently and within a range of days and time.

 

Schedule time depends on the server timezone.

Keep in mind that the time you set in the fields of the Schedule block may differ from your timezone.

 


Microsoft Teams is a separate service and there is a risk some notifications may be lost due to poor internet connection or rejected by Microsoft Teams itself.

Jira administrators can keep track of these possibilities and not only via Audit Log page in Manage apps section. All errors and major events related to connector configuration can be met there for further investigation.


Please note that logs are automatically cleared once a month, only leaving information about previous month’s events. All older events will be gone.