Many people are familiar with Nintex as a workflow solution for SharePoint and Office 365, but last year Nintex released their Workflow Cloud offering (NWC), which has no dependency on SharePoint or Office 365. NWC comes with dozens of native workflow actions connecting to many different external cloud services, such as Salesforce, Box, Dropbox, Google, SharePoint, and many others. Nintex frequently updates NWC with new connectors/actions for additional cloud services. And more importantly, Nintex recently added an extensibility framework with a published SDK to allow developers to create their own custom NWC connectors.
This new extensibility model is branded as Nintex Xtensions, and leverages the OpenAPI specification, (aka Swagger), which is considered the most popular open source framework for creating RESTful APIs. While Nintex Xtensions is well documented in their SDK & Help files, the documentation assumes that you (the developer) are familiar with how to write the code for for your custom connector as well as create the necessary Swagger definition file, which you need to import into NWC in order to configure your connector.
I decided the easiest approach for me to create a custom Xtension for NWC was to use Azure Functions, which provides a scalable, “serverless”, compute-on-demand platform to host and execute the code. Additionally, Azure Functions includes tooling to generate the Swagger definition file for my code. And you can develop and test Azure Functions for free. If your Azure Function is used in production, you’ll end up paying for the actual compute time. But Azure provides a limited amount of compute time per month at no cost, so for testing or a Proof of Concept, it would likely cost you $0/month.
Since, there is a lot of content for this article, I decided to break it down into four separate posts:
- Part 1 – Introduction, Requirements & Setup related to Azure Functions and Visual Studio Tools for Azure (this post)
- Part 2 – Develop C# code in Visual Studio
- Part 3 – Edit Swagger Definition
- Part 4 – Importing and using the connector in Nintex Workflow Cloud
For my first NWC Xtension, I wanted to select a project where the coding logic would be routine, since I was learning a few new technologies (Azure Functions & the NWC Xtensions Framework), but also a project that would have some real-world value.
Having implemented various projects in the past for clients to process Travel Authorization Requests and Expense Reports, I figured it would be useful to have an Xtension to calculate the allowed per diem expense amounts for hotels and meals. The U.S. GSA website allows government employees and contractors to lookup the max per diem amounts that can be reimbursed for hotels and meals. The GSA also provides a REST based Per Diem API that can be queried by year and location (Zip, County or City & State).
This API returns a JSON message, containing the maximum per diem amount for meal and hotel expenses. The response contains a single value for the meal per diem and 12 values for hotel per diem (one value for each month, as the hotel per diem changes based on peak months when hotels tend to be more expensive).
To simplify the requirements for my Xtension, I decided it would accept two inputs (Zipcode and TravelDate) and return two values (HotelPerDiem and MealsPerDiem). I then used Visual Studio 2017 to create my Azure Function as a simple wrapper around the GSA Per Diem API.
I assume you’re reading this article due to your interest in Azure Functions and/or Xtensions for Nintex Workflow Cloud, not for GSA Per Diem rules. I expect that anyone reading this will adapt the concepts to whatever business logic or integration requirements that you may have. Although I’ve provided code samples for the GSA Per Diem integration, that’s only to ensure completeness of the content.
If you haven’t used Azure Functions before, before starting in Visual Studio I suggest that you Create your first function in the Azure portal to understand the basics of Azure Functions. Ultimately, you may decide you prefer to develop in the portal rather than in Visual Studio. But the rest of this article is based on using Visual Studio.
The following steps are needed before you can really begin:
- Make sure you have an Azure subscription. If not, you’ll need to create a free account before you begin.
- Download and install the Visual Studio 2017 Tools for Azure Functions, including:
- Visual Studio 2017 (version 15.3) Preview (it will not work with any earlier versions of Visual Studio)
- Include the the “ASP.NET and web development” or “Azure development” workload installed
- Download and install the Visual Studio 2017 Tools for Azure Functions extension
- Once your Visual Studio environment is configured per instructions above, you can create your first Azure Functions project in Visual Studio. From the New Project dialog, select Visual C# as your language and the Azure Functions project template, as shown below:
- Provide a project and solution name for your new function, select your desired folder location, and click the OK button. This creates the Visual Studio project which represents a single Azure Function “App”. We can then add one or more individual Azure Functions to this App / Project.
- Once the new Project is created, we’ll need to add an Azure Function to it. From the Solution Explorer, right click on the project name and select Add> New Item. This shall display the Add New Item dialog. Select Azure Function, provide a name for the new class, and click Add, as shown below:
- You’ll then be prompted to specify the type of trigger that this function should use. Since NWC will call our Xtension over HTTP, you’ll need to select the HttpTrigger. At this point, you can select the AccessRights (I used “Function”), and specify the FunctionName. I suggest using the same name as was used to create the C# class in the prior step. This will create a new C# so you can start developing your code. Note that at this point, everything has been done locally. Later, we’ll Publish our new Function App and any specific Functions to Azure.
Publish to Azure Functions
Now that our Visual Studio project is created, we can publish the project which will create the new Function App with an empty function in Azure Functions. From the Visual Studio Solution Explorer, right click on your project name and click the Publish option. This will display the Publishing screen with options to create a new Function App or select an existing one:
Click the Publish button, which will display the Create App Service dialog, as shown below:
Provide your preferred App Name and select the Subscription, Resource Group, Service Plan and Storage Account. Then click the Create button, which will provision your new Function App in Azure. You can then login to your Azure portal to inspect your new Function App and function:
As we start and continue to write the code for our function, we can publish our changes as often as needed to Azure. Now that our Azure Functions project is setup in Visual Studio, we can start on our C#, which I’ll cover in part 2.