To help project managers and their development teams streamline their agile workflow processes, the integration of DevOps 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 DevOps to Fluid Boards, allowing the the Project Owner to have visibility over the work and IT/Tech teams delivery without the complexity of DevOps and the technical process.
NOTE: This feature is not enabled by default. Depending on the complexities of your internal DevOps environment, we recommend first discussing your requirements with your Fluid Success manager. They will be able to assist on enabling the feature and guide you through the key steps for integrating with DevOps.
Access the Integrations option on the board
To start off, navigate to the integrations options on your Kanban board view from the the Tools tab.
For other board related views like the Backlog or Board Workspace view, the Setup Integration option can be found on the left column navigation. As a general rule, the left navigation is where you should look for options related to your current view. For views like the Kanban view above however, there is no left navigation, so options can instead be found under the tools menu.
Once the Integration options is selected and the dialog opens, you will then be able to select the integration for AzureDevOps.
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.
Completing 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 DevOps. |
| 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 DevOps | Hard block to ensure no requests are sent to DevOps. Used when you only want to pull information from DevOps into fluid, read only and want to ensure that you do not change any DevOps Work Items. |
| Authentication Provider | See below in the next section. |
Authentication Provider
Fluid supports Service Principals or PAT tokens for access to DevOps. Project managers should work with their internal IT teams to provide the information below as part of the setup requirements.
Service Principals
Below are the required configuration details:
- The unique client ID GUID for the service principal.
- The client secret. The secret is stored securely in an Azure Key Vault, it is not persisted anywhere outside of the Key Vault and access to the Key Vault is locked down to the process running the fluid instance within the Azure platform.
- Your Azure AD Tenant ID.
The above details are used per our configuration:
NOTE: With respect to permissioning of the Service Principal to the DevOps projects, it is important that the account is also permissioned to the Area level that the project resides in, and not just the project itself. The Service Principal requires access along the hierarchy tree down to the specific project.
The service principal will need to be permissioned to Azure DevOps project(s) you want to integrate with and have the same permissions as a typical user that contributes to the board/worktitems in DevOps.
How to create Service Principals
Details on Service Principals : https://learn.microsoft.com/en-us/azure/devops/integrate/get-started/authentication/service-principal-managed-identity?view=azure-devops#1-create-a-new-managed-identity-or-application-service-principal
Please follow the guide for service principals. Managed identities are not supported.
PAT Tokens
Below are the required configuration details:
- PAT token as generated from your DevOps instance
| Board | The board to integrate (where the tasks will be extracted from) |
| Organisation | The url of the domain that is integrated. https://[organiastion_name].visualstudio.com or https://dev.azure.com/[organization_name] |
| Project | The name of your project in DevOps https://[organiastion_name].visualstudio.com/[project_name] or https://dev.azure.com/[organisation_name]/[project_name] |
| Iteration path | An iteration path is a hierarchical structure used to organize work items into specific timeframes or iterations. It helps teams manage and track progress by categorizing work items (such as user stories, tasks, bugs, etc.) You can find your iteration path by following the below. Work Items: Open any work item within your Azure DevOps project, such as a user story or a task. Look for the field named "Iteration Path" or "Iteration" (the name might slightly vary based on your project's configuration). It's often located alongside other fields like "Area Path," "Assigned To," etc. Boards (Backlogs/Sprints): Navigate to the Boards section in your Azure DevOps project. If you're using Agile methodologies, you'll find the iteration path while managing backlogs or sprints. It's usually visible when you create or manage these boards. Project Settings: Project Administrators or users with appropriate permissions can configure iteration paths within Project Settings. Go to Project Settings > Project Configuration, and there you might find the settings related to iterations where you can create or manage iteration paths. |
| Backlog iteration path | The backlog iteration path essentially refers to the specific iteration or sprint where backlog items are situated or planned. You can find your iteration path by following the below. Boards Section: Go to the Boards section in your Azure DevOps project. Navigate to the specific board corresponding to your backlog (e.g., "Backlog" or a custom board). On this board, you might see an option to switch between iterations or sprints. The current iteration or sprint selected here represents the backlog iteration path. Backlog Navigation: When you create or manage these backlog items, they are typically associated with an iteration or sprint. This association signifies the backlog iteration path. Iteration Settings: Project Administrators or users with appropriate permissions can configure iteration settings that might include defining which iterations are associated with the backlog. Go to Project Settings > Project Configuration, and within the Iterations or Sprints settings, you may find configurations related to the backlog iteration path. |
| Area path | The area path represents the organizational structure or hierarchy within a project. It helps in categorizing and organizing work items into different areas or teams within the project Work Items: Open any work item within your Azure DevOps project, such as a user story, task, or bug. Look for the field named "Area Path" (or sometimes just "Area") among the work item's details. It's often located alongside other fields like "Iteration Path," "Assigned To," etc. Boards and Backlogs: Navigate to the Boards section in your Azure DevOps project. Depending on the setup, you might see options to filter or view boards and backlogs based on area paths. This allows you to focus on work items within specific areas or teams. Project Settings: Project Administrators or users with appropriate permissions can configure area paths within Project Settings. Go to Project Settings > Project Configuration, and there you might find the settings related to area paths where you can create or manage area paths for your project. |
| Team project | A Team Project is the top-level container that holds repositories, pipelines, boards, and other resources related to a specific project or product. Below is where you can find the team project name: Azure DevOps URL: The URL for a specific team project will usually follow this format: https://dev.azure.com/[organization_name]/[project_name]. You can directly navigate to a project by using its URL. Azure DevOps Administration: Users with appropriate permissions can manage team projects through Azure DevOps administration. Access Azure DevOps administration by clicking on the organization settings. Here, you can create, delete, or manage team projects and their settings. |
| Update status from DevOps | Allow both Fluid and DevOps to update the status of the board tasks. The status Sync mode can also be set here. See Status Sync mode of this document for a detailed explanation. Note: if not turned on, the status updates made in Fluid on the board tasks will not be synced to DevOps. DevOps status changes will not be reflected back into fluid. |
| Allow Delete in DevOps | Allow Fluid to delete tasks in DevOps. Note, this is a non-destructive action, this is a soft delete in DevOps and can be restored from within DevOps itself. The retention policies is project specific, consult your site administrator for exact retention times. |
| Allow Attachments to be synced from Fluid to DevOps | When enabled will link attachments from the Fluid Item to DevOps. Attachments are url 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 DevOps. 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 DevOps item be used as part of the % complete calculation. If the DevOps 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 DevOps. |
| Status Mapping | Configure the status columns that will be mapped in DevOps for when tasks statuses are being updated. |
| Task Types Mappings | Configure the task types that will be mapped to DevOps. Only Tasks that have been configured and mapped will be used to integrate with DevOps. |
| 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 DevOps, 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:
DevOps may change their specific settings and configuration between versions and deployments. The details below are correct at the current time but visit https://learn.microsoft.com/en-us/azure/devops/organizations/?view=azure-devops for more up to date information.
In your DevOps instance:
1. Sign in to Azure DevOps:
- Go to your Azure DevOps organization's URL (e.g., https://dev.azure.com/[organization_name]).
2. Access User Settings:
- Click on your profile icon (top-right corner) to open the menu.
- Select "Security" or "User settings" (the exact wording might vary based on your organization's settings).
3. Personal Access Tokens:
- Look for an option like "Personal access tokens" or "PATs."
- Click on this option to navigate to the Personal Access Tokens page.
4. Create a New Token:
- On the PATs page, click on the "New Token" or "Create Token" button.
5. Token Configuration:
- Enter a name for your token. This is for your reference and can describe its purpose or usage.
- Choose the organization or project scope for the token's access.
6. Choose Access Level and Scopes:
- Select the level of access the token should have (e.g., full access, read, write).
- Specify the scopes or areas the token will have access to (e.g., work items, repositories, pipelines).
7. Set Expiry Date:
- Set an expiration date for the token.
- Ensure you set a suitable expiration date in line with your start/end dates of your project.
- You can edit your token and extend the expiry at a later date.
8. Create the Token:
- Click on the "Create" or "Generate" button.
9. Copy and Save the Token:
- Once generated, the PAT will be displayed only once. Copy it and store it in a secure place.
- Treat this token like a password; it provides access to your Azure DevOps resources.
Remember:
Security: Keep your tokens secure. Avoid sharing them openly.
Revocation: If a token is compromised or no longer needed, you can revoke or delete it from the Azure DevOps portal.
Status Syncing
When enabled, this option controlled the behaviour of syncing status from DevOps 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 DevOps and the item will be updated accordingly.
- If DevOps status is changed, when the configured synch job runs, the fluid card will be updated to match the status of the DevOps 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 DevOps item being created. DevOps by default will create the DevOps item in its default status as defined for that task type within DevOps itself. View your DevOps configuration for each task type within the DevOps 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 DevOps. Any subsequent changes in status in Fluid will not be reflected in DevOps. You can continue to update the status in Fluid, and the status will appear changed in Fluid, but the linked item status in DevOps will not be changed.
- One-Way [Push]
- Any change to the status in Fluid is sent to DevOps . However, no status from DevOps 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 DevOps item is pulled into Fluid and overrides the current status of the Fluid item, when sync occurs. Use this if you intend DevOps to be the gold standard source of status for the item.
- Two-Way [Sync]
- The Fluid status and the DevOps status are kept in sync. Any changes to Fluid are sent to DevOps and vice versa any DevOps 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 DevOps to ensure that when a task's status is updated in Fluid it is synced in DevOps.
Note: If the statuses are not mapped out, the updates made in Fluid on the tasks will not be integrated to DevOps. 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 DevOps. In Addition, "Not Started" and "Returned" have both been mapped to "To Do" in DevOps.
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 DevOps.
Note: DevOps can be inconsistent with its letter case and naming conventions. When configuring the DevOps field, it is best to ensure the exact same letter case is used, upper and lower as it is exactly defined in DevOps.
Common Properties Syncing Mode
- Create-Only [Push]
- Fluid properties are sent once and only on item create to DevOps. Any subsequent changes to properties in Fluid are not be reflected in DevOps. You can continue to update properties in Fluid, and they will appear changed in Fluid, but the linked item properties in DevOps will not be changed.
- One-Way [Push]
- Any changed properties in Fluid are sent to DevOps . However, no properties from DevOps 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 DevOps item are pulled back into Fluid and override the properties values of the Fluid item, when sync occurs. Use this if you intend DevOps to be the gold standard source of properties for the item.
- Two-Way [Sync]
- The Fluid properties and the DevOps properties are kept in sync. Any changes to Fluid are sent to DevOps and vice versa, and any DevOps changes to properties are synced back into Fluid when the Sync process runs.
Task Type
For each task that you want to create a DevOps item in your workflow, the Task Type needs to be defined and mapped to the equivalent type in DevOps .
If the a Fluid Task type is not mapped, then no corresponding item is created in DevOps 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 DevOps .
Synchronising Fields from DevOps into Fluid
Each time a board task/card is updated, the changes are synced to the card on DevOps. Below is an example of a card created on a fluid board and how it is represented in DevOps.
This is the card created in DevOps as a Feature.
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 DevOps item into fluid.
"In Progress" status shows the DevOps item is currently being worked on. You can click on the title "Risk Matrix Chart" to view the actual item itself in DevOps.
"0% Done" indicates that the % complete calculation is set to 0%, no items associated are in a done/completed status.
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 DevOp. It is the same job that runs at the set frequency as defined in the earlier configuration.
If you only want to "Sync Integration" on this one card you can click the "Last sync: 01 Dec 2023 10:23" text, to trigger an update for this one item only.
To further illustrate, IT/Tech team has added 3 subtask in DevOps this parent item in the example below. This displays how IT/Tech team manages the DevOps 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 DevOps 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 child-tasks, they are free to work off of the parent DevOps issue and update it accordingly, use it in sprints etc. Child tasks are the recommended DevOps 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 DevOps item, clicking on “Open DevOps ” will link you directly to the DevOps item in a new browser tab.
The “30 Mar 23” is the due date that has been set on the DevOps 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.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article