Many of you have noticed that Microsoft has introduced a new personal productivity tool, called Microsoft Flow, to replace the now deprecated SharePoint Designer and some of you have subsequently built out some flows. Now you want to take them to the next level by integrating them into the enterprise workflows you've built out with Nintex Workflow Cloud. But how can it be done?
Well, the great news here is that your Microsoft Flows can easily compliment your Nintex Workflow Cloud (NWC) workflows!
Below, I step through what the flow and workflow actually do. Then, I step through setting up the NWC workflow and the configuration of the HTTP web request from Flow to an External Start enabled NWC workflow so that you'll have a real world example of how it all works.
In this fictitious scenario I tie together several cloud assets:
- A GitHub repository simply called "hello-world" which my dev team uses for an internal development project. When Issues are logged in the repository, they can have two possible metadata values in their titles:
- 10 - Baseline issue. This value is used to request resolution to problems using best effort but can be escalated if the team thinks it needs to be
- 80 - Critical issue. This value is used for tracking problems that can derail the project
- A ZenDesk tenant for tracking critical issues
On the process side we have two pieces that needs to be married up:
- A simple Microsoft Flow that watches for Issues to be assigned in my GitHub repository and then makes a call to my NWC workflow (configured to start based on an external call):
- An NWC workflow configured for external start that:
- Parses two regular expressions in parallel (to grab the issue code # mentioned above and the rest of the issue title from the GitHub issue)
- Branches by value of the issues code (80 <-> 10)
- If 80 we immediately create a ZenDesk ticket
- If 10 we assign a task to a member of the team to handle the casual issue triage and who has the ability to escalate and thus push the issue over to the A-Team via a ZenDesk ticket:
Execution Walkthrough
First, I create an issue in my GitHub repository (hello-world) with '10' in the title:
Then I assign it (to myself in this case since the flow doesn't care about the assignee):
Now the flow will pick up on the issue assignment and make a call to my NWC External Start URL and pass along some of the GitHub issue metadata (the repository URL, the issue title, and issue body) as start variables. Once the NWC workflow starts, it examines the issue title and pulls the value of our issue code (in this case 10 which is a less critical issue). Then a task is assigned to our team inbox so that someone can take a look at it and decide if it can be taken care of as a baseline activity or if we need to escalate it.
Below is the task notification email. By using the Express Approval action in NWC, I am able to reply to the email with the desired outcome. In this case, I reply with Investigate.
Since I replied with the term 'Investigate', the NWC workflow proceeds to create a ticket in ZenDesk:
Building It
I'm going to assume here that you have a basic understanding of how to use NWC so I won't step through absolutely every button click to build this workflow, just the (arguably) important parts.
The Nintex Workflow Cloud workflow
Let's create a new workflow in NWC:
Then double click on the Start event action:
Now select Nintex under connector and then External start on the Event dropdown and create the variables that will be used to store the metadata passed from the flow:
At this point you can drag and drop a Run parallel paths action and a couple of Apply a regular expression actions onto the canvas:
Before we get into setting up the regex's here are some handy links to assist you with building regular expressions in your NWC workflows as it uses Ruby syntax:
Now configure the first Apply a regular expression to parse the issue code. Notice that I've inserted the issuetitle variable into the Input text field and selected Extract (as I want to pull the value out). Also, please note the pattern ^[^-]* used to select everything before a hyphen (since the structure the team uses for logging issues is ##-ISSUETITLE):
Now configure the Apply a regular expression on the other side of the parallel path action to parse the issue title. Notice that I've inserted the issuetitle variable into the Input text field and selected Extract (as I want to pull the value out). Also, please note the pattern [^-]+$ used to select everything after the hyphen (since the structure the team uses for logging issues is ##-ISSUETITLE
Now I am just going to add a Branch by value action:
And add two branches (80 and 10):
This switching action will allow the workflow to either Create a ticket in ZenDesk if the issue status code is 80 or first assign an Express Approval task to the team if the issue code is 10.
When adding the Create a Ticket for ZenDesk action, it can be configured to pass the values from our GitHub issue as such:
Beyond these actions, the rest of the workflow configuration is trivial in the context of this post. Feel free to use your imagination for the rest...
When you publish your workflow you will get the External start URL:
Copy the URL and paste it in a new tab in your browser:
When you open the URL, you should get something like this:
{ "swagger": "2.0", "info": { "title": "Flow to NWC Test Workflow", "description": "", "version": "1.0.0" }, "schemes": [ "https" ], "basePath": "/api/v1/workflow/published", "produces": [ "application/json" ], "consumes": [ "application/json" ], "host": "TENANTNAME.workflowcloud.com", "paths": { "/WORKFLOWID/instances": { "post": { "summary": "Starts the workflow", "description": "Starts workflow: Flow to NWC Test Workflow", "operationId": "OPERATIONID", "parameters": [ { "name": "API Parameters", "required": true, "in": "body", "schema": { "type": "object", "properties": { "startData": { "type": "object", "properties": { "se_repository1": { "title": "repository", "description": "", "type": "string" }, "se_issuetitle1": { "title": "issuetitle", "description": "", "type": "string" }, "se_issuebody1": { "title": "issuebody", "description": "", "type": "string" } } }, "options": { "type": "object", "properties": { "callbackUrl": { "title": "callbackUrl", "description": "A Url to return the results back (https urls only)", "type": "string" } } } } } }, { "name": "token", "type": "string", "in": "query", "description": "A security token to start the workflow" } ], "responses": { "202": { "description": "Accepted", "x-ntx-callback-schema": { "type": "object", "properties": { "returnData": { "type": "object", "properties": { "se_repository1": { "title": "repository", "description": "", "type": "string" }, "se_issuetitle1": { "title": "issuetitle", "description": "", "type": "string" }, "se_issuebody1": { "title": "issuebody", "description": "", "type": "string" }, "c_issue_code1": { "title": "Issue Code", "description": "", "type": "string" }, "c_issue_title1": { "title": "Issue Title", "description": "", "type": "string" }, "c_zen_desk_ticket_id1": { "title": "ZenDesk Ticket ID", "description": "", "type": "number", "format": "double" } } }, "workflow": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found" }, "410": { "description": "Gone" }, "429": { "description": "Too Many Requests" }, "503": { "description": "Service Unavailable - Overloaded" }, "default": { "description": "Unexpected Error" } } } } }}
You will need to get the internal name of your NWC External start variables. Be aware that they will be formatted a bit differently than the friendly name you used when creating them:
External Start variable structure = se_VARIABLENAME#
Copy these internal variable names into your text editor of choice (NotePad++, Evernote, OneNote, Notepad, pen and paper...) as we'll reference them in our web call when we build the flow.
The Microsoft Flow flow
I'm not going to walk through a step by step build of a flow as that isn't important here. It's really more about how do you take data from your flow and pass it over to the NWC workflow.
For the example scenario, my flow is simply configured with a connection to GitHub and a trigger to pick up an issue when it gets assigned:
Next I add an HTTP action and configure it with the external start URL I picked up when I published my NWC workflow:
Notice the Uri is slightly different from what we copied and pasted into the browser earlier. The URL given to you from the NWC publish dialog is the Swagger definition. To change it into a valid start Uri for Flow, you must replace the 'Swagger.json' portion to 'instances'.
Also, be aware that the JSON parser in the HTTP action configuration is rather strict and may throw errors based on your formatting. Feel free to use the code samples below:
Headers:
{ "content-type": "application/json"}Body:
{ "startData": { "se_repository1": "FLOW_REPOSITORY_URL_HERE", "se_issuetitle1": "FLOW_ISSUETITLE_HERE", "se_issuebody1": "FLOW_ISSUEBODY_HERE" }}
Now save the flow and you should be all set. Keep in mind that while NWC supports an optional callback function when using the External start functionality, I am not using it in this example as it is not necessary. But, you may have applications or other scenarios where getting data back from the NWC workflow is important. If that is the case, take a look at the help documentation here:
Start workflows using External Start
http://help.nintex.com/en-US/nwc/#NWC/ExternalStart-call.htm
I hope you enjoyed reading this blog post and find it to be as helpful as I did writing it!
Happy Nintexing!
>>>>>UPDATE 12/5/16:
So our NWC devs (crafty bunch that they are) have made some of this configuration even easier! The publishing dialog for External Start workflows now has all of the pertinent information you will need for your external system.
Simply, copy/paste the various fields and enjoy!
