Agemba-Jira integration
What does integrating Agemba with Jira mean?
The whole idea behind integrating Agemba with Jira is simply to allow strategically organized work (Stories) in Agemba to be delegated to Jira for implementation. With this structure, a clear-cut overview is still maintained in Agemba while implementation in Jira is uninterrupted. As such, there will not be any pressure for development teams that are highly effective in working with Jira to have to readjust to the introduction of Agemba. It is important to note that this is different from what would qualify as a Jira Plugin which would require installing it onto Jira.
Preconfiguration
Before Jira-syncing can be enabled in Agemba, some configuration is required both in Jira & Agemba. The assumption here is that a Jira project is already setup or should be setup before proceeding with the rest of the steps outlined from this point on.
Prepare Jira User
A Jira user is required to facilitate the process of syncing a Circle (project) in Agemba to a Jira Project. Such a user should have the Jira permissions Create Issues, Edit Issues and Add Comments. By default, these permissions are auto-set in the Jira user groups jira-core-users & jira-software-users. Therefore a user belonging to these groups should suffice.
NB: This user should NOT have Admin rights.
Create API Token for Jira User
An API token is necessary for authorizing Agemba as an API in Jira with the Jira user created in the section above. This needs to be created manually following the process described below:
- Login to https://id.atlassian.com/manage/api-tokens using Jira user credentials.
- Click API tokens, then Create API token.
- Use Copy to clipboard, and paste the token to your somewhere secure and easily accessible.
- Alternatively, follow the guide here for an updated version on how to create an API token.
Setup Jira Sync License Module in Agemba
A special license module is required to be able to sync a Circle with a Jira Project, at the Site level in Agemba. A Site Admin can do this from the License Tab in the Site Overview Modal view in Agemba just like with any other license module. Once this license module has been setup, then any of the Circles within that Site can be synced with a Jira Project.
Configure Jira Sync Properties for Agemba Circle(Project)
NB: To proceed with this, the preceding steps above must have been followed.
For every Circle that is to be synced with a Jira Project, certain Jira properties must be configured in that Circle in Agemba. Below is a Screen dump of Jira Configuration for a Circle:
Configurable Jira properties in Agemba are:
- Jira Sync Status
A display only field, that indicates the current status of the Circle synchronization with the configured Jira project. It can be;- Paused – Syncing has been deliberately set on pause.
- Active – Syncing is currently enabled for this Circle.
- Invalid Credentials – Syncing failed because the Jira credentials provided could not be authorized in the supplied Jira Server Url.
- Invalid Project Key – Syncing failed because the supplied Jira Project Key could not be found in the supplied Jira Server Url.
- Jira User Permission Check Failed – Syncing failed because the provided Jira Server User Name does not meet the permission requirements. Please see the Jira Server User Name point below.
- Connection Error – Syncing failed because connection to the Jira Server Url supplied could not be established; possible reason could be that Jira is down.
- Unknown Api – Syncing failed because the data received from the supplied Jira Server Url could not be processed by Agemba. This would most likely mean that Api version of Jira is different from what is supported in Agemba.
- Corrupted – Syncing failed because of an internal failure in Agemba during the process of syncing data. This situation requires action to resolve.
- Unknown – Syncing failed and the reason could not established decisively.This situation requires action to resolve.
- Jira Project Key
The unique identifier value of the Jira project to sync the Agemba Circle with. It usually starts with an uppercase letter followed by one or more uppercase alphanumeric characters and max length is 10 characters. - Jira Server Url
The Http path that points to the Jira instance that this Circle will be synced with;
e.g ‘ https://your-domain.atlassian.net’ - Jira Server User Name
The dedicated username for the user, in Jira, that will be used by Agemba to synchronize with the project in Jira. See the Prepare Jira User section above. - Jira Server Api Token
See Create API Token for Jira User section above. - Jira Status Map
Map the possible Jira Issue statuses with the corresponding Agemba states. This is necessary so as to be able to sync the state of a delegated Agemba Story to the status of the corresponding Jira Issue. As such, it is only allowed to have a single Jira status mapped to an Agemba state. Jira Statuses are loaded automatically from Jira. - Jira Type Config
This section(s) of the configuration shows the Jira Issue type and what Agemba Story type it is mapped to. If there are any compulsory fields for that Jira Issue type that have to be set when creating in Jira, it will be listed to be configured. The configured compulsory fields will then be used as default values when creating the Issue in Jira.
A Label can optionally be set to be used to label Issues created in Jira, from Agemba.
Test Jira Connection
There is a possibility of testing Jira properties of a Circle at any time which also includes before saving them. This can be done using the ‘Refresh Config from Jira’ button found at the top left corner of the Jira Configuration Tab. This will also load any missing configuration fields from Jira.
Updating Circle Jira Properties
Some of the configured Jira properties on a Circle in Agemba can be updated or changed, more specifically; Jira Server User Name, Jira Server Api Token, Jira Status Map and compulsory fields under Jira Type Config. The other properties i.e Jira Project Key and Jira Server Url cannot be changed or updated once set.
Delegating Agemba Story to Jira
Once the Circle in which a Story resides has been successfully synced with a Jira project, it will be possible to delegate that Story to that Jira project. Delegation to Jira can be done from the Story’s menu in Agemba; see the sample screen dump below:
Delegating an Agemba Story to Jira will result in the creation of a Jira Issue with a similar title and description composing of a merge of the user story and detailed description in Jira. Editing of the Agemba Story will consequently be restricted and its state will be in-sync with that of the corresponding Jira Issue. Information about the Jira Issue will be made visible on the Story in Agemba including the status of the delegation & syncing process. The Delegation Status shows the status of the sync process of the Agemba story with the corresponding Jira Issue. Delegation Status can be:
- Pending – Indicates that the delegation process i.e creation of a corresponding Jira Issue for the Agemba story is not yet complete.
NB: This status should not be interpreted to mean that the process failed or succeeded. - Synced – Indicates that syncing with corresponding Jira Issue is active and the state of the Agemba story will be in sync with the status of the corresponding Jira Issue.
- Syncing Failed – Indicates that syncing failed and the Agemba story will not be in sync with the corresponding Jira Issue.
- Unsynced– Indicates that syncing between the Agemba story and the corresponding Jira Issue was deliberately stopped by the system, either because it was determined as completed i.e set to ‘Closed’ during syncing or as a consequence of canceling Circle syncing with Jira project altogether.
- Unknown Jira Status – Indicates that mapping of the Agemba story’s state to the read status of the corresponding Jira Issue failed. The reason could very likely be that the JIra Status Map configuration on the Circle level was not setup correctly.
- Corrupted – Indicates that either the delegation or syncing process of the Agemba story failed because its data was corrupted.
- Uknown – Indicates that the system encountered a situation that was not anticipated during either delegation or syncing of the Agemba story.
Add Existing Jira Issue to Agemba
An existing Jira Issue, in the specific Jira Project a Circle in Agemba is configured to sync with, can be added directly to the Circle by specifying its Jira Issue Key. This can be done following the same procedure for creating new Stories in Agemba i.e. as children of Epics or in the Inbox, via right click or menu icon. Once the user inputs the Jira Issue Key and it can be verified, Agemba will create a new Agemba Story with the Jira Issue Summary as the Title and Description as the Jira description displayed on the eventual Story card. Just like delegated Stories, Agemba will ensure that it stays insync with the corresponding Jira Issue in Jira.
Undelegating Agemba Story from Jira
A simple form for undelegating from Jira where a Story is disconnected from the corresponding Jira Issue that was created, has been implemented. This can be done from the Story menu in Agemba and will result in the Jira Issue summary(title) being prefixed with [UNDELEGATED].
Story State, Title & Jira Descriprion Sync
Once a Story is delegated, its state, Title and Jira Description will be kept in sync with that of
the corresponding Jira Issue.
