Power Platform Documentation: How Gen AI can help

In my current role as a Power Platform consultant and developer, I have been confronted more than once with the situation that documentation of Power Platform solutions is an important part of development. This we already know: writing documentation is not always the most popular task for developers.

At the risk of repeating myself, I would nevertheless like to emphasize that proper documentation is also an indispensable standard in Power Platform solutions.

Don’t always reinvent the wheel – let Gen AI help you

Writing documentation is not always easy. But you don’t always have to reinvent the wheel! There are some best practices that can help you to document your Power Platform solutions more effectively. In an other article, I have already described some kind of best practices, which I’ve experienced in my daily work: Power Platform Solution Documentation Tips.

As the age of AI brings us new possiblities in regards to generating content: why not make use of Generative IA when it comes to documentation? In addition to my best practices mentioned above, I have also started to experiment with Github Copilot. Especially with the help of Anthropic Claude 3.5 or 3.7 (even if it is still in an experimental stage), it is possible to let Copilot generate a really good documentation for you. Could this be a good starting point for your own documentation?

Read on to see how Gen AI can help you create simple and uncomplicated Power Platform documentations.

Documenting Power Automate workflows

When it comes to documenting Power Automate workflows, it is important to provide a high-level overview of the workflow, its connections, triggers and actions. The documentation should be understandable to developers, administrators and other stakeholders.

Example: Github Copilot prompt to generate a description

Inject the JSON definition of your Power Automate workflow (you can make use of the CLI for Microsoft 365 command m365 flow get [options] which you can find here: https://pnp.github.io/cli-microsoft365/cmd/flow/flow-get). Let the Github Copilot (within “Edits”) generate the description for you by using the following prompt:

You are a documentation assistant for creating technical documentations for Power Platform resources.
Summarize a given Power Automate workflow's JSON structure by categorizing the summary in these topics groups:

- 1. Connections: list of used connections and connection references as well as the according permissions. Make sure you mention "Connection reference" in case of a connection reference is set (set it on top of the listing and also provide the name of the connection reference in this case).
- 2. Owners, Co-Authors & Run-Only Users: list of Owners, Co-Authors and Run-Only Users as well as the according permissions
- 3. Trigger: describe the trigger that starts the workflow (as well as  its trigger conditions). Only provide these attributes: "Kind" (use label "Type") and "Schema"
- 4. Actions: High-level description with a list of all action groups that act as "blocks" of this workflow

Generate the output as a Markdown report that follows this structure:

# Description
Write a short summary by providing a high level description in a few sentences.

## Connections & Owners
Provide a table that contains this structure.
Insert connections and owners, Co-Authors & Run-Only Users:

| **Type**             | **Group / User**                       | **Permission** |
|----------------------|----------------------------------------|----------------|
| Connection Reference | <insert the connection reference here> |                |
| <Other connections>  | <insert the connection reference here> |                |
| Run-only User        | <reference all Run-only users>         |                |

Always provide a table row for Run-only users, even if they do not exist.

## Triggers & Actions

### Triggers
Provide the list with these list items:
**Name of the trigger**
- Type: the type
- Schema: the schema (in words)

### Actions
Provide a table that contains this structure:

| **Action Group**      | **Description**                                                      | **Connectors**              |
|-----------------------|----------------------------------------------------------------------|-----------------------------|
| 1. <Action Group>     | <High level description of the list of all contained actions>        | <Used Connectors as a list> |
| <other Action Groups> | <High level description of the list of all contained actions>        | <Used Connectors as a list> |
| x. Return             | <Description of how the workflow terminates and what it does return> | <Used Connector>            |

Provide a the markdown report using {my main language}.

This prompt could be a good starting point for generating a documentation for your Power Automate workflows. It is important to note that the generated content should be reviewed and adjusted by you. But it could be a good starting point for your own documentation.

Documenting Power Apps (Canvas Apps)

Documenting Power Apps is a bit more complex than documenting Power Automate workflows and can contain different aspects. Of course, several further aspects should be considered when documenting Power Apps.

For example it can be really useful to provide a high-level overview to provide a better understanding of the app, its workflows, permissions, and license requirements.

To start with an easy approach, you could use PowerShell and Github Copilot to generate a high-level overview.

Example: Create a High-level documentation of a given Power App

High-level overview of a Power App documentation should include the following aspects:

• Solution details (configurations and common information about the solution)
• App details (name, type, connections, connector types)
• Workflow details (workflows, triggers, connections, connector types)
• Permissions (and maybe permission roles)
• License requirements

This is an example of how a high-level documentation could look like:

Let’s start with a simple approach on how you could work this out with the help of PowerShell and Github Copilot. In this two-step approach, you first generate some context before then Github Copilot can be used to generate a detailed description of the app and its workflows.

PowerShell script to get app details and definitions (context)

Following script uses the CLI for Microsoft 365 to get the app details and definitions. Therefore, admin permissions are required. The script first gets the app details and then extracts the workflows and the workflow definitions.

An app documentation file as JSON as well as workflow documentation files for every workflow (JSON), as an example:

├── your current folder/
│   ├── App – My awesome app.json 👈 the app's technical definition
│   ├── Workflow – <Workflow 1>.json
│   ├── Workflow – <Workflow 2>.json
│   ├── Workflow – <Workflow 3>.json
│   ├── Workflow – <Workflow 4>.json
│   ├── ...
│── ...

These files can then be processed to generate a documentation as Markdown by using Gen AI (see following section).

# This script generates a high-level overview of a Power Platform solution

$settings = @{
    env = @{
        name = "Default-95c567d6-2321-424a-ac62-7345b1d26d12" # Environment id
    }
    app = @{
        name = "My awesome app" # The (displayed) name of the app
    }
}

### Get app details and definitions via CLI for Microsoft 365
$app = m365 pa app list --environmentName $settings.env.name --asAdmin --query "[?displayName == '$($settings.app.name)']" | ConvertFrom-Json
$appDefinition = m365 pa app get --name $app.name --environmentName $settings.env.name --asAdmin

### App documentation file
$appDefinition > "App - $($settings.app.name).json"

$app = $appDefinition | ConvertFrom-Json # Update app object with the full app definition

### Workflows
$app.properties.connectionReferences.PSObject.Properties | ForEach-Object {
    $id = $_.Name
    $connection = $_.Value
    
    if($connection.id -notlike "*apis/shared_logicflows" ) { return }
    
    $workflowName = $connection.parameterHints.workflowDisplayName.value
    $workflowId = $connection.parameterHints.workflowName.value
    
    "Connection (workflow): $($workflowName)"
    $flowDefinition = m365 flow get --name $workflowId --environmentName $settings.env.name --asAdmin
    $flowDefinition > "Workflow - $($workflowName).json"
}

Now you have several JSON files which you need to pass to Github Copilot to generate a cool documentation.

Github Copilot prompt to generate your documentation as Markdown

Use the following prompt to generate a high-level documentation of a Power App. It is important to provide the JSON files generated by the PowerShell script above.

You are a documentation assistant for creating technical documentations for Power Platform resources.
Summarize a given Power Automate workflow's JSON structure by highlighting the used connections and the appropriate licensing per user.

Get the flow definitions from the JSON files that start with "Workflow -". Put down following information in a table:

- Workflow Name (last modification date)
- trigger (how the workflow is triggered)
- all connections that are used in the flow
- derive the connector type for every connection

Then, generate the final report, based on the JSON file that starts with "App - ".
It must contain this structure:

---

# {the name of the solution}

## Solution Details (Configuration)

| Solution Name | Version | Publisher |
|---|---|---|

Very important: don't fill out the table in case if no information about the app was provided. Instead, provide a note that no information was found.

## Power App

This chapter shows the following details of the app's structure.
Take the details from the JSON file that starts with "AppDefinition".
Very important: don't fill out the table in case if no information about the app was provided.

Use the following table to display the information:

| Application (Last modification, format: dd.mm.YY HH:MM) | App Type | Data connection(s) | License designation |
|---|---|---|---|

- For "connector type(s)", denote the needed license for the according connector. Use the short description and avoid using the word "connector".
- In "Data connection(s)", list all connection references from the app structure from the property "connectionReferences". Provide how often each data is used by displaying the value within parentheses, in this format: Connection reference (amount). Only use values from the property "connectionReferences".
- For "License designation", use the following values:
  - "Standard" when only Standard connectors are used
  - "Premium" when at least one Premium connector is used
  - "Not applicable" if no connections are used

## Workflow Overview

| Workflow (Last modification, format: dd.mm.YY HH:MM) | Trigger | Connection(s) | Connector type(s) |
|---|---|---|---|

- For "connector type(s)", denote the needed license for the according connector. Use the short description and avoid using the word "connector".

Use a new table row for every given workflow.

## Recommendation

Describe the need of the necessary permissions for a user to make use of this app.
Also give hints how this app must be licensed in a proper way; avoid license grandfathering
as well as license muliplexing. Consider using seeded licenses whenever possible.
Avoid mention of advanced or Premium licenses when not useful.

In case of any suitable website from learn.microsoft.com, give an overview of these websites and always append this url param: ?wt.mc_id=MVP_383763

### Rationale

Summarize the rationale for your licence recommendation. Keep it to the point in 1-2 sentences.

---

Display the output in markdown and use {my main language}.

Store the generated content in a Markdown file: Docu - My awesome app.md. Now, your files’ structure should look like this:

├── your current folder/
│   ├── App – My awesome app.json
│   ├── Docu – My awesome app.md 👈 the generated documentation
│   ├── Workflow – <Workflow 1>.json
│   ├── Workflow – <Workflow 2>.json
│   ├── Workflow – <Workflow 3>.json
│   ├── Workflow – <Workflow 4>.json
│   ├── ...
│── ...

Example Content of Docu - My awesome app.md:

# My awesome app

## Solution Details (Configuration)

No solution information was found in the provided files.

## Power App

| Application (Last modification) | App Type         | Data connection(s)              | Connector type(s) |
| ------------------------------- | ---------------- | ------------------------------- | ----------------- |
| My awesome app (25.09.24 13:59) | ClassicCanvasApp | SharePoint (1), Logic Flows (4) | Standard          |

## Workflow Overview

| Workflow (Last modification) | Trigger          | Connection(s) | Connector type(s) |
| ---------------------------- | ---------------- | ------------- | ----------------- |
| Workflow 1 (17.09.24 11:23)  | PowerApp Request | SharePoint    | Standard          |
| Workflow 2 (17.09.24 11:23)  | PowerApp Request | SharePoint    | Standard          |
| Workflow 3 (17.09.24 11:21)  | PowerApp Request | SharePoint    | Standard          |
| Workflow 4 (24.01.25 13:18)  | PowerApp Request | SharePoint    | Standard          |

## Recommendation

For using this app, users need the following permissions:

1. Microsoft 365 license with SharePoint Online access
2. Power Apps permission for Canvas Apps (included in Microsoft 365)
3. SharePoint permissions for the relevant libraries and lists

Since the application and all workflows exclusively use Standard connectors (SharePoint and Power Automate), no additional Premium licensing is required. The app can be operated with the Power Apps licenses included in Microsoft 365 subscriptions (E3/E5, Business Premium).

Further information:

- [Power Platform Licensing: Overview](https://learn.microsoft.com/en-us/power-platform/admin/pricing-billing-skus?wt.mc_id=MVP_383763)
- [Licensing for Power Apps and Power Automate](https://learn.microsoft.com/en-us/power-platform/admin/powerapps-flow-licensing-faq?wt.mc_id=MVP_383763)
- [Overview of Standard Connectors](https://learn.microsoft.com/en-us/connectors/connector-reference/connector-reference-standard-connectors?wt.mc_id=MVP_383763)

### Rationale

The app exclusively uses Standard connectors (SharePoint) that are included in Microsoft 365 licenses and stays within the boundaries of the Power Platform functionalities provided by Microsoft 365 subscriptions, eliminating the need for additional Premium licenses.

With this, you could have a good starting point for your own documentation. If you like, you could even use Pandoc to convert the generated Markdown to a PDF or Word document.