My Disney Movie : Custom Connectors for Microsoft Flow – Your Service Is My Command

Hello There ! 🙂

I am still not back in my mind from the moments I have spent in Colombo during the SharePoint Saturday event at Microsoft Office and the trip I had in Sigiriya with the speakers was spectacular. Its been great connecting and meeting the passionate community and become part of it. So, the topic I had presented there was about the custom connector of Microsoft Flow and therefore, I have decided to write an article on it now.Before I proceed ahead, I would like to express BIG THANK YOU to friends – Hugh Wood,Perumal and Program Manager – Sunay Vaishnav , Sr Technical Evangelist Srikantan Sankaran from Microsoft  for all their time and assisting me to understand the depth about Azure AD Authentication for Microsoft Flow.

So, objective is what is custom connectors and why should we use that ? How to use that ? And what are the benefits.The whole idea behind this article is to have understanding on integration of custom connector with Microsoft Flow with Authentication setup.Sometimes, I look at issues/scenarios as picture and story, so I feel like Microsoft Flow is our Genie who does what we wish, Custom Connector is our Magic Lamp that magically connects with outside service to use in Microsoft Flow and you are Aladdin who need the automation on workflow tasks with your service, so let’s begin with the movie 🙂 considering you already know what is Microsoft Flow and what are its features. If not, you can go through this article for basic information. Though Microsoft Flow – The Genie, keeps introducing the new services and templates to work with, there is no easy way to connect with desirable service ( Wow, Service can be a princess here 😉 ) which are not available on cloud/associated with Microsoft Flow and that is bit challenging for Aladdin and therefore, Custom Connector – The Magic Lamp helps him to connect with it and makes Business User – Aladdin’s life easy.

So custom connector are nothing but the connection with RESTful APIs which are hosted anywhere but not associated with the Microsoft Cloud for which we require to create a “Swagger Specification” which is a documentation in JSON format to register in Microsoft Flow that tells to Microsoft Flow about RESTful API details such as where its hosted?, what is the authentication type?, which kind of input/out parameters are used? and what are the operations which is served by the API?. Once, we have swagger specification for our web API, then we need to register that with Microsoft Flow via Custom Connector and use them in flow designer to achieve your workflow tasks with your service ( and meet a princess 😛 ).

So, I have directed this movie in following plot points, hope you will enjoy them !

1. Exposition: Creating Web API that returns list of items using Visual Studio and Installing the Swagger Package.
2. Rising Action:Hosting it on Azure and Setting up Azure AD Authentication.
3. Climax: Generating and verifying the swagger file with web API details.
4. Falling Action: Creating Custom Connector in Microsoft Flow.
5. Resolution: Creating a flow using SharePoint On-Premises data, Custom connector and Muhimbi PDF Services.

Have your popcorn ready to enjoy movie ahead, so here is the beginning !

Exposition – In Exposition, I will be introducing how you can create the web API using visual studio, here I am using Visual Studio 2017 and the web API name would be “Magic We Web API” that returns the contact details of magic tools and genie as presented in following video:

 Rising Action:  In this plot, we will host this web API on Azure to let it available on cloud instead of the local server and create two Azure AD Apps required for Azure AD authentication for Custom Connector, so we require to do as follows:

Step 1 : Publish the web API on azure via Visual Studio.

Here, I am using my Azure Subscription and publishing the “MagicWeWebAPI” from Visual Studio that will be hosted on following URL:

• Web API URL : http://magicwewebapi.azurewebsites.net/api/magic
• Swagger Specification: http://magicwewebapi.azurewebsites.net/swagger/docs/v1

 Step 2:   Creating two Azure AD App  as follows:

• MagicWe WebAPI App
• MagicWe Connector WebAPI App

Publishing the App via Visual Studio is easy, however setting up authentication by creating two Azure AD App is bit challenging  comparatively but again not much tricky if you are being careful and noting up all the required information while creating the Azure AD Apps.Infact, you can also authenticate the Web API by creating only one azure AD app, but that’s not the best practice when you are acceeing them via Microsoft Flow. The purpose of creating the first AD App ( MagicWe WebAPI App) is to secure web API.Meaning whenever user is making a call via browser, user is being authenticated via this app.Another AD App called “MagicWe Connector WebAPI App” is basically meant to secure the custom connector created in Microsoft Flow, meaning when user is accessing the Web API through Flow, He/She is being authenticated against the “MagicWe Connector WebAPI App”. This way you can know the difference between an actual user making a request vs request being made on behalf of a user via flow.Furthermore, you can also define and grant a subset of scopes with the 2 AAD app model. For eg: All users calling the Web API via the Custom API can only perform read operations.Also, for your information, the Reply URL is the location to which Azure AD will send the authentication response, including a token if authentication was successful. In the case of Microsoft Flow, the Redirect URI is a unique identifier to which Azure AD will redirect the user-agent in an OAuth 2.0 request.

For the first AD App, use following values and note down the Application ID as indicated in video:

• App Name: MagicWe WebAPI App
• Sign-on URL: https://login.windows.net
• Reply URL: https://magicwewebapi.azurewebsites.net/.auth/login/aad/callback

While for second AD App, use following values and note down the Application ID and Client Secret as indicated in video:

• App Name: MagicWe Connector WebAPI App
• Sign-on URL: https://login.windows.net
• Reply URL: https://msmanaged-na.consent.azure-apim.net/redirect

Here,  in Second AD App, we need to add permissions to have delegated access to MagicWe WebAPI and THAT’S IT !

Step 3: Setup and verify an Authentication for Web API which we have hosted as App Service on Azure via Azure AD App. In this step, we require to add an Azure AD Authentication for MagicWeWebAPI App Service as indicated in following video which require two values:

MagicWe WebAPI App Application ID : 8cbd5931-11a2-4468-a760-8f22ac7135de

In order to generate the right swagger specifications, we need to add the “Security Definition” in swagger file downloaded from above url for this web api as mentioned below as well as in the following video.As soon as you have your swagger specification ready, you can verify the operation in swagger editor before registering it into Microsoft Flow.

"securityDefinitions": {
    "AAD": {
             "type": "oauth2",
             "flow": "accessCode",
             "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
             "tokenUrl": "https://login.microsoftonline.com/1bc57a44-d6da-4bb6-ba00-d7248e1f43da/oauth2/token",
             "scopes": {}
            }
  },

 Note: Make sure that scheme value is “https” in swagger file.Also, operation ID must be unique.Token URL can be recived from classic azure portal > Active Directory > Applications > Add App > Configure > View EndPoint tab.

 Falling Action: And this is the falling action of the movie where we will see how can you create custom connector in Microsoft Flow using swagger file as presented in following video and you will be requiring following values during registration process:

• Client ID and Secret of MagicWe Connector WebAPI App.
• Application ID of MagicWe WebAPI App.
• Setting up auto generated Redirect Url to be set as reply url of MagicWe Connector WebAPI App.
• AD User’s credentials to make a connection.

Note: I would recommended to use Internet Explorer browser while working with Microsoft Flow.

 In nutshell, Whenever user accessing the MagicWe Web API hosted on azure via custom connector (MagicWe Connector WebAPI App) , He gets the access token to access the MagicWe Web API and get succeed to execute the operations of MagicWe Web API.The whole idea is depicated in following illustration:

Resolution: In this plot, We will be looking at how custom Web API being used with SharePoint on-premises data and Muhimbi’s PDF converter service to help Aladdin’s task 🙂 So, here is the flow :

 And, How would you build-run-monitor the flow has been depicted in following video as depicted in above diagram.Basically, I have “My Wishes” document library in SharePoint on-Prem where Aladdin will store his wishes, the moment wish has been added, Flow will be triggered and It will notify to Genie about Aladdin’s wish with Approval option, If Genie approves Aladdin’s wish then document will be converted into PDF and text mark will be added via Muhimbi’s PDF service and notification will be sent to Aladdin that Genie is ready to complete his wish and if rejected, then Genie will notify Aladdin via email about his limitations.For the sake of demo, I am using my own email id to view notifications.

Microsoft Flow Demonstration in Designer:

Microsoft Flow Execution, If Approved:

Microsoft Flow Execution, If Rejected:

Note:  You have to build the flow in default environment since SharePoint On-Prem data can be connected only via default environment.To install the Gateway to access on-premises data, please follow this article.Also, I have added another action that fetches the email ( string ) by ID as follows in controller file of web api.You can find the updated working swagger file here.:

 public IHttpActionResult GetGiene(int id)
        {
            var giene = MagicWe.FirstOrDefault((p) => p.Id == id);
            if (giene == null)
            {
                return NotFound();
            }
            return Ok(giene.Email);
        }

And then, I have added the same action under “Paths” in swagger file as follows:

 "/api/Magic/{id}": {
      "get": {
        "tags": [ "Magic" ],
        "operationId": "Magic_GetGiene",
        "consumes": [],
        "produces": [ "application/json", "text/json", "application/xml", "text/xml" ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "integer",
            "format": "int32"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": { "type": "string" }
          }
        }
      }
    },

And, That’s THE END of movie, I would like to see the review comment if you have and suggestion/questions are most welcome below.

Keep Running, Stay Young 🙂