When working with Microsoft Dataverse, have you ever tried to figure out what exactly is happening behind the scene, and why that specific column is getting a certain value which you would not expect it would be getting?
One might think it is easy to do, but consider how many ways are there to actually change that column value:
- A Power App (canvas or model-driven) can make a change
- A Power Automate Flow can make a change
- A plugin can make a change
- A classic workflow can make a change
- And this is not to mention possible integrations/external processes
The first 4 on this list are not even exceptional in any way – they are just something we would use as/when we need, so, on a relatively large project, we would often end up having all of those mixed and matched based on such factors as:
- Available functionality (synchronous vs asynchronous is, probably, the most prominent example)
- Microsoft recommendations (use Power Automate, avoid workflows)
- “Center of excellence” recommendations (if a version of it exists in the organization)
- Business preferences, as strange as it sounds (low-code as much as possible)
- Project team preferences overall
- Personal preferences of the team members
And this can turn into a nightmare when there is no obvious structure to it, and when there is no documentation.
A record is created, and there is a Flow/Workflow/Plugin that kicks in. However, exactly because there can be different ways to respond, some logic might end up in the Flow, but other logic might end up in the plugin, and, yet, there could be a business rule or a javascript on top of that. Now, there could be valid reasons mixing everything – for instance, it’s quite possible that we would only want synchronous logic to be in the plugin, and the rest might be in the Flow since we would want functional consultants to work on those.
I always feel bad when another team member has to ask “where does this value get set – is it in the plugin? Is it in the Flow? Is is happening in Javascript?”
And I always feel frustrated when it’s me who is asking the same question.
Because, in either case, I usually have to spend quite a bit of time figuring out how do all those pieces work together and where exactly the change is happening.
Would not it be nice to have some kind of documentation, or, at least, some way of answering this kind of questions faster? This is exactly why, in the pro-code world, adding comments directly to the code has been recognized is the best practice (and has been well-documented). Here is one example:
https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/
However, there is no universal way of documenting Power Automate flows, workflows, plugins, scripts, etc. We could, probably, start creating diagrams/documents, but all those details are extremely difficult to document, and, even if someone were diligent enough to maintain that level of documentation, it might turn into a full-time job for that person on anything but a relatively simple project.
This is why, sooner or later, almost every project becomes a bit of a “black box” for new team members. This is not to say the same problem does not exist on the pro-code projects, but, because of the variety of tools, there just seem to be an extra layer in Power Platform.
Well, now that the skeleton has been uncovered… what do we do about it? I have no perfect answer, but here is what I’ve seen so far:
- For the plugins, apparently, commenting in the code helps. Putting some thought into the structure of those plugins helps, too
- With Classic Workflows, adding notes to the description may help to an extent
- With Power Automate flows, adding “notes” to the actions may be helpful. As well as filling in Flow description
- It also helps to keep high-level diagrams updated every now and then so that all those relationships between different parts of the system were a bit more clear
Although, as helpful as those can be, you will usually need a way to perform solution-wide search, and this is one benefit of using source control:
Personally, I don’t believe a lot of folks would have the ability to do advanced changes directly in the the extracted xml / json files in the source control without breaking something. However, it’s easy to perform search over all those files to find a column name, and that can help identify all low-code/pro-code components which are using that column quickly.
Although, that does require some discipline, yet the clients need to understand the importance of this for future maintenance and support. Which, again, is not always the case – it usually comes as the clients, projects, and teams mature.
And, yes, I had my share of projects where I would not put enough efforts into documenting implemented solutions. Although, to my (somewhat lame) excuse, in many cases there would be no one to provide this kind of documentation to. Which is just how those skeletons end up being stuck in the closet.
PS. Do you have a “skeletons story” to share for the month of October? Everyone’s invited:
