Understanding Workflow Triggers for Metanow CRM Integrations
Workflow triggers in Metanow CRM are activated by events (e.g., a commit being created) that occur in various integrated development tools.
It is crucial that users thoroughly understand the implications before adding triggers to global transitions. Incorrect configuration can lead to a work item unexpectedly changing its status. For instance, if a global transition is triggered when code is committed, a work item might incorrectly move to 'In Progress' from statuses such as 'In Review' or 'Done'.
Referencing a Metanow CRM Work Item in Development Events
The table below describes how to reference a Metanow CRM work item in a commit, branch, pull request, or review, so that these events will trigger transitions for the work item (provided that you have set up triggers on the transitions).
| Event | Instructions |
|---|---|
| Create commit | Include the work item key in the commit message. For example, a commit message like this "TIS-1 Initial commit" will automatically transition the TIS-1 work item from 'To Do' to 'In Progress'. |
| Create branch | Include the work item key in the branch name, when you create the branch. For example, if you name your branch "TIS-2-feature", it will automatically transition the TIS-2 work item from 'To Do' to 'In Progress'. |
| Create/Reopen/Decline Merge pull request | Ensure that the pull request includes commits that reference the work item (in their commit messages). For example, if you create a pull request that has "TIS-3" in the title, it will automatically transition the "TIS-3" work item from 'In Progress' to 'In Review'. If you reopen, decline or merge the pull request, it will also transition the "TIS-3" work item accordingly. |
| Start/Reject/Abandon/Close review | Include the work item key in the review title, when you create the review. For example, if you name your review "TIS-4 New story" and start the review, it will automatically transition the TIS-4 work item from 'In Progress' to 'In Review'. If you reject, abandon or close the review, it will also transition the "TIS-4" work item accordingly. |
The following process details how a user from a development tool is mapped to a Metanow CRM user for workflow triggers. This mapping applies to all events, though each development tool utilizes specific email addresses and usernames for this purpose (refer to the bullet points below for details).
- Process: The user initiating the event in the development tool is mapped to a Metanow CRM user by matching the email address, then the username, i.e.
- _Single Metanow CRM user with a matching email address —_ Transition the work item as the Metanow CRM user.
- _No Metanow CRM users with a matching email address —_ Transition the work item as an anonymous user.
- _Multiple users with a matching email address in Metanow CRM —_ Try to find a matching username in that group of users. If there is a Metanow CRM user with a matching username, transition the work item as the Metanow CRM user. If there is no matching username, transition the work item as an anonymous user.
Email Address and Username Used for User Mapping
For Bitbucket Data Center:
| Event(s) | Email address and username used for user mapping |
|---|---|
| All pull request events | The Bitbucket Data Center email address and username of the user who actioned the pull request. |
| Commit created | The email address associated with the commit and the Bitbucket Data Center username that the email address maps to. If the email address does not map to a username, the authors "name" from the commit will be used. |
| Branch created | The Bitbucket Data Center email address and username of the authenticated user that pushed the branch to Bitbucket Data Center. |
For Fisheye or Crucible:
| Event(s) | Email address and username used for user mapping |
|---|---|
| Commit created | The email address associated with the commit and the Fisheye username that the email address maps to. If the email address does not map to a username, the authors "name" from the commit will be used. |
| Branch created | This event is not mapped to a Metanow CRM user. This means that the work item will be transitioned as an anonymous user. |
| All review events | The Crucible email address and username of the authenticated user that actioned the review. |
For Bitbucket Cloud:
| Event(s) | Email address and username used for user mapping |
|---|---|
| All pull request events | The Bitbucket email address and username of the user who actioned the pull request. Note, the Bitbucket user needs to have made at least one commit (with that email address configured for their profile), otherwise the pull request cannot be mapped to a Metanow CRM user. This means that the work item will be transitioned as an anonymous user. |
| Commit created | Email address associated with the commit and the Bitbucket username that the email address maps to. If the email address does not map to a username, the authors "name" from the commit will be used. |
| Branch created | This event is not mapped to a Metanow CRM user. This means that the work item will be transitioned as an anonymous user. |
For GitHub:
| Event(s) | Email address and username used for user mapping |
|---|---|
| Pull request created / Pull request merged | GitHub email address and username of the user who actioned the pull request. Note, the GitHub user needs to have made at least one commit (with that email address configured for their profile), otherwise the pull request cannot be mapped to a Metanow CRM user. This means that the work item will be transitioned as an anonymous user. |
| Commit created | Email address associated with the commit and the GitHub username that the email address maps to. If the email address does not map to a username, the authors "name" from the commit will be used. |
| Branch created | This event is not mapped to a Metanow CRM user. This means that the work item will be transitioned as an anonymous user. |
Event Handling and Event Limits
Typically, events from integrated development tools should seamlessly trigger automatic work item transitions. However, delays or failures in work item transitioning can occasionally occur due to how events are handled or specific event limits.
- Event Handling — The way events are processed varies depending on whether the development tool connects to Metanow CRM via the DVCS connector or an application link. This distinction can influence whether events are delayed or lost if Metanow CRM is temporarily unavailable.
For Bitbucket or GitHub
Events from Bitbucket and GitHub are processed via the DVCS connector in Metanow CRM. The DVCS connector processes events from Bitbucket and GitHub via two synchronization mechanisms: a webhook-triggered synchronization and a scheduled synchronization.
- Webhook-triggered synchronization: The DVCS connector uses webhooks in Bitbucket and GitHub to post data to Metanow CRM when an event occurs. This is the standard mechanism for processing events, which means that work items should be automatically transitioned almost immediately after a Bitbucket/GitHub event. Event limit: 10 branches; 100 commits.
- Scheduled synchronization: Event limit: 600 branches (sync interval in minutes x 10); 6000 commits (sync interval in minutes x 100)
The event limits for scheduled synchronizations can be less than 600 branches and 6000 commits, if the synchronization interval is reduced, but never greater.
If Metanow CRM cannot be contacted when a Bitbucket/GitHub event occurs, the event is stored by the DVCS connector and sent at the next scheduled synchronization (every 60 minutes, by default). This is a backup mechanism in case the webhook-triggered synchronization fails.
For Bitbucket Data Center, Fisheye, or Crucible
Events from Bitbucket Data Center and Fisheye/Crucible are processed via the application link. However, Bitbucket Data Center and Fisheye/Crucible are responsible for ensuring that events are sent, and they send them once at the time that the event occurs. This means that if Metanow CRM is unavailable when the events are sent, the events will be lost.
Event limit: 10 branches; 100 commits per synchronization. A further constraint that applies on top of the 10 branches and 100 commits limits is a 100,000 work item changed event limit. For example, if 100 commits each reference more than 1000 work item keys, the work item changed limit would be exceeded. Limited to 6000 events per synchronization.
How Triggers Relate to Other Workflow Operations/Constraints
When a transition is automatically triggered, it bypasses any conditions, validators, or permissions set on that transition. However, post functions will still be executed. If a post function requires a specific user, ensure your transition is not executed by an anonymous user (refer to the user mapping section above).
