Enhancement: extend 'flow run get' with approver information

[klubis]

Description

Power Automate portal allows to get all flow runs as JSON response that includes approver information along with other properties. However, m365 CLI Flow Run Get returns only subset of the flow historical data.

Steps to reproduce

Open Power Automate portal -> My Flows -> Choose Flow -> Click on All Runs -> Get .CSV file

Expected result

"body": {
    "responses": [
        {
            "responder": {
                "id": "2acd63ea-863e-4281-9bb7-edc6fca7b0a3",
                "displayName": "s",
                "email": "",
                "tenantId": "67e88f39-f855-4d41-xxxx-xxxxx",
                "userPrincipalName": "xxx"
            },
            "requestDate": "2020-09-21T08:27:10Z",
            "responseDate": "2020-09-21T08:27:51Z",
            "approverResponse": "Approve"
        }
    ],
    "responseSummary": "Approver: xxx, xxx\r\nResponse: Approve\r\nRequest Date: Monday, September 21, 2020 8:27:10 AM\r\nResponse Date: Monday, September 21, 2020 8:27:51 AM",
    "completionDate": "2020-09-21T08:27:52Z",
    "outcome": "Approve",
    "name": "16f35689-d90f-4a50-xxxx-ac89fa5a7ecb",
    "title": "New Item Approval",
    "requestDate": "2020-09-21T08:27:09Z"
}

Actual result

Running m365 flow run get -e xxx -f yyy -n zzz -o json
Returns following JSON without any reference to flow approver, like user principal name, email, outcome and etc.
Is it possible to add these properties to the output of the function? Can we use options --query to expand return properties?

{
"name": "xxx",
"id": "/providers/Microsoft.ProcessSimple/environments/yyy",
"type": "Microsoft.ProcessSimple/environments/flows/runs",
"properties": {
"startTime": "2020-09-22T04:59:25.1666534Z",
"endTime": "2020-09-22T05:01:52.6243125Z",
"status": "Succeeded",
"correlation": {
"clientTrackingId": "xxxx"
},
"trigger": {
"name": "When_an_item_is_created",
"inputsLink": {
"uri": "xxx",
"contentVersion": "2O1Lig/PbQxBA3UIjmz/aA==",
"contentSize": 367,
"contentHash": {
"algorithm": "md5",
"value": "2O1Lig/PbQxBA3UIjmz/aA=="
}
},
"outputsLink": {
"uri": "yyy",
"contentVersion": "v0qWvwJ/Gc+VUhFTzNNX+g==",
"contentSize": 3182,
"contentHash": {
"algorithm": "md5",
"value": "v0qWvwJ/Gc+VUhFTzNNX+g=="
}
},
"startTime": "2020-09-22T04:59:24.92999Z",
"endTime": "2020-09-22T04:59:25.0706232Z",
"scheduledTime": "2020-09-22T04:59:24.830353Z",
"originHistoryName": "xxx",
"correlation": {
"clientTrackingId": "xxx"
},
"code": "OK",
"status": "Succeeded"
}
}
}

Environment

Latest CLI running on Windows 10 PRO in VS Code

[waldekmastykarz]

Thank you for reaching out to us. I wouldn't say this is a bug. There is a chance there is a difference between what information is exposed in CSV and what's available when calling the API. That said, we should have a look at what's in the API and if there is a way for us to get this information.

[klubis]

Greatly appreciated your help. Thanks.

[appieschot]

According to this post https://powerusers.microsoft.com/t5/General-Power-Automate/How-to-export-Approval-Flow-Data-through-Rest-API-in-power/td-p/593198 there is no way to achieve that with REST currently. I do not see a way to get the data in the flow run list command.

However hacking a bit with Fiddler makes it look that we could call the endpoint https://emea.api.flow.microsoft.com/providers/Microsoft.ProcessSimple/environments/[env]/flows/[flowid]/exportRuns?api-version=2016-11-01. That would return us a job that we can query to see if the CSV export is ready, and download the file once it is ready. Would a potential command flow run export help you? We would have the exact same result as the UI export. If that would help you I could draft a spec.

[waldekmastykarz]

Good find! The question is if we can get a token for that endpoint. If we can, then I'd be all for extending the command. Let's double check that before proceeding.

[appieschot]

Just found our previous issue: #1827 with quite some background already 😄 I am happy to do a quick check on the command. @klubis did you have a look at that endpoint by any chance?

[Adam-it]

@appieschot, @klubis did you had some time to have a double check on that endpoint and how we may use it?
@pnp/cli-for-microsoft-365-maintainers this issue seem quite old and with little attention, maybe we could revisit this one?

[appieschot]

I have not; perhaps we can take this into account when we work on our #3670 epic?

[Adam-it]

ok adding the needs research label and lets hope we will find time to investigate it along the way 👍.
thanks @appieschot . You rock 🤩

[nicodecleyre]

Hi 👋 ,

When exporting a flow run as CSV, as explained in the 'Steps to reproduce', it exports every action of the flow run. Flow actions are not exported with the command m365 flow run get, but we could do this by adding an extra option includeActionsInformation.

When doing a get request to the following api, we can get the actions of a flow run

GET https://management.azure.com/providers/Microsoft.ProcessSimple/environments/[EnvironmentName]/flows/[FlowName]/runs/[RunName]/actions?api-version=2016-11-01"

every action that has the status 'Succeeded' has an inputsLink.uri and/or an outputsLink.uri, both uri's can be called anonymously and we can add their body responses to the output of m365 flow run get.

Why both? Because the approval action information can be found in the body response of the outputsLink.uri while it doesn't contain an inputsLink.uri value. While the send an e-mail action information can be found in the body response of the inputsLink.uri while the outputsLink.uri body response is empty.

[mkm17]

HI @nicodecleyre , I have also checked this task. After analyzing the requests invoked in Power Automate, I noticed that it is possible to retrieve information about the run actions by adding expand=properties/actions to the request, which is present in the current m365 flow run get. I am wondering if we should call inputsLink.uri and outputsLink.uri for all actions. When considering the use case for monitoring the flow, I would like to have information about some crucial actions. Perhaps, we can add --includeActionsInformation to obtain basic information about actions and --includeActionsDetailsFor "Get_items,Compose" to get details only for specific actions. Just in case, the users would have inputsLink.uri and outputsLink.uri to get the necessary information.

[Adam-it]

HI @nicodecleyre , I have also checked this task. After analyzing the requests invoked in Power Automate, I noticed that it is possible to retrieve information about the run actions by adding expand=properties/actions to the request, which is present in the current m365 flow run get. I am wondering if we should call inputsLink.uri and outputsLink.uri for all actions. When considering the use case for monitoring the flow, I would like to have information about some crucial actions. Perhaps, we can add --includeActionsInformation to obtain basic information about actions and --includeActionsDetailsFor "Get_items,Compose" to get details only for specific actions. Just in case, the users would have inputsLink.uri and outputsLink.uri to get the necessary information.

@mkm17 this is an awesome find and IMO we could go with this approach.
Additional comment:
What if we only add a single option like --includeActionsInformation and if left empty it will return get details (the input/output Link.uri) for all actions. And it would be also possible to pass specific actions as you mentioned to get info only for them. That way we would only include a single option and not two. I would suspect at first run the user will want to check all the details anyway, and then he or she would amend the command to get only the specific details for the action they are interested in.
Also having a single option for that instead of two removes the additional validation and strange behavior we would need to handle of someone would execute the command specifing both options 🤷

@pnp/cli-for-microsoft-365-maintainers
Any other comments on that? If not let's open it up.
BTW @mkm17 are you by any chance willing to work on this?

[martinlingstuyl]

Second to your idea @Adam-it: Let's just add a single extra flag that determines if we will retrieve additional action details.
Get details of all actions by default, or specify a list of actions to retrieve the details for seems like a nice addition to me.

[mkm17]

@Adam-it @martinlingstuyl
Thank you for checking. I believe it's a better idea :) Please feel free to assign me to the task.

[Adam-it]

@Adam-it @martinlingstuyl
Thank you for checking. I believe it's a better idea :) Please feel free to assign me to the task.

All yours 👍

[waldekmastykarz]

Could we shorten the flag's name to --withActions to make it more convenient to use?

[mkm17]

@waldekmastykarz Hi, in the current command, there is the flag --includeTriggerInformation to include trigger. Perhaps --includeActions would be better, just to have a consistent convention.

[waldekmastykarz]

Thanks for bringing it up @mkm17. I find it overly verbose and would suggest that we shorten --includeTriggerInformation to --withTrigger. To avoid breaking changes, we'd introduce a new option and show a deprecation message when using the --include... variant until the next major, when we'd remove it.