How to configure Azure Devops to Fluid Boards integration

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.

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. 

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

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.

Below are the required configuration details:

1. The unique client ID GUID for the service principal.

2. 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. 

3. 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.

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.

Below are the required configuration details:

1. PAT token as generated from your DevOps instance

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.

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.

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.

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 grey. This is to indicate this is the starting status for created items. The last row is coloured green to indicate this is the Final item status. All other statuses are blue, 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.

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.

• 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.

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 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 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 .

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.

• Sequence diagram for Fluid to DevOps Integration