SOLUTIONS FOR POWER PLATFORM
Building a Power Platform Independent Publisher Connector for the Ethereum Blockchain (Part 1)
This article is the first of a three-part series on building and submitting a custom connector through the official certification process.
TL;DR — Part 1 explains what makes a custom connector and what it takes to talk to the Ethereum Blockchain. Also, we get a quick introduction to the Ethereum Blockchain ecosystem and Infura. Primarily, we learn how to tackle the challenges of JSON-RPC in a RESTful API world.
What are custom connectors?
Before we look at my Infura Ethereum connector and the concrete certification process, we do a short recap on what a custom connector is. For this, it’s best to let the official documentation speak:
“While Azure Logic Apps, Microsoft Power Automate, and Microsoft Power Apps offer over 325+ connectors to connect to Microsoft and non-Microsoft services, you may want to communicate with services that aren’t available as prebuilt connectors. Custom connectors address this scenario by allowing you to create (and even share) a connector with its own triggers and actions.”
Custom connectors overview | Microsoft Docs
Now that we recalled what a custom connector is, I will briefly introduce you to the Ethereum Blockchain and what’s required to communicate with it. Also, we look at the challenges I’ve faced during the implementation of the custom connector and how I solved it.
Ethereum Blockchain
Ethereum is an open-source, blockchain-based distributed ledger. It is powered by software running on a network of computers (or nodes). Those nodes ensure that data and smart contracts are replicated and run on all computers on the network without a central intermediary.
Ethereum can be used for:
- Sending and receiving cryptocurrencies and stablecoins
- Experience decentralized finance such as lending and borrowing
- Trade non-fungible tokens, known as NFTs
- Participate in online communities and decentralized autonomous organizations (DAOs)
Essentially, every node talks to many other nodes. The API used in such a peer-to-peer distributed ledger world is different from what we Microsoft folks usually expect. It’s not a RESTful API, which complicates matters a bit.
JSON-RPC
To communicate with the Ethereum Blockchain and its nodes, JSON-RPC is used. JSON-RPC is a stateless, lightweight protocol. Furthermore, it is transport agnostic in that the concepts can be used over sockets, over HTTP, or other ways.
While it is designed to be simple, it’s not necessarily as intuitive as RESTful APIs and heavily relies on documentation. As you may guess, that’s not a perfect fit for a low-code platform with its generic connector approach.
Infura
Talking to a peer-to-peer network is not very practical if you want to build apps on top of the Ethereum blockchain. For that, some cloud providers expose the JSON-RPC endpoint of the network as a single public API on the web so that app developers can consume the network as a service.
One of those services is Infura. The Infura API provides instant access over HTTPS to the Ethereum network and therefore is a good entry point for traditional applications trying to communicate with the Ethereum blockchain.
I’ve used the Infura Ethereum API to build the first version of my connector for the Ethereum Blockchain.
The Challenge: Using JSON-RPC in the Power Platform
Due to the nature of JSON-RPC, there are some challenges I had to tackle because the Power Platform depends on RESTful OpenAPI based services. Since most of the platform UX relies on that fact, I needed to solve three unique challenges.
- JSON-RPC has only one endpoint and no path templates. While we still need dedicated actions in the platform for a good UX, we need to route every call to the same URL.
- The method to invoke is identified through a POST body and follows documentation instead of a standardized approach. JSON-RPC parameters can be named or positional, and there is no exact pattern, so you need to decide on a per-method basis.
- Everything in the Ethereum world is expressed as byte strings or hex-strings. This is unusable for the average user. So, the connector logic should convert from byte string to string or decimal values.
Solving the challenges
Model as a RESTful API
Since the Power Platform UX is very much dependent on RESTful APIs or OpenAPI based services, we need to model every target service as if it is based on those specifications, even if it isn’t as with the Infura JSON-RPC endpoint.
Infura supports most of the Ethereum JSON-RPC specifications. The OPEN-RPC Playground allows you to explore all the methods and their parameters.
For my connector, I did choose the following three simple methods:
/eth_blockNumber| Returns the number of the most recent block./eth_getBalance| Returns the account balance of the given address./eth_gasPrice| Returns the current price per gas in wei.
The trick is to model the OpenAPI definition of my connector just as it were a RESTful API and as it follows the path template approach. Then, as explained in the following section, together with Template Policies and Custom Code, we can translate between the two worlds while providing the best possible UX for the user.
Routing Template Policy
Since the JSON-RPC API of Infura uses a single endpoint without any path templates, we need to route every incoming request to that single endpoint. For this and other cases, the platform provides Template Policies. When creating such a policy, you can use the Route request template, which routes all requests to the specified endpoint on the same service.
In my case, the specified endpoint is dynamically constructed in the New path field. The expression /@connectionParameters('infuraProjectId’) simply appends the Infura Project Id to the base URL and routes everything to that endpoint.
The Infura Project Id is defined as a UI parameter in the apiProperties.json. When you create a new connection to the connector, it is required as an input parameter. UI parameters can only be configured using the paconn-cli tooling as explained in Part 2 of this series.
Transformation with Custom Code
To tackle the remaining two challenges, we need the help of Custom Code. Custome code is a preview feature that allows us to use C# code to transform requests and responses from and to the connector. With custom code, you can achieve virtually everything, but it also increases the complexity of a connector.
However, keep in mind that you’re building for a low-code platform where a simple and good UX for the user is the key to success. Always model your connector with the user in mind. To keep the complexity low and allow for maintenance, I’ve tried to keep my custom code in the script.csx code as simple and clean as possible.
Let’s look at two snippets of the custom code specifically. The first snippet solves challenge number two, as it transfers the incoming request based on the operation invoked. With the IsOperationId pattern your code stays readable and allows for future maintenance and extensibility.
The second snippet transforms the response message before passing it back to the user. With this approach, we can check if the result contains hex-formated binary strings (identified by a regex pattern), and then we try to convert it to a normal string or a decimal value. This is necessary because we can’t expect a typical user to work with hex-formated binary strings, and it would be very impractical to work with such strings in a Power Automate Flow or a Power App.
With the help of custom code, we solved two out of three challenges. We could have solved all three challenges with custom code, but I decided to use as much native support as possible (or as little custom code as possible) and stick with the transform template to solve the first challenge.
Summary
After playing around with the connector and its design, here are my top learnings:
- Model any API as if it were RESTful, even if it isn’t RESTful.
- Use Custom Code and Transform Policies to translate between the different worlds.
- When in doubt, UX comes over Connector complexity. Don’t worry if your custom code gets more complex until the UX for the user stays great or improves. Remember, you’re building for a low-code platform.
- The Power Platform can talk to any API; this includes legacy or future systems, such as Ethereum Blockchain.
Disclaimer: There’s currently a bug with the connector deployment pipeline in the certification process, blocking some of the connectors from working. Microsoft solved the issue and is presently redeploying everything.
In the second part of my article, I will explain what it takes to submit your custom connector as an independent publisher connector to the official Microsoft Connector repository so that the connector shows up as a premium connector inside the various Power Platform products.
Make it so 👉
— Sebastian
