dan.stoll

Start a Nintex Workflow Cloud Workflow from an Amazon IoT Button

Blog Post created by dan.stoll Employee on Oct 12, 2016

The other day I thought I'd have a bit of a play with the Amazon button I ordered AWS IoT Button and since I had been testing out the Nintex Workflow Cloud Advance Preview,  'External Start feature'. Why not try and hook them up. There was a bit of a learning curve here as I had never used AWS at all. For this blog post, I'm not going to go into too much depth here as to be honest, I'm pretty sure I didn't do everything right  I just fudged my way around until I got something to work.. Who needs instructions ? Right !!   lol .. 

What I'm playing on doing is to execute a Nintex Workflow Cloud workflow by pushing an AWS button. There a nu,mber of possible scenarios for this, but for my example I'm just going to have a workflow run and send me an email.. 

 

Before we dive into AWS and the IoT button, we need to setup a workflow inNintex Workflow Cloud that has an external start end point configured. For the rest of this post, I'm going to refer to Nintex Workflow Cloud as NWC..

 

Log into your NWC tenant and create a new workflow.

The first thing you need to do is configure the start event. So click on the start event action and select the Nintex Connector with the External start Event. Then add however many start variables you wish to pass into the workflow. For my example I'm just going to use once variable called 'data'.

You then build out any needed workflow logic. For this workflow example I am going to add and configure a 'send an email' action to email me as a notification of execution success.

Once you have your workflow sorted out, select publish in the top toolbar. Give your workflow a name, and you'll be presented with a success screen like the screenshot below.

Copy the URL and paste it into a browser to get your Swagger definition..

{
  "swagger": "2.0",
  "info": {
    "title": "AWSMagic",
    "description": "",
    "version": "1.0.0"
  },
  "schemes": [
    "https"
  ],
  "basePath": "/api/v1/workflow/published",
  "produces": [
    "application/json"
  ],
  "consumes": [
    "application/json"
  ],
  "host": "ntxdemo14.workflowcloud.com",
  "paths": {
    "/3ecc9955-a4c3-4fae-9c1a-dd28f1331ea3/instances": {
      "post": {
        "summary": "Starts the workflow",
        "description": "Starts workflow: AWSMagic",
        "operationId": "wf3ecc9955-a4c3-4fae-9c1a-dd28f1331ea3",
        "parameters": [
          {
            "name": "API Parameters",
            "required": true,
            "in": "body",
            "schema": {
              "type": "object",
              "properties": {
                "startData": {
                  "type": "object",
                  "properties": {
                    "se_data1": {
                      "title": "data",
                      "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_data1": {
                      "title": "data",
                      "description": "",
                      "type": "string"
                    }
                  }
                },
                "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"
          }
        }
      }
    }
  }
}

Now we need to break this out for a couple of reasons. We need the Workflow ID. Which is the GUID in the Path string.

"paths": {
    "/3ecc9955-a4c3-4fae-9c1a-dd28f1331ea3/instances": {

This GUID can also be seen in the URL:

/api/v1/workflow/published/3ecc9955-a4c3-4fae-9c1a-dd28f1331ea3/swagger.json?token=<token>

 

We also need to grab the internal name for our start variables. So in my case I have 1 start variable called data. However the internal name is 'se_data1' which can be seen here:

"startData": {
                  "type": "object",
                  "properties": {
                    "se_data1": {
                      "title": "data",
                      "description": "",
                      "type": "string"
                    }
                  }
                },

It's just that easy! It looks like a lot of stuff, but really this should take no more than 5 minutes to setup.

 

On to the next steps!

 

On the AWS side the first step is to register your button with AWS.

 

Instead of listing out everything I went through to register the button with AWS, you can follow the instructions via the following link: http://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html. It isn't overly difficult, just a few hurdles to get it done.

 

Now once you have your device communicating with AWS you are ready to rock.  Which takes me back to the function screen above. I have created a new function called 'myExternalStart'. Which you can see is using NODE.js

and here is that function:

 

'use strict';
const https = require('https');
/**
* Pass the data to send as `event.data`, and the request options as
* `event.options`. For more information see the HTTPS module documentation
* at https://nodejs.org/api/https.html.
*
* Will succeed with the response body.
*/

exports.handler = (event, context, callback) => {
    console.log('Received event:', event.clickType);
    var options = {
      hostname: '<server>.workflowcloud.com',
      port: 443,
      path: '/api/v1/workflow/<Workflow Guid>?token=<value>',
      method: 'POST',
      headers: { 'Content-Type': 'application/json' }
    };
   
    var startdata = JSON.stringify({
        se_data1: "Put your Start Variable stuff here"
    });
   
    var req = https.request(options, (res) => {
      console.log('statusCode:', res.statusCode);
      console.log('headers:', res.headers);
   
      res.on('data', (d) => {
        process.stdout.write(d);
      });
    });
    req.write(startdata);
    req.end();
   
    req.on('error', (e) => {
      console.error(e);
    });
};

 

I have removed my NWC Tenant Name, the workflow GUID and the token, so you will need to replace these with your own settings.  Also make sure you have your trigger setup 

From the code window you can test your call without having to press the button. After saving, press the test button,

your workflow should execute almost immediately.

 

And that's it folks! You should be able to apply the exact same principles to the external start feature in Nintex Workflow for SharePoint 2013 and 2016 as well.

 

Now for the Dev type folks reading this I'm sure your thinking "well that is just NODE.js, I don't actually have to use that function with an AWS button, I could just do that in a custom app, form, or whatever !!" and you would be right!  Let us know what you do with it .

 

To get yourself an advanced Preview tenant of Nintex Workflow Cloud head over to this link

 

http://www.nintex.com/workflow-platform/nintex-workflow-cloud

        

Until next time. Enjoy.

Outcomes