A Sample OpenAPI/Swagger file for PowerApps

Send to Kindle

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.

image

Note that the trigger states clearly “URL will be generated after save”, so the first thing to do is generate that URL…

image

Once you have done so, it will look like this:

image

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 or prod-01.australiasoutheast.logic.azure.com

Note: The image below shows the port number shown (443), this no longer works so omit it altogether as shown in my 2 examples above.

From this…

image

To this…

image

Now find the section labelled [enterid here]. This is where the workflow ID goes… so from this:

image

To this..

image

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

image

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…

image   image

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.

image

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.

image

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 🙂

Parting notes…

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.

 

"responses": {
  "200": {
    "description": "OK",
    "schema": {
       "type": "object",
       "properties": {
          "answers": {
          "type": "array",
          "uniqueItems": true,
          "minItems": 1,
          "items": {
             "required": [
                "answer",
                "score"
             ],
             "type": "object",
             "properties": {
                "answer": {
                   "type": "string",
                   "minLength": 1
                },
                "questions": {
                   "type": "array",
                   "items": {
                      "type": "string"
                   }
                 },
                 "score": {
                   "type": "number"
                 }
              }
           }
        }
      },
       "required": [
         "answers"
       ]
    }
 }

 

Thanks for reading

Paul Culmsee

Print Friendly, PDF & Email
 Digg  Facebook  StumbleUpon  Technorati  Deli.cio.us  Slashdot  Twitter  Sphinn  Mixx  Google  DZone 

No Tags

Send to Kindle
Bookmark the permalink.

37 Responses to A Sample OpenAPI/Swagger file for PowerApps

  1. Brad says:

    If I could figure this out, I would finally be able to accomplish what I need for my PowerApp. I just want to simply upload a picture to a Sharepoint library, and be able to not only include the picture\’s filename, but also to include the \”job number\” , and \”description\” of the picture so I can sort the Sharepoint columns easily. However, i\’m not having any luck making this happen. I can upload the picture to the library, but when I try to add the other properties of the picture, i\’m not having any luck. Is there anyway that you could help me!?

  2. Diana says:

    Hi Paul
    Thanks for the info. I managed to upload picture successfully,I have one question, the file that was created in the shared point is somehow always pointing to me as the creator (created by in the file property) , regardless who ever is using the apps to upload the file. I understand we dont pass any parameter in the JSON file to define this, as i assume it should be created automatically by Flow using the user profile. Do you know how we can rectify this? this is asmall issuebut im very eager to eliminate it

  3. admin says:

    Hi Diana

    It’s trickier than it seems. a Custom connector runs in the context of the person who created it. To change this, one has to use some trickery 🙁 Let me know if you want some more detail, but I can confirm its not overly simple…

  4. Dave Huddleston says:

    Hi Paul,

    Great Tutorial, Very appreciative of you taking the time to explain this. I got everything to work as you have described but can’t seem to get the custom connector added to PowerApp’s I get a DLP violation. which is very odd. So i figured I’ll move this over to Azure Function App seemed simple enough. used the Swagger file and OpenAPI to generate a new function on Azure. Do i need to grant

  5. Pete says:

    Hi Paul

    Please share on how I could rectify the similar issue as mentioned by Diana. Would love to see the Modified by column showing the user name instead of mine. Also, I could not preview the photos uploaded in SP for unknown reason. Thank you.

  6. admin says:

    The inability to preview is likely that you did not convert the images from base64 back to binary. There is a flow WDL function available for that. As for the updating modified by, that requires to set the AllowUnsafeUpdates property which I assume can be done via REST API. I have not done this so will look into it… eg https://threewill.com/update-sharepoint-online-system-fields-via-csom/

  7. Paul O'Flaherty says:

    Thanks Paul – unfortunately I’m getting authentication errors when I try to run the Flow via PowerApps. I’m the only user on my dev tenant so PowerApps is running under the same ID/context as was used to create the Connector.
    Could this be related to the Sig? Can this just be any text of any length? I haven’t yet found information on the relevance of Sig.

  8. admin says:

    The sig is *super* important. It is in affect an access token. It is generated as part of the HTTP trigger on your flow. That’s where you get it from…

  9. Chris says:

    Paul, your video on this was excellent and even a Sharepoint/365 noob like me has got it *almost* working!

    I’m down to an authentication error when I click “New” and start filling out the form. I saw elsewhere that I need to make sure the parameters are correct. They all have default values that were pulled from the URL and set to required and appropriate ones set to Internal (all but filename, right?)

    The error persists but I have no other context. Do you have any other suggestions on what might be causing this error? Thanks!

  10. admin says:

    remove :443 from the host section of the swagger file. That seems to be a recent change…

  11. Chris says:

    Paul, thank you for your response. I’ve removed that but still have the same authentication error.

    Do I need to rebuild the connector from scratch after I remove the :443 from the file, or can I just edit the connector and remove it from the Host field and update?

    Maybe there’s another issue.

  12. admin says:

    send me your file or contact me via linkedin and I’ll send you a working file to compare…

  13. Lee says:

    Hi Paul,

    This is great. I watched your youtube video on submitting a photo through powerapps, which then triggered FLOW to save the record into Sharepoint.

    I do have a question though in regards to error handling. In the event that FLOW stops/is not turned on, is there a way for powerapps/custom connector using the Open API file you shared above, that we can use to inform a user of the error message received (if there is one)? Do you know a way that we can reference the JSON body response from the connector in PowerApps for this?

  14. Anthony says:

    Hi,

    The link to your swagger file is broken. Do you mind updating it?

  15. admin says:

    Hi Anthony

    I just tested it and it works fine. It is possible your company is blocking onedrive?

    Paul

  16. James Reynolds says:

    Hi Paul, great video thank you very much. However I am stuck creating a custom connector I get this error
    The request failed with error: ‘{“Code”:”ValidationError”,”Message”:”One or more fields contain incorrect values:”,”Target”:null,”Details”:[{“Message”:”One or more fields contain incorrect values:”},{“Code”:”ValidationError”},{“ErrorEntity”:{“ExtendedCode”:”Entity field:apiDefinitionUrl”,”InnerErrors”:[{“Parameters”:[“value[0].responses[0].representations[0].contentType”,”apiDefinitionUrl”],”Code”:”ValidationError”,”Message”:”‘contentType’ should not be empty”}],”Code”:”ValidationError”,”Message”:”One or more fields contain incorrect values}}],”Innererror”:null}. The tracking Id is ‘634a9933-5d77-41ca-9e23-b56a5bfc9bfe’.

    Andy ideas please?

  17. Kristine says:

    Hi Paul,

    I get the same Error Message as James when I try to make a custom connector. Any help would be appreciated!

  18. admin says:

    It is telling you the API definition URL is empty. You need to edit my OpenAPI file and update the URL before you load it. Double (triple) check you have the URL right 🙂

  19. admin says:

    Oh, we just found out that adding :443 to the end of the URL for host might be the culprit. Try removing “:443”

  20. Chris Rowles says:

    Hi Paul, I have followed your instructions and despite a sucessful result, I am getting the following error even though the photo uploads to SharePoint and all the correct metadata gets added!

    PhotoHandler.UploadPhoto failed: Exception message: ‘Unknown error.’ Exception call stack: Error at d (https://paplayercdn-int.azureedge.net/appresources/08ma4a1cra84f/js/Core.js:1:15269) at f (https://paplayercdn-int.azureedge.net/appresources/08ma4a1cra84f/js/Core.js:1:15377) at Object.n [as checkNonEmpty] (https://paplayercdn-int.azureedge.net/appresources/08ma4a1cra84f/js/Core.js:1:14697) at Function.n.createFromArrayBuffer (https://paplayercdn-int.azureedge.net/appresources/

    Any ideas?

  21. admin says:

    Hi @chris, I really need to see your custom connector and try it on this end… Never seen that error before.

  22. Alex says:

    Hi Paul,

    if followed your instructions. But by creating a custom connector i got this message.

    Fehler bei der Anforderung: {“Code”:”ValidationError”,”Message”:”One or more fields contain incorrect values:”,”Target”:null,”Details”:[{“Message”:”One or more fields contain incorrect values:”},{“Code”:”ValidationError”},{“ErrorEntity”:{“ExtendedCode”:”Entity field: apiDefinitionUrl”,”InnerErrors”:[{“Parameters”:[“contract”,”apiDefinitionUrl”],”Code”:”ValidationError”,”Message”:”Parsing error(s): Invalid type. Expected String but got Null. Path ‘paths./{connectionId}/090dc30a6e25408daf458a9a03084e85/triggers/manual/paths/invoke.post.produces[0]’, line 31, position 14.”}],”Code”:”ValidationError”,”Message”:”One or more fields contain incorrect values:”}}],”Innererror”:null}. Die Nachverfolgungs-ID lautet “52ab2

    – Tried removing “:443
    – Double (triple) checked the URL

    Can you give me a hint?

    Thanks bevorehand

  23. Andri says:

    Hi, I’m having the same problem. Same error. Tried the fixes mentioned but nothing works.

  24. Leigh says:

    new to this so any help with the procedure / steps to have the other parameters (lat, long, desc) populated in the library would be most helpful. other than that it works great.

  25. Alan Hoiland says:

    Hi – Is there any way to use this with other file types? Word, PDF, etc.
    Thanks!

  26. Vipul Kelkar says:

    Thanks for the great explanation in the video and the swagger file. In my case, the SharePoint site where the user wants to upload the file is not fixed and is decided in the PowerApp form by the user himself, in which case I cannot use the SP connector in Flow to create file in the Library 🙁 Guess I’ll have to go down the Azure function route !!

  27. Christoph_G says:

    Hey Alex and Andri,

    I ran into the same problem and didn’t understand why the error refers to the “apiDefinitionURL” since this didn’t seem to be the problem. It’s a null-value he doesn’t like.

    Solution:
    Find…

    “produces”:[
    null
    ]

    …in your code and delete the “null” to make it look like this:

    “produces”:[ ]

    Hope this helps – it did for me 🙂

  28. Alex says:

    Thank you Christoph,

    Im a step forward, but now accures another error.

    {„error“:{„code“:“AuthorizationFailed“,“message“:“you do not have the permissions to provide this action \“run“ for the section \“/triggers/manual/paths/\“. …

    any body an idea?

    Thanks

  29. Andri says:

    That worked, I’ve got my connector. But the photos don’t save to my sharepoint now. They did when I tested with Postman, but the app doesn’t send the photos. Argh, so close!

  30. Andri says:

    I can see now that when adding the ForAll(PhotoList,PhototoSP.PostPhoto(filename,content-type,file) line in onSelect, PowerApps prompts me for an additional variable, content-type.

  31. Andri says:

    Deleted content-type from Header in the custom connector to solve this.

    Now getting “Authorization failed” on PostPhotoToSP.PostPhoto, “the authentication credentials are not valid”

  32. Alex says:

    I have the same problem.

  33. Alex says:

    Could be this problem coused by the licence type?

    Because my license doesn’t support the use of gateways. To use this feature, start a trial.

  34. Jonny says:

    RIght Now i get it Working. Removing “Null” and Content-type.
    Thanks a lot for the Video and this Comments here.
    Very Good Job!!

  35. Christoph_G says:

    Hello Andri and Alex,

    Concerning the authentication error:

    Do you have the right path? (the string from your Flow-URL in the paths-object?)

    “paths”:{
    “/XXXXXXXXXXXXXXXXXXXXXXXXX/triggers/manual/paths/invoke”
    …..
    }

    Is the first thing that comes to my mind.

  36. Ani says:

    You are just Awesome man!! Just followed your path and got Success!!

Leave a Reply

Your email address will not be published. Required fields are marked *