After creating a custom connector and using it, you can download the relevant files from the Microsoft Flow (or relevant PowerPlatform) website and commit them to a shared Microsoft GitHub repository; ‘PowerPlatformConnectors’. This provides the connector for the community to use! This is a guide through the process for those that are unfamiliar with version control, namely GitHub (such as low-code/no-code individuals), and the file retrieval process.
Where to start
The first thing you’re going to need is a GitHub account.
If you already have a GitHub account you will want to open the PowerPlatformConnectors repository(repo) page and click ‘fork’ (highlighted in yellow below).
What is a fork?
A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project. Most commonly, forks are used to either propose changes to someone else’s project or to use someone else’s project as a starting point for your own idea. (GitHub-Fork-Repo)
Once you’ve done this and agree to the prompt, you will now have a ‘copy’ of the repository on your account for you to freely edit.
Getting Your Repo On To Your PC
If you do not have it already, then you will need to install Git. This will allow you to connect to git hub and download your files/push updates of your files back to GitHub.
The first thing you’re going to want to do is find a directory on your computer than you’re comfortable saving repositories to i.e. make a PowerPlatform folder in Documents. Once you are happy that you have a location open up the command prompt(cmd) and ‘cd’ to that directory by using, as an example(replace the directory/user with your own);
The ‘cd’ is simply ‘change directory’ and you’re telling your command prompt to switch to that folder. We do this so that our next step pulls the files from GitHub into that folder.
Now you want to use another command, this time we will be ‘cloning’(copying) the files from our forked-repository to our local machine to allow us to make changes. Firstly copy the link from your forked-repo to clone (see below):
Once you have copied your fork clone url then you can simply type the command below in your command prompt (replacing REPLACEURL with your url) and press enter.
git clone REPLACEURL
You now have your repository locally on your machine, however, you need to create a custom branch to keep the code separate, to do this enter the code below (Replace with the name of your connector):
git checkout -b <branchname>
The -b will enable you to create a new branch, a branch will simply clone your repo and allow you to make changes without the worry of modifying your stable master code. Now you have a branch you need to set the upstream (where your changes will be passed to) as we want them passed to the branch. Simply enter (with your branch name you just used):
git push --set-upstream origin <branchname>
You are ready to add your own custom connector, so lets get the files.
Getting The Custom Connector Files
You need to have Python 3.5+ installed and can get it from here. Make sure you select ‘add to PATH’ and ‘pip’ options.
Firstly, check to see that Python is working by entering into your command prompt:
If you get an error about python rerun the installer, click ‘modify’ and check the PATH and PIP box.
Otherwise, we need to install paconn (Paconn is command line tool that is designed to aid Microsoft Power Platform custom connectors development) by entering the code below into your command prompt:
pip install paconn
Once the paconn tool is installed, you then need to log in with your Microsoft Login Details by going to the Device Login Page and entering the code provided on your command prompt. This will start the process to link the Microsoft paconn tool to your Microsoft account. To start this enter the code below:
Once you have entered the code and click next you will be asked to select your account. You will then see a ‘Login Successful’ message on your command prompt to show the login is completed (shown below).
Now we’re logged in we can start the download process of our files. Enter the code below:
You then simply select an environment by entering the number (i.e. ) of the environment, once the environment is selected you will be asked to select the connector you wish to download. The files will then be downloaded and ready for you to copy over you your repo.
You now have the Custom Connector files on your local machine.
Adding The Connector Files To Your Forked-Repo
Open the PowerPlatformConnectors\connectors folder and create a folder with the name of your connector. The copy the files that were just downloaded (apiDefinition.swagger.json & apiProperties.json) into that folder. You can then cd into your fork-repo directory, into the folder your just added, and type(for each file):
git add <filename>
Then simply commit the changes by typing & replacing ENTER_A_MESSAGE with your commit message i.e. ‘Added Companies House Connector Files’:
git commit -m ENTER_A_MESSAGE
Once you have committed you then need to ‘push’ those changes up to GitHub by using the git-push command:
You can now open your GitHub repo on the GitHub website, open the branch and you should see your commits.
Merging Your Files In To The Official Microsoft Repository (Pull-Request)
In your branches section of your forked-repo, there will be a pull request button next to your active branch.
What is a pull request?
Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch. (GitHub-Pull-Requests)
Click the Pull Request button (shown below)
Now, ‘normally’ you would be merging to your own repository, but we want to send our changes over to Microsoft’s GitHub. To do this we need to ensure that the base we’re comparing to is Microsofts PowerPlatformConnectors ‘master’ (see below)
Once you’re happy hit ‘Submit’ and that’s it! You just need to await approval (and fix any issues that may be raised) and follow the CLA walk-through to confirm that it is your work on the page.
I’m currently awaiting reviews for my CustomConnector that was previously created and I’ve been asked to change some things, so don’t worry, this is normal!