I’ve been moving content from my old KB in Github to its new (and hopefully permanent) home at

https://codemastershawn.com/kb

and I took the opportunity to update the Set up a new Windows PC entry. It documents how I configure a new PC with my chosen productivity tools.

Objective

To create, deploy and use a custom Connector that can be used in Azure Logic Apps. We also want to be able to publish this connector in the gallery (so that it shows up in the list with other connectors). For now the latter appears to be primarily available as invite-only for Microsoft partners.

Disclaimer

During my research it became clear that Azure and the Microsoft Flow services are constantly changing, both in terms of functionality and user interface. What follows are based on my experience at the time of this writing. By the time you read this there have likely been additional changes.

What you need to know first

1. Custom connectors are just ASP.NET Web API applications.
2. An action (the functionality provided by a connector) in Microsoft Flow and Logic Apps relates directly to an operation in your Web API – The connector/action executes the configured operation from your Web API.
3. While it’s technically not required, you’re going to want your Web API to be described using Swagger (aka OpenAPI Specification). Microsoft uses an extended Swagger spec to provide additional information and functionality to the connector.
4. Logic Apps will timeout an HTTP request after 1 minute (the documentation for Flow says 90 seconds). If the call to your Web API might take longer you will need to implement the async pattern.

Microsoft Flow / Azure Logic Apps

Logic Apps are an outgrowth of BizTalk and various workflow platforms from Microsoft. They are a way to build workflows that can integrate with a variety of external services. Think IFTTT with the ability to provide more logic, or Yahoo! Pipes.

Flow is kind of a “lite” version of Logic Apps. Flows use the same connectors as Logic Apps, but expose less of their functionality and have fewer options for linking connectors. Microsoft Flow is a direct competitor to IFTTT.

Workflows in both consist of actions. These actions come in two flavors:

• Triggers – Every workflow must start with a trigger action. Triggers are executed in response to some event. There are two types of triggers:
  • Polling triggers periodically check status (e.g. by calling a Web API) and only take action when the status conditions are met.
  • Push triggers, sometimes called webhooks, provide a special endpoint for the Logic App. When that endpoint is called from an external process with the appropriate values the workflow starts.
• “Normal” actions – This encompasses all non-trigger actions. These respond to the previous action and may pass their data on to the next action.

There are already several good tutorials on-line that cover the basics of creating Flows and Logic Apps, so I’m not going to go into that here. These are a few that I recommend:

• Getting started with Microsoft Flow
• Azure Logic Apps – Post to Twitter
• Create a new logic app connecting SaaS services
• How to Automate Business Processes Using Azure Logic Apps
• Design, build, and deploy Azure Logic Apps in Visual Studio

Because Microsoft Flow and Logic Apps both allow the user to select the same connector/actions from the gallery, we will start by adding our Custom API to Flow. Once there it can be rolled out for Logic Apps.

The built-in HTTP connectors

If you don’t need your custom API to be in the gallery where other users can select it to include in their own Flows the easiest way to access it is with one of the built-in connectors:

• HTTP is for Web APIs that don’t have a Swagger description. The user will need to provide the HTTP method (e.g. POST), URL, headers, body and authentication information when added to the Flow.
• HTTP + Swagger requires a Swagger endpoint URL for your API. The user will then be asked to select an operation provided by the service. There are a variety of libraries that can dynamically add Swagger to your API.
• HTTP Webhook allows push notifications into the Flow. The user will need to provide the same information as for HTTP above – for both subscribe and unsubscribe endpoints. Configuring a webhook is beyond the scope of this article. See Using webhooks with Microsoft Flow.

Custom APIs

What we’re looking to do, however, is provide our own branded connector that customers can choose from the gallery instead of one of the built-in HTTP connectors. In Microsoft Flow, this is referred to as a Custom API. In Logic Apps this is referred to as a connector.

To register a Custom API for use in your flows click the gear icon in the top right and select Custom APIs.

On the next page click the Create custom API button:

1. Upload the Swagger file that describes your API. (As of this writing the process will only accept an uploaded file. It will not accept a URL.)
2. Upload an icon that represents your service. While the icon is required, it is already pre-populated with a generic image.
3. Provide a description if you like.
4. The Host and Base URL should be filled in from the contents of the Swagger file.
5. Click Continue.
6. Select the authentication method required by our API. You may be prompted for additional information.
7. Click the Definition tab. This page shows the operations, parameters, entities, etc. that Flow found in your Swagger file. You may fine-tune names, descriptions, etc. here.

When done click Create API in the top right. If successful, your API should be listed on the Custom API page. From here you can create Connections, edit or remove the API.

T-Rex = Swagger + MS extensions

You may have noticed near the end of the steps in the previous section that a lot of cleanup was needed on the Definition screen. Maybe you needed to provide friendlier names, descriptions or set visibility.

Microsoft has provided the following extensions to the Swagger specification which covers some of these situations:

• x-ms-summary provides a display name.
• x-ms-visibility allows an element to be hidden from the UI or behind an “advanced” dialog.
• x-ms-trigger denotes a trigger as well as what type.
• x-ms-dynamic-values indicates that the values come from some other process (e.g. the result of another operation).
• x-ms-dynamic-schema indicates that the format of the values is dynamic.

For more details see Customize your Swagger definition for Microsoft Flow.

Maintaining these extensions in your API’s Swagger by hand could become a real headache, so a Microsoft MVP by the name of Nick Hauenstein has created a library for that. T-Rex extends the Swashbuckle library, which generates Swagger for ASP.NET WebAPI applications, with additional attributes to generate the Microsoft extensions listed above.

Here is an example from the T-Rex documentation:

[Trigger(TriggerType.Poll, typeof(SamplePollingResult))]
[Metadata("Roll the Dice", "Roll the dice to see if we should trigger this time")]
[SwaggerResponse(HttpStatusCode.BadRequest, "Bad configuration. Dice require 1 or more sides")]
[HttpGet, Route("diceRoll")]
public HttpResponseMessage DiceRoll(string triggerState,
                                    [Metadata("Number of Sides", "Number of sides that should be on the die that is rolled")]
                                    int numberOfSides,
                                    [Metadata("Target Number", "Trigger will fire if dice roll is above this number")]
                                    int targetNumber)

NOTE: At the time of this writing the stable release of T-Rex only includes support for the summary, visibility and trigger extensions.

Creating a connection

After the Custom API has been registered you will need to create a connection to it before it can be used in a Flow.

From the Custom API page, click the plus (+) icon for the API you want to connect to. Enter the connection information when prompted then click the Create Connection button.

That’s it! You can now select your Custom API from the list of actions in a Flow.

Getting into the public gallery

Following the previous steps, your Custom API will only be available to you, your team and others you share it with – using the same connection (including credentials) you created. It will not be available to all Flow users. Nor will it be available to Logic Apps.

To get your Custom API into the public gallery, where it can be used by anybody, you will need to contact Microsoft. They will review and test the Custom API and, if approved, make the necessary changes to require each user to set up their own connection. Only then will they make it available to all users.

Once your Custom API is in the Flow gallery Microsoft will incrementally roll it out across data centers for use in Azure Logic Apps.

Additional references

• Using Web APIs as a Custom API in Microsoft Flow
• Integrating a Custom API with Flow
• Create a new logic app connecting SaaS services
• Get started with API Apps, ASP.NET, and Swagger in Azure App Service
• Deploy your first web app to Azure in five minutes
• Deploy an ASP.NET web app to Azure App Service, using Visual Studio
• Call custom APIs hosted on Azure App Service with Azure Logic Apps
• Diagnosing logic app failures
• Microsoft videos
• Build holistic integration solutions using Azure Logic Apps and API Management from Connect(); // 2016
• Integrate all of the things! from AzureCon 2015
• Integrating your Systems with Logic Apps from Build 2016
• Online forums for Microsoft Flow

If you have experience dynamically generating entity models for OData I could use a bit of help with getting the finer bits of manually defining Navigation Properties. If not, do you know somebody who’s an Edm Goddess?

For more details see my forum post in the ADO.NET, Entity Framework, LINQ to SQL, NHibernate forum:

https://forums.asp.net/p/2085521/6022522.aspx?p=True&t=635912368648167847

I’m really close – just need some others who are also familiar with these libraries to brainstorm with.

Thanks

So, I’ve been working for K2 for about a year-and-a-half now and am still enjoying being part of an actual software company again. Today I found out they’ve produced a new How To video for the product I’ve been the primary developer on for the last year or so.

This component is a broker that connects to a RESTful web service and exposes its entities and methods as K2 SmartObjects – which can be used in workflows, reports and other K2 blackpearl or Appit processes.

The area outlined by the blue box below is the functionality I am responsible for:

Topics: Telecommuting tips, Heartbleed tools, the end of crapware?, Git tutorials, free education, ideas into products, humanize numbers, better Datetimes, a Git GUI.

• The Pluralsight blog has some good tips for those working from home.
• If you’ve been under a rock and haven’t heard, make sure you’ve updated OpenSSL on all your computers.
  • If you’re a LastPass user, they now have a report that will tell you which of the sites you have accounts on have patched the bug.
  • GRC (host of the Security Now podcast) has an online tool that will tell you if your browser is properly recognizing revoked SSL certificates.
• SweetLabs is working with PC vendors to replace OEM-installed crapware with a recommendation-based app store solution, letting developers sell their apps directly.
• The fledgeling OneGet community has apparently pushed to get the repository moved to Github. (via @fearthecowboy)
• Discovered that Atlassian has a nice set of Git tutorials and resources online.
• The Free Technology Academy offers free education in “Free Software, Standards and Hardware“.
• Local developer @EliThompson passed along an interesting new guide coming out soon: How to Transform Ideas into Software Products from Femgineer. Sign up to be notified when the guide is published and you can participate in a free e-mail course to get feedback on your idea.

Tools, etc.

• Wow. Humanizer is a .NET library that provides a mind-boggling array of ways to convert “strings, enums, dates, times, timespans, numbers and quantities” into more human-friendly text. (via Scott Hanselman)
• Scott also recommends Noda Time as a better library than what’s provided with the .NET Framework.
• Looking for a GUI for Git and/or Mercurial? Source Tree is a free download from Atlassian.

Projects, etc.

• Working on something, which I hope to announce the next day or two. Stay tuned….

The Weekly roundup is my regular post of interesting and useful things I’ve found or done over the last week.

Topics: Computer yoga, OneNote API, BitCoin explained, WordPress for PhpStorm, hosting service for .NET, personal data protocols, git prompt.

• A short How to do computer yoga while sitting at your desk.
• Unlike many Microsoft products, I actually like OneNote. Now there’s an API, and I absolutely love APIs.
• Scott Hanselman’s interview with Steve Beauregard provided the best description of BitCoin and the tech around it that I’ve heard so far.

Tools, etc.

• Looks like the next version of the PhpStorm IDE (currently in Early Access) has some pretty nice support for developing and debugging WordPress plugins.
• Considering AppHarbor as a simple, basic cloud-hosting service for .NET applications.
• Reviewing some of the word needed on Diaspora* led me to Tent – “a protocol for personal data and communications.“
• Want a better prompt for git on Linux? There’s a Github repository for that.

Topics: Unit testing PHP, test images for color-blindness, hands-on learning, RSS on Github, myths of software development.

• The Open Data Protocol (OData) 4.0 has been approved, along with the OData JSON Format 4.0. If you’re not familiar with OData, it’s a standard for reading and writing to data sources with RESTful web services.
• Need to explain computing concepts to somebody? Computer Science Unplugged has some pretty nifty activities that do just that.
• I remember hearing about Flattr years ago – one of the early services for giving back to open source developers – but I had no idea they were still around. And doing reasonably well.
• Migrations in Entity Framework are a topic I could be stronger on. The ADO.NET Blog has some screencasts that just might do the trick.
• Friend Dan passed along another comic I need to add to my list of regulars: CommitStrip.
• Dan also shared some thoughts on a thought-provoking article from Model View Culture about the myth of the software developer. I hope to share my own thoughts on it later this week.
• OSS Perks is a listing of tools and services (including commercial ones) that are available for free to qualifying open source projects.

Tools, etc.

• Colblinder has a handy Color Blindness Simulator for your images. Upload an image then select different types of vision to see what it looks like. (via @DanielSolis)
• Portable.Text.Encoding is a portable (i.e. cross-platform) implementation of .NET’s Text.Encoding namespace. (via @migueldeicaza)
• Did you know Github repositories can have releases? You can find them using the following URL path:
  • https://github.com/<account>/<repository>/releases
  • To get an RSS feed, just add .atom to the end of the above URL.

Projects, coding, etc.

• Been studying up on WordPress plugins. There’s lots of documentation and tutorials out there, but I found that HardcoreWP has a very nice overview.
• Published a new KB article on Configuring PHPUnit for PhpStorm after introducing unit testing to a WordPress plugin project at work.

Topics: Incentivizing software issues, free images for your blog, testing Javascript, automating browser tests.

• I think Donay has a really compelling idea, but I ran into a lot of problems with their site just trying to get an account set up. Maybe if more people express an interest in being able to ask for and provide incentives for project features/issues… I hope they can get some momentum going and turn it into something workable. Spread the word!
• Bountysource is another service that lets people set bounties on existing Github issues they’d like completed. Visit my profile.
• GettyImages strikes a good balance between copyright, intellectual property and fair use: Embed images for free in a non-commercial context.
• I’m always looking for ways to increase productivity by automating processes. This week’s NuGet Package of the Week from Scott Hanselman shows how to use FluentAutomation (I love “fluent” syntax!) with Selenium and scriptcs to automate browser testing.

Tools

• There’ve been a lot of windowing enhancement add-ons over the years; the new Preme for Windows looks pretty feature rich, with some useful hotkeys.

Coding, projects, etc.

• Been studying up on the current state of unit testing with Javascript, including Jasmine and QUnit.
  A few good tutorials:
  • Testing your Javascript with Jasmine on Tuts+.
  • Unit test Javascript applications with Jasmine on Adobe’s Developer Connection.

If you’d like to support this blog and the work I do in general, I now have an Amazon Wishlist with hardware, software, etc. that I need. More options and information are coming soon.

NOTE: I’m moving the posting day/time for the weekly roundup to Monday morning. Hopefully that will make it a little more visible as well as giving me the weekend to wrap up the content.

• The current stable version of Entity Framework (EF6) now supports mocking the database context – which is allowing me to update the CtcApi so that unit tests do not require the database.
  • Oh, and if you’re working with the Entity Framework you should be using LINQPad. Even if you don’t use EF, it’s still a great minimalist C# editor/compiler – test out snippets of code outside of the complexity of your project.
• Code for Seattle – “Developers, designers, data geeks, leaders, artists, and idea-makers who help Seattle government and civic organizations adopt open web technologies.” (via Seattle Transit Blog)
• Did you know you can use your Android smartphone to contribute to distributed research projects now? (via GeekWire article)
• Microsoft has a new online source code browser (beta) for the parts of the .NET Framework that have been open sourced.
• Read an old, but interesting interview with the CEO of a very successful, commercial WordPress forms management plugin on how licensing under the GPL has been beneficial for them.
• Game Developerz sounds like a fun new card game – comes recommended by a former boss, co-founder of Humongous Entertainment. Its Kickstarter has a little over a month to go.
• On the job-hunting front, GET /api-jobs looks like a useful stream of API-related job postings from a variety of sources.
• If you’re a C# developer interested in learning – or even just curious about – Python, I highly recommend the JetBrainsTV video Python for the C# developer.

Tools

• Friend of a friend, Robert shared MTR – a better traceroute for *nix. I also found WinMTR; unfortunately there’s not a Chocolatey package available.
• I’m not quite as late to this party as Eli is, but certainly late enough to have missed Scott Hanselman’s post about SlowCheetah. Previews for my Visual Studio configuration transforms? Yes please! (Scott’s most recent blog post is also very much worth reading and sharing.)
• I’ve recently needed to start watching my blood glucose levels. Today I discovered Nutritionix, which provides free nutrition information (including calculators for many restaurants) and an available API. Access to the API includes a free tier and they state that freeware mobile apps can get a bump in that access for no charge.

Projects, coding, etc.

• We’ve been migrating a lot of college sites to a newly-established WordPress platform. This week I’m getting familiar with Gravity Forms to help with that effort. (PHP)
• Been helping out (and working towards the offered bounty) a Stackoverflow user having trouble programmatically writing to Active Directory. (C#)