Have you ever opened an Azure DevOps item and experienced an overwhelming amount of information screaming at you, with Business Rules, URL’s and links to attachments files everywhere?
While you review the content and try to understand what all the rules mean and where are the documents pointing to, you also notice that files are stored in the Attachments section of the DevOps item.
This is so confusing… So where do you even start looking you wonder?
I love managing my client requirements in Azure DevOps Boards.
Azure DevOps let me create a Product Backlog with all the items, features, and requirements needed for the solution I am implementing. I can organize the items by Epic, Features, Stories, have different states, assign tasks and track conversations for each of the individual items
However, the one thing that I always find challenging is when there is no consistency in documenting requirements details. Often different users will do what is more natural for them. Some will store documents in the Attachments section. Others will point to external locations where documents and rules are stored. And yet other users will copy and paste detailed business rules directly into the Acceptance Criteria of your User Story.
If there are no defined ways of working, your User Stories can quickly become very messy and difficult to understand.
My way of dealing with this.
1. Avoid attaching documents into the Attachment section of the User Story.
I personally try to stay away from attaching documents into the Attachment section. Unfortunately, there is no easy way to reference an attached document (ex: Get the URL of that document so that you can refer to it in your Acceptance Criteria) or update a Word or Excel file once they are stored in the attachment section.
If you need someone to review rules and provide feedback, they will need to download the file, make their changes and reupload the same file again.
DevOps doesn’t even replace the files if you upload the file with the same name. See below how I just uploaded 3 times the same file:
Yes, in some occasion you might want to force a file to be fixed and make sure no one edits it. But a user can still delete the old file and upload a new one in if they want.
2. Store Business Rules or complex decision trees into external files.
So how can I make it easier to store my files in a Microsoft Teams file folder or a SharePoint folder I wondered? SharePoint provides natively the ability for people to edit documents directly in the cloud and collaborate. SharePoint will also take care of versioning and tracking changes.
Well, it appears that there is no direct integration between DevOps and SharePoint, however, with the tools that we have available, building that integration only takes a matter of minutes these days.
So after a few tweaks, I managed to clean up my Story to look somewhat cleaner and easier to understand.
So what have we done:
- All Business Rules or complex decision trees are stored in external files and we only reference the links to those tables in the Acceptance Criteria.
- All documents and attachment are stored in 1 central location in SharePoint. For my stories I like to have the following structure in SharePoint: Documents > General > DevOps Items > [Item ID – Item Title]
- All URL’s have been replaced with a description hyperlink and only point that one location where all the attachments are stored.
- We have configured a Power Automate to automatically create a SharePoint folder on creation of a DevOps User Story. The Power Automate also stores back that SharePoint location URL into a custom field of the DevOps User Story. This way, we can easily access that SharePoint folder directly from our User Story.
Steps to configure the Azure DevOps field and the Power Automate.
Open the item where you would like to add your SharePoint location link. In the example below, I am adding the new field to a Feature item type.
1. In the Feature item, click on the … and then on Customize.
2. Under the Layout tab, click on the New field button.
3. Define a Name and a Type for the field. Make sure to select the Text (multiple lines) field type.
4. Once done, edit the field again and navigate to the Options section and copy the value under the Field Reference Name. (E.g. in this case, copy in your notepad the value Custom.SharePointFolder). You will need this Field Reference Name in the Power Automate that you will build in the following steps.
5. When done you should see your new field added to the Feature item type.
If you are using MS Teams.
1. Navigate to the Files section and click on Open in SharePoint button.
2. Copy somewhere the URL to your SharePoint as show below. (E.g. Here the value you need to copy is https://datasense.sharepoint.com/sites/Dynamics365AgileTemplate). You will need this value for the Power Automate that you will build in the following steps.
If you are not use MS Teams, you can just create or use an existing site.
Now that we have the new field in DevOps and the SharePoint site is ready to be used. It’s time to create the Power Automate that will automatically create a new Folder in SharePoint for the DevOps Item.
The Power Automate will also populate the URL of that folder back into the DevOps item so that you can easily navigate from DevOps into the item folder in SharePoint.
1. Start by creating a new Power Automate with the Azure DevOps > When a work item is created trigger. Make sure you select the item Type you want your trigger to fire on. (E.g. In this case I want my trigger to fire on creation of a new Feature in Azure DevOps).
Then add the SharePoint à Create new folder action. Make sure to find the SharePoint URL that matches the one you copied in MS Teams – step 2. Then under List or Library select Documents and then for Folder Path, you can define how the folder structure for your DevOps items should look like. (E.g. In this case I want my structure to look like Documents > General > DevOps Items > 67 – Satisfaction surveys).
Then finish your Power Automate with Azure DevOps > Update a work item action to update your DevOps item with the URL to the new folder you just created in SharePoint.
Now when you create a new Feature in DevOps, a new folder is created in SharePoint and you will see the URL of the folder directly populated in your new field in Azure DevOps.