There are so many connectors provided (It's over 900 now), with new ones coming on line almost daily. But I have a cautionary word:
You may think these are all created by software providers, yet anyone can create connectors (in fact I hear from Microsoft a lone developer had delivered 20% of them).
Secondly for some business these are very small volumes, meaning there is no motivation in updating and maintaining them.
Therefore using these out of the box connectors isn't always the right solution, especially if the API its built on has good documentation.
The example that made me feel this way was Service Now. I wanted to use the out of the box Connector Provided by Service Now, the first thing I noticed was the icons logo, it's the old one. And I don't mean just old, I mean very old.
Connector
Website Icon
Now I know an icon doesn't impact the connector, but if they haven't update it it makes me think that it's not been updated in a long time or they don't care about it.
Second thing I noticed was the list of APIs in the connector, pretty much just the Table API.
Now the Table API is by far the most powerful and useful API, but it is far from the only one. Example there is no way to use Attachment or Email APIs.
The final thing I found, and this was the deal break, was how unuser friendly it was. In trying to be helpful the connector pulled the schema and showed all of the fields. But in some tables there are over 200 fields, far too many to navigate through in a long list.
Yes it really is that long.
So I decided to make my own Service Now connector, which would have all the APIs I need, and be a lot more user friendly (and use the latest icon 😋).
Before I started I wanted to create some design principles for all my custom connectors. My Approach was simple, start with CRUD and keep them very flexible - in other words have one body input, that way I can create my own object.
Once established I can extend the base connectors with specific use cases, these would have set inputs.
An example would be a correspondence email table, in Service Now this is based on a standard table, so the Table API would be used, but as its a specific use case I will set the parameters:
to, subject, body, important, parent case
This approach ensures that all requirements can be covered, and then over time introduce simpler parameters to make high use actions more user friendly.
Creating a custom connector is a lot easier than it sounds, you have 2 very easy ways to create the connector:
- Import OpenAPI file (Swagger)
- Create From Blank (there are more, including Import a Postman Collection, but I always seem to have issues when I tried it, the first 2 always work)
Using OpenAPI (Swagger) is by far the best and simplest way. Extract the API from its swagger page, Import OpenAPI file, add icon, descriptions and authentication and you are done. What's great about swagger files is references (reusable parameters) and response schemas (allow different schemas for successful and failed responses) are easily added.
Creating From Blank is more like a wizard then actually from blank. Setting up API's is often as simple as entering an example query and response, from this the custom connector creates the actions for you.
I won't go into exact detail on how to create a custom connector, there are already load of great guides, including from one MS learn, (see links at the bottom of the page). Though one top tip is to leverage the swagger view of the connector, this allows for quick edits of the connector.
So after a small amount of work I was able to create my own Service Now connector, fully functional to all my requirements, easier to use, and better looking 😊.
As you can see there are many benefits to going custom and I would recommend it, but there are a couple of caveats:
- You own the life cycle, so any updates to the api you have to do (this can also be a benefit if the conenctor owner is slow to do updates)
- The connector has to be added to all environments it is used in (not too challenging, but another admin task, including pushing out updates for the connector to all environments)
Further Reading
- https://learn.microsoft.com/en-us/connectors/custom-connectors/
- https://learn.microsoft.com/en-us/connectors/custom-connectors/define-blank
- https://learn.microsoft.com/en-us/connectors/custom-connectors/define-openapi-definition
- https://learn.microsoft.com/en-us/connectors/custom-connectors/openapi-extensions
Top comments (0)