Ever since I posted a video on how to use Flow to upload photos to SharePoint from PowerApps, I get a lot of requests for help with the most mysterious bit – the swagger/openAPI file…
To save you all much pain and suffering, here is a sample file that you can use to get started.
In this post I am going to assume you have watched the video and understand the intent. Here I will simply annotate the file with some notes that will help you customise and extend it for your own purposes.
Note 1: This only works for a HTTP request trigger in Flow
Flow is capable of being called like any other web service. To do so, you have to use the following trigger.
Note that the trigger states clearly “URL will be generated after save”, so the first thing to do is generate that URL…
Once you have done so, it will look like this:
If we break the URL it down, you will see:
- A domain something like <location>.logic.azure.com.
- A URL path of “/workflows/<instance ID>/triggers/manual/paths/invoke” which that identifies your specific workflow ID. Take note of this as you will need it.
- A parameter called api-version with a (at the time of writing) value of “2016-06-01” – eg api-version=2016-06-01
- A parameter called sp with an encoded value of “/triggers/manual/run” = eg sp=%2Ftriggers%2Fmanual%2Frun
- A parameter called sv with a value of 1.0 – eg &sv=1.0
- A parameter called sig with a random string value. eg sig=PeZc-ljtjmJhsz00SD78YrwEohTqlUxpQuc95BQQuwU
In combination, the URL looks as follows with the important bits in bold…
https://<location>.westus.logic.azure.com:443/workflows/<workflow instance ID>/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=<signature>
The bits in bold you will need to know, because they need to be added to the OpenAPI file. Why? because this file is what PowerApps uses to construct a HTTP call to your flow.
So let’s look at the Swagger File…
Note 2: Host, basePath and Path
Open the Swagger file and look for the section called “host”… Replace the section labelled [enter Flow URL here] with the URL from the flow Trigger I mentioned above. eg:
prod-23.westus.logic.azure.com:443 or prod-01.australiasoutheast.logic.azure.com:443
Now find the section labelled [enterid here]. This is where the workflow ID goes… so from this:
Note 3: Double check the sv, api-version and sp parameter sections.
All of the parameters expected by the Flow are specified in the OpenAPI file. You will see it in the “parameters” subsection of the “post” section…eg
Now for reference, each parameter section has:
- name: The name of the parameter as it appears on the URL
- in: specifies whether this parameter is in the query string, header or body. All of the default flow parameters are in the query string.
- default: This is the value to check!! If Flow is updated in future it is very likely this parameter will reflect it. Please do not come to me for support if you have not checked this!
- required: States that this parameter MUST be passed. PowerApps will not allow you to call this Flow without specifying this parameter
- x-ms-visibility: this basically says “use the default value and don’t show the user”. So in effect, the above “required” condition is met, but PowerApps will not ask the user to enter it.
- type: is self-explanatory. It tells PowerApps that the parameter is a string.
Note: For more detail on these parameters go and read the OpenAPI 2.0 standard and Microsoft’s documentation.
Note 4: Update the sig parameter…
The sig parameter is like an API key or a password. You need to paste it as the default value in your file like so…
Note: It is possible to set this up in PowerApps so that it has to be entered when a user adds a datasource. However I am not covering that here.
Note 5: Add (and remove) your own parameters…
This swagger file makes the assumption that PowerApps is going to send a file name for the photo, as well as a description, latitude and longitude. Note that all fields are set to required, but none have default values and the x-ms-visibility parameter is not specified, meaning that PowerApps will prompt the user to enter them.
Using the examples as a guide, add or remove parameters as you see fit.
Note 6: Set your function call names appropriately…
Going back to the top of of the file, update the description to suit the task you are performing. Pay special attention to “Title” and “operationId”, as PowerApps uses these. For example, based on the image below, you will be calling a function called PhotoHandler.UploadPhoto() from PowerApps.
At this point you should be able to save your file and register it as a custom connection and call it from PowerApps.
Note 7: Do not use the word “SharePoint” in your custom connector name
Believe it or not, if you name your custom connector with the word “SharePoint” it will confuse PowerApps completely. For example, consider this custom connector:
Now look what happens when you try to use it… you get the message “The data did not load correctly. please try again”, with a sub message of “Resource not found”…
The solution? Name your connector anything, so long as the word SharePoint is not there 🙂
If you intend to send data back to Flow, you will also have the define the schema for what is returned to Flow in the responses section. I have not added any custom schema in the sample swagger file and discussing it is outside the scope of this article. But in case you are interested, to get you started, below is an example of calling Microsoft’s QNAmaker chatbot service REST API and sending the results back to PowerApps.
Thanks for reading