How to configure Jira to Fluid Boards integration

Modified on Thu, 21 Mar at 5:18 PM

To help project managers and their development teams streamline their agile workflow processes, the integration of Jira with Fluid will enable managers to establish an agile workflow that aligns with their team's technical requirements, thereby fostering collaboration and driving progress.

This article will cover how to integrate Jira to Fluid Boards, allowing the the Project Owner to have visibility over the work and IT/Tech teams delivery without the complexity of Jira and the technical process.

Access the Integrations option a board

To start off, navigate to the integrations options on your board from the the Tools tab.

Once the Integration options is selected and the dialog opens, you will then be able to select the integration for Jira.

The following dialog will present the Set Up page where the integration details for the board can be completed.

You can learn more about how to initially create a board in Fluid by clicking here.

Complete the Integration details

Each of the sections for the integration details are as follows:

Name	The name of the board that will be reflected in Jira.
Active	Whether integration is currently enabled for this board.
Frequency	How frequent the job runs for any updates/changes made on the board. - Hourly - 6 Hour - 12 Hour - Daily - Weekly
Block Create/Update tasks for Jira	Hard block to ensure no requests are sent to Jira. Used when you only want to pull information from Jira into fluid, read only and want to ensure that you do not change any Jira Tasks.
Authentication Provider	What authentication mechanism you want to use for connect to Jira. Jira at present only supports PAT for their restful service.
Token	The API PAT token that is generated for programmatic access. See how to generate a API PAT Token in this KB for more details.
Board	The board that will be linked/integrated. https://your_domain.atlassian.net/jira/software/projects/EG/boards/[board_number]
Your Domain	The url of the domain that is integrated. https://your_domain.atlassian.net/
Username	The username of the account that was used to generate the PAT API PAT token.
Project	Jira project that that items will exists under https://your_domain.atlassian.net/jira/software/projects/[project_name]/boards/1
Board number	The assigned number of the board in Jira. https://your_domain.atlassian.net/jira/software/projects/EG/boards/[board_number]
Update status from Jira	[Two-Way Updates] - Allow both Fluid and Jira to update the status of the board tasks. Any change in status in fluid will be sent to Jira. Any status change in Jira will change the status of the card in Fluid. Status in both systems are kept in sync. Note: if not turned on, the status updates made in Fluid on the board tasks will not be synced to Jira. Jira status changes will not be reflected back into fluid.
Allow Delete in Jira	Allow Fluid to delete tasks in Jira. Not this is a destructive action. The Jira item will be permanently deleted and cannot be recovered.
Allow Attachments to be sync from Fluid to DevOps	When enabled will link attachments from the Fluid Item to Jira. Attachments are links back to Fluid to view/download.
Sync item after create or link	Immediately after the Fluid item has been created on the board, it is synced with Jira. You do not have to wait for the sync schedule, or manually click "Sync Schedule" on top of the board to sync properties.
% Progress calculator	What calculation to use to determine % complete for a task
Include parent item in % progress calculation	Should the parent Jira item be used as part of the % complete calculation. If the Jira task is just used as a container for subtasks then you may not want to include the container as part of your calculation
Verbose Logging	Used when initially setting up, turn this on to see detailed messages in the event of issues communicating between Fluid and Jira.
Status Mapping	Configure the status columns that will be mapped in Jira for when tasks statuses are being updated.
Task Types Mappings	Configure the task types that will be mapped to Jira. Only Tasks that have been configured and mapped will be used to integrate with Jira.
Common Properties	Configure which common properties will be associated with all mapped tasks to minimise duplication. The properties if defined will be sent downstream to Jira, on create and update of the fluid card.
Task Properties	Configure specific properties for this task type only. Only properties mapped here will apply to the task in addition to the ones that have been defined as common.

API PAT Token Generation

All users are allowed to create their own PATs, which will match their current permission level. To create the tokens, you may follow these steps:

Atlassian Jira cloud versions and On Premises deployments may vary in versions. As such the PAT token creation process may vary to the steps detailed below. For further information visit https://support.atlassian.com/jira-software-cloud/resources/

In your Atlassian application:

In Jira, select your profile picture at the top right of the screen, then choose Profile. Once you access your profile, Click on "Manage Your Account"
Select Security from the top menu

Scroll down and click on Create and Manage API tokens.

Click Create API Token

Give your new token a label name.

Keep this token secure, it will be used as part of the configuration process of your Fluid boards.

Status Syncing

When enabled, this option controlled the behaviour of syncing status from Jira into fluid and vice versa. If this is enabled, it is considered a Two-Way syncing.

If Fluid status is changed this is pushed to jira and the item will be updated accordingly.
If Jira status is changed, when the configured synch job runs, the fluid card will be updated to match the status of the jira item.

Once synced, both items are matched in terms of their respective statuses based on the Status Syncing Mode (see below) and defined per the status mapping, see below "Status Mapping" section for more information.

When disabled, no status information will be sent as part of the jira item being created. Jira by default will create the jira item in its default status as defined for that task type within Jira itself. View your Jira configuration for each task type within the Jira application itself to know what default status is used.

Status Syncing Mode

If Status Sync is enabled, there will be a visible button as highlighted above that can be clicked to choose the Sync Mode you want to apply.

Create-Only [Push]
- Fluid status is sent once and only on item create to Jira. Any subsequent changes in status in Fluid will not be reflected in Jira. You can continue to update the status in Fluid, and the status will appear changed in Fluid, but the linked item status in Jira will not be changed.
One-Way [Push]
- Any change to the status in Fluid is sent to Jira. However, no status from Jira is pulled/updated back into Fluid. Use this if you intend Fluid to be the gold standard source of status data for the item.
One-Way [Pull]
- Any change to the status for Jira item is pulled into Fluid and overrides the current status of the Fluid item, when sync occurs. Use this if you intend Jira to be the gold standard source of status for the item.
Two-Way [Sync]
- The Fluid status and the Jira status are kept in sync. Any changes to Fluid are sent to Jira and vice versa any Jira changes to status are synced back into Fluid when the Sync process runs.

Status Mapping

In Fluid status columns for each board can be set up to move tasks as they progress through the agile workflow. It is important to map out which status columns should be included in Jira to ensure that when a task's status is updated in Fluid it is synced in Jira.

Note: If the statuses are not mapped out, the updates made in Fluid on the tasks will not be integrated to Jira.

Statuses can have a 1 : M ( 1 to Many ) relationship. for example "In Progress" and "Dev Complete" in fluid have been mapped to the same "In Progress" in Jira. In Addition, "Not Started" and "Returned" have both been mapped to "To Do" in jira.

Note: The first row is coloured green. This is to indicate this is the starting status for created items. The last row is coloured blue to indicate this is the Final item status. All other statuses by definition are considered an "In Progress" status.

Click on the [+ New Status Mapping ] to add a new row.

Select from a list of possible status options on the left.

On the right hand side, type the name Status and the Fluid status should be applied to.

Click [ X ] to remove the row.

Common Properties

Configuring common properties provide the ability to establish properties that will apply consistency through out the task data that is streamlined in your workflow.

These properties are widely used and applied to multiple tasks which in turn reduces duplicated effort.

Only properties mapped will be sent to Jira.

Common Properties Syncing Mode

Create-Only [Push]
- Fluid properties are sent once and only on item create to Jira. Any subsequent changes to properties in Fluid are not be reflected in Jira. You can continue to update properties in Fluid, and they will appear changed in Fluid, but the linked item properties in Jira will not be changed.
One-Way [Push]
- Any changed properties in Fluid are sent to Jira. However, no properties from Jira are pulled/updated back into Fluid. Use this if you intend Fluid to be the gold standard source of properties for the item.
One-Way [Pull]
- Any changed properties in Jira item are pulled back into Fluid and override the properties values of the Fluid item, when sync occurs. Use this if you intend Jira to be the gold standard source of properties for the item.
Two-Way [Sync]
- The Fluid properties and the Jira properties are kept in sync. Any changes to Fluid are sent to Jira and vice versa, and any Jira changes to properties are synced back into Fluid when the Sync process runs.

Task Type

For each task that you want to create a Jira item in your workflow, the Task Type needs to be defined and mapped to the equivalent type in Jira.

If the a Fluid Task type is not mapped, then no corresponding item is created in Jira in the workflow.

Task Type Properties

Task type properties provide additional reporting on the different types of activities that are carried out within a workflow. These relate specifically to this defined Task Type only.

If you have a property that is only set for a particular task type, then use this workflow. If you have a property that will be applied to all task types then use Common Properties as defined above. Common properties are included as a union set of properties for this task type.

Task Type Status

Task type status allows you to define any further specific status that only apply to this Task type. Note, you can still have Status mappings defined as mentioned previously in the Status mapping section of this document, but any status you define here at the Task Type level are in addition to the already defined Status mappings are are specific to this Task type only.

If you have already defined the mapping "Not Started"->"New", then adding a Task type status mapping of "In Progress"-> "Working" will mean for the Fluid Task type of New Feature, we have mapped Fluid "Not Started" and ""In Progress" mapped accordingly.

This allows you if you prefer to have completely different sets of statuses for each Task type, depending on how you have setup your status and rules in Jira.

Synchronising Fields from Jira into Fluid.

Each time a board task/card is updated, the changes are synced to the card on Jira. Below is an example of a card created on a fluid board and how it is represented in Jira.

This is the card created in jira as an issue.

Clicking on the card in Fluid opens the edit dialog, the Integrations section is shown at the bottom of the board card where you can see the synchronisation of the jira item into fluid.

"In Progress" status shows the jira item is currently being worked on. You can click on the "Open Jira" option to view the actual item itself in jira.

"0/1" indicates there is 1 item associated with this integrations and 0 has been completed.

Note: You can manually start a synchronisation job by clicking on the "Sync Integrations" Button

located at the top of the board. This will manually run the job that fetches all the data from Jira. It is the same job that runs at the set frequency as defined in the earlier configuration.

To further illustrate, IT/Tech team has added 3 subtask in jira this parent item in the example below. This displays how IT/Tech team manages the jira issue themselves using their own agile methodology, outside of the Project Owner.

The 3 sub-tasks, are controlled by IT/Tech team, all fields are set by IT and IT is free to use these sub-task in any development methodology they so choose. As these SubTasks are updated by IT, the parent jira item is updated to show the change in subtasks status. IT has also put a Due Date on this parent item “30 Mar 2023”.

Note: It’s not a requirement of IT to use sub-tasks, they are free to work off of the parent jira issue and update it accordingly, use it in sprints etc. Subtasks are the recommended jira process of breaking a larger task into smaller components, that can be worked on separately and then roll up to a parent.

After the data has been synced. The below section on the action is displayed on the action edit dialog.

“In Progress” is the status of the jira item, clicking on “Open Jira” will link you directly to the jira item in a new browser tab.

The “30 Mar 23” is the due date that has been set on the jira item itself. This is NOT the Due Date of the Fluid item.

“33% complete” indicates the percentage of completed subtasks / total subtasks. The bar shows you a progress bar of how much work is left before complete, Green is “Completed”, Blue is “In Progress”, Grey is “Not Started”

Clicking on “show details” will show you an expanded view and you can see all the subtask assigned, a title/description, status and due date for each subtask

The Project Owner has visibility over the work and IT/Tech team itself, they can see that the IT/Tech team are 33% complete on this work and that current due dates align.

IT/tech team added the tasks into their sprint cycle and did the development within their own processes without having to change how they run as a team. The Project Owner also didn’t need to chase the IT tech lead for updates, the Project Owner can see this on the card/action itself.