Custom Connector with MS Flow

Published: May 11, 2020

Microsoft has introduced workflows in SharePoint from SharePoint (MOSS) 2007 and apparently with SharePoint 2013, we have 2 different templates to achieve process-based functionalities: SharePoint 2010 workflow templates and SharePoint 2013 workflow templates. These templates are very useful to develop automated processes like document approval workflows, send notification emails, etc.

Our sharepoint development team is using workflows to achieve these functionalities in On-premise as well as Online versions. But these are very much limited to SharePoint. Over the decade, Microsoft has introduced many services in cloud which were previously available only in On-premise versions i.e. Dynamic 365, MS Access, Office products, etc. With all these services, there was a requirement of one service which can inter-connect all these services, communicate and transfers data easily between these services and Microsoft Flow is introduced.

Table of Content

  1. What is Microsoft Flow?
  2. Connectors
  3. Life-cycle of Custom Connectors
  4. Create a Custom Connector to access GitHub Repositories
  5. Conclusion

What is Microsoft Flow?

Microsoft Flow is very easy to integrate, reliable and durable. As the tagline suggests “Work less, do more”, you can easily integrate it without any coding language knowledge. Microsoft has provided easier UI to create Flows that one can learn to create it very quickly. Also documents and training modules are available here to learn it quickly. MS Flows are a better replacement of the SharePoint Designer Workflows in SharePoint Online because it’s faster, much easier to develop and maintain compare to Designer workflows. Hundreds of templates and many connectors are provided for users to create Microsoft Flows.

With Microsoft Flow, you can perform the recursive tasks which don’t require manual monitoring. Refer this link to have more idea. Microsoft has introduced AI services (called as Cognitive Services) and integrated them in MS Flow to make it more powerful tool. Go through this link to know about MS Flow with Cognitive services

Microsoft has introduced several pricing models for MS Flows. You can check them here.

Connectors

A wrapper around an API which permits the underlying service to converse with the Microsoft Flow, PowerApps and Logic Apps is called as a Connector. It provides a way for different applications which contains Triggers and Actions to create Flows.

Components of Connectors

The set of operations is provisioned by each connector and it is in form of Actions and Triggers.

Actions:

  • This component is used to perform actions added by users in the process i.e.: Create a new item in list, update an item in list, send an email, get document from document library, etc.
  • The operations are defined inside the Swagger and all actions are mapped to these operations.

Triggers:

  • This component is used to get notification when specific event occur in the application i.e.: When item is created or updated in list, when document is updated in library, when new email is received, etc.
  • With the use of MS Flow or Logic App which listens to a trigger, you can perform an action whenever the trigger is fired.
  • Two types of triggers are there to perform an action based on various scenarios:
  • Polling Triggers: To check for the new data at a specified frequency, you can consume this trigger by calling your service. This trigger initiates a new run of the workflow instance with the data as input when a new data is available.
  • Push Triggers: These triggers listen for data on an endpoint i.e. they wait for an event to occur. This event’s occurrence initiates a new run of your workflow instance.

Note: In PowerApps, the triggers are not supported.

However, Microsoft has a vast range of connectors which are divided under 3 categories for different applications:

  • Standard Connectors
  • Premium Connectors
  • Custom Connectors

Azure Logic Apps, MS Flows and PowerApps provides 180+ connectors in Standard and Premium Connectors categories to connect Microsoft and non-Microsoft services. The communication can be established with the services which are not available in the prebuilt connections by developing a Custom Connector. Here, we consume a custom connector from scratch so let’s dive into it.

Lifecycle of Custom Connectors

Build your API

PowerApps, MS Flows and Logic Apps can communicate with the REST API or SOAP API with the assistance of a custom connector which is a wrapper around that REST API.

These APIs can be:

  • Public (available on public internet):
  • Private (available on your private network):

For public APIs, you can use Azure functions, Azure Web Apps and Azure API apps from Microsoft Azure or you can use dedicated hosting to host your APIs.

Secure your API

Below are the standard authentication methods for the APIs and connectors:

  • OAuth 2.0
  • API Key
  • Basic Authentication

For your API in the Azure Portal, you do not require to implement the authentication externally if you set up Azure AD authentication. To have more knowledge visit here.

Describe your API and define the connector

Once you have your API ready with authentication, you will have to describe your API so MS Flow, Logic Apps and PowerApps can communicate with your API through various below supportable approaches:

You can use OpenAPI definitions and Postman collection to create machine readable documents that describes your API, yet both use different formats. With the use of various tools, you can generate these documents for your API but MS Flows, Logic Apps and PowerApps use OpenAPI to define connectors basically.

Use your connector

There is no difference in the usage of the Microsoft managed connectors and Custom Connectors. Connectors created in MS Flows will be available in PowerApps and vice versa but it will not be true for Logic Apps. You will have to recreate connectors using existing OpenAPI definitions or Postman collection in Logic Apps.

Go through below links to know more about the usage of a custom connector:

Sr. No. Usage Medium Reference Link
1 Microsoft Flow https://docs.microsoft.com/en-us/connectors/custom-connectors/use-custom-connector-flow
2 PowerApps https://docs.microsoft.com/en-us/connectors/custom-connectors/use-custom-connector-powerapps
3 Azure Logic Apps https://docs.microsoft.com/en-us/connectors/custom-connectors/use-custom-connector-logic-apps

Share your connector

You can share your custom connector with other members of your tenant in the same way you share resources in MS Flows, Logic Apps, and PowerApps. Sharing connectors in optional.

You will get more data from here.

Certify your connector

You can submit your connector in Microsoft for certification, if you want your connector publicly available in other tenants in cloud. After reviewing it, Microsoft will approve it if it meets the expectation criteria. Certifying connector is optional, else you can also share OpenAPI definitions or Postman collection files with other tenants’ members to add them in their tenants.

You will learn about more data/information from here.

Let’s create one Custom Connector with GitHub API to understand it in depth.

Create a Custom Connector to access GitHub Repositories

You can access the GitHub Repositories through a custom connector. We will create two actions in our custom connector which provide the below two details from GitHub Repositories via Rest APIs end-points:

  1. Get all repositories for user
  2. Get issues from selected repository

Later, this custom connector is consumed in the MS Flow in which we have demonstrated one action called ‘Get issues from selected repository’.

Getting Started

When you start building a connector, you have five options available for creating a custom connector.

Here, we will use Postman collections to develop Custom Connectors and GitHub API with Basic Authentication.

Prepare GitHub APIs in Postman

  • Install Postman setup to your machine and open it.
  • Create a new collection in it. Here, we are creating it with name “GitHub API”.
  • Add description for this API collection, if required.

  • Click on “Authorization” to add authentication details. Select “Basic Auth” option from Type dropdown control and pass your GitHub user credentials.

  • Click on “Create” button to save the details.
  • Here, we will create 2 REST API requests as below:
    1. Get all repositories for user
      • Create new request using https://api.github.com/user/repos URL and select GET request.
      • Select “Inherit auth from parent” option in Authorization or you can pass GitHub user credentials as provided before.
      • Click on “Send” button to see the results.
    2. Get open issues from repository

  •  Click on “Send” button to see the results.
  • Once both APIs are working properly, export collection from Postman.
  • Click on ellipsis in left navigation under your collection click on “Export” option.

  • Select “Collection v1 (deprecated)” option to export the collection.

Note: MS Flows custom connector creation only supports collection v1 file.

Create custom connector in MS Flows

  • Open https://flow.microsoft.com with proper credentials.
  • From left navigation menu, click on “Custom connectors” under “Data”.

  • Click on “New custom connector” and select “Import a Postman collection”.

  • Pass proper connector name and V1 file (previously saved from Postman collection) click on “continue” button.

  • Once collection will be imported, you will have 4 stages to create and publish the connectors.
    1. General
    2. Security
    3. Definition
    4. Test

General

  • In General section, it will allow us to set icon for connector and background colour in hash value.
  • Set proper Description as per the connector.
  • Select “https” in Scheme pass “api.github.com” in Host pass “/” in Base URL.

  • Click “Security” at bottom to go to next stage.

Security

  • It will directly take Basic Authentication from Postman collection file, but you can set it from here if not taken.
  • Create parameters for username and password.

  • Click “Definition” at bottom to go to next stage.

Definition

Note: There is one interesting functionality provided by Microsoft that one can create action in custom connectors to be used for internal purpose. This action will not be available in MS Flows to add in Flows, but it can be used in another action in same custom connector definition. Let’s see this in detail.

  • In this section, you can add triggers and action for your custom connectors. Here, two actions are added.
    1. Get all repositories for user
    2. Get issues from repository
  • Click on “New action” to add new action.
  • In general section, provide “Summary”, “Description” and “Operation ID”.
  • Select “Internal” option for “Visibility” to use this action internally in other actions.

  • You can see there will be few parameters in Request tab. You can set values for these parameters by populating dynamically and statically or take input from user in actions.

  • Click on ellipsis beside “owner” to edit it.
  • Set default value of owner and required/non-required parameter as shown below:

  • Click on “Back” to go to earlier page.
  • Click on “repo” to edit it for setting its default value as per the need.
  • Repository values can be populated dynamically so let’s populate these values dynamically here.
  • Set “Type” to “String” and choose dynamic in “Dropdown type”.
  • Below there will be “Operation ID” dropdown control. It will have all the actions we have created in this connector.
  • Select “UserRepos” in that dropdown control.
  • Select parameter “name” in “Value” and “Value display name” dropdown controls.

  • Click on “Back” to save the details.
  • Click on ellipsis beside “state” to edit it for setting its default value.
  • States can be “open” and “close”. Let’s set dropdown control for this with static values.
  • Select “Static” in “Dropdown type” and pass values with comma separated and covered with double quotes as shown below:

  • Click on “Back” to save the details.
  • Click on “Test” to go to next stage.

Test

  • You can test your connectors before making them available for users to use in MS Flows in your tenant.
  • Click on “New connection”.

  • It will redirect to new page where you will have to pass credential details for GitHub authentication.

  • Pass credentials and click on “Create connection” for testing. This connection details will be populated in “Selected Connection” dropdown control as shown below:

  • You can select action from left side and pass required parameters, and click on “Test operation” to test the actions.

  • Check the output details as shown below:

  • Once you are satisfied with the output, save the connector by clicking on “Update connector”.

Use action in MS Flows

  • Login to https://flow.microsoft.com with proper credentials.
  • Go to “My flows” to create a new flow with “Instant – from blank” option.
  • Here, for illustration, “Manually trigger a flow” trigger is selected.

  • Click on “New step” button to choose an action.
  • In that card, click on “Custom” tab to view all custom connectors added in your tenant.

  • Select “Custom Github API” connector to see all actions and triggers under it.

  • You will find “Get Issues from selected repository” action inside it.

  • Click on that action to add it in your flow.
  • Action will be added in flow with default values in parameters.

  • You can add your GitHub authentication in this action.
  • Click on ellipsis provided on action click on “Add new connection” to add your credentials.

  • Add “Compose” action below this action to see its output.

  • Save this flow and Run it to see output.

Conclusion

Through this blog, you get the basic idea about the custom connector and its consumption in MS Flows, Logic Apps and PowerApps. Custom connectors are very powerful and helpful for the people who don’t like to write code. It is a simple process of building a custom connector when the correct end-points are known.

You can also create a reusable custom connector to carry out the development process in effective and efficient manners. A custom connector can be reused by downloading it from the custom connectors listing and the downloaded custom connector is an OpenAPI file. This JSON file can be used to create a new connector which includes more actions but the point to remember is that you have to manually provide the Client ID and Client Secret for OAuth 2.0 authentication.

As we realize that MS Flow is fit for handling complex tasks and also allows to create complex integrations between different platforms i.e. either On-premise or Online. Thus, create your complex custom connector and give it try with the MS Flow.

Comments

  • Leave a message...

Related Articles

SPFx Extensions – ListView Command Set

Jul 24, 2020

PowerApps + Microsoft Bots = PowerBot

Jul 9, 2020

Actuate Bot Features within SharePoint Framework

Jun 23, 2020