Getting started

In this section we’ll be writing a simple blueprint and running a Flobot…

Install Node.js

First ensure you have Node.js installed… FlobotJS requires at least v6.9 LTS.

To check everything’s OK, run node from the command line:

$ node --version
v6.9.1

Configure npm

The npm command (Node Package Manager) comes bundled with Node.js. But again, might be worth a quick check:

$ npm --version
3.5.2

Running npm`behind a proxy

To download packages from the mothership, npm will need access to all your internets. If you’re going to be using FlobotJS from behind a proxy server, then there’s some one-off hurt to get through at his point:

$ npm config set proxy       "http://domain%5Cusername:password@servername:port/"
$ npm config set https-proxy "http://domain%5Cusername:password@servername:port/"

Note: Use URL encoding to include \ characters (i.e. replace them with %5C as above). More here.

To check NPM is using your proxy correctly, try the following (which should contact the mothership to find out the latest published version of the Flobot package):

$ npm show flobot version
0.0.4

Hello World!

To help show what FlobotJS is about we’ll go through the steps to get Hello World! printed to the console.

All functionality in FlobotJS is delivered via a flow and flows are defined in blueprints. So to get Hello World! onto the screen, we’re going to need ourselves a blueprint…

Nothing to it: make a directory, with a /flows sub-directory and a /blueprint.json file:

Directory structure for the Hello World! tutorial

Edit the content of the /blueprint.json file, so it looks like:

{
  "namespace": "tutorial",
  "name": "helloWorld",
  "version": "1.0",

  "label": "Hello World! tutorial",
  "author": "John Doe",

  "organisation": "Flobots",
  "description": "Provides a simple flow to print 'Hello World!' to the console",
  "tags": ["tutorial", "test"] 
}
  • The important takeaway here is that our blueprint is named helloWorld and it will live within the tutorial namespace. Blueprints which share the same namespace can refer to each others components. The rest of the blueprint.json is meta tinsel.

Now we need to define a flow for FlobotJS to run

Create a /flows/hello-world.json file:

Revised structure showing hello-world.json file

…and edit its content to:

{
  "description": "Prints 'Hello World!' to the console and nothing else",
  "version": "1.0",
  "initialStateId": "logging",
  "fsm": {
    "logging": {
      "options": {
        "text": "Hello World!"
      }     
    }    
  }  
}

That’s the blueprint finished!

  • The fsm property is the meat of each flow and defines one or more states
  • The keys of the fsm object are the ids for each state in the flow. So in this example we’re working with one state with an id of logging
  • The initialStateId property is important: it indicates which state things should start from

As a quick aside, to keep things simple, some shorthand is in-play in this flow. Each state needs associating with a State Class. This can be done explicitily using the className property:

"fsm": {
  "logging": {
    "className": "logging"
    "options": {
      "text": "Hello World!"     
    }    
  }  
}

…but if you omit className (like we did in our example flow) it will be inferred from the state’s id.

Now we need to create a project to run our new blueprint…

Make a totally fresh directory somewhere (not inside the blueprint) and create an /index.js file inside it:

Startings of a FlobotJS project structure

Then, from within that directory, use the npm command to install the flobot package:

$ npm install flobot

After some huffing-and-puffing a new /node_modules directory should appear full of wondrous things:

Shows a new node_modules dir has appeared

Now we’ll make sure FlobotJS can boot without any problems… edit the /index.js to be:

 'use strict'
 var flobot = require('flobot')
 
 flobot.boot(
   {
     blueprintPaths: [
     
       // Change the path below to point to wherever you created
       // that blueprint directory earlier...
      '/myProjects/blueprints/hello-world-blueprint'
      
     ]
   },
   
   // Callback function
   function (err, services) { 
     if (err) {
       console.error('There were errors.')
     } else {
       console.log('Done booting.')
     }         
   }
   
 )

Make sure you change the blueprint path to point to your hello-world-blueprint directory, then from the same directory that the index.js file is located, run:

$ node index.js

…a chunk of output should then appear - for everything to have worked it should end with Done booting.

  • This is a relatively exciting moment! FlobotJS has booted, consumed our demo blueprint and offered us lots of ready-to-use services - the reason we’re not seeing Hello World! yet is that we haven’t used any of those services.

Let’s run a Flobot!

Edit the ./index.js file again, keep the changes you made previously but replace the callback function with:


  // Callback function
  function (err, services) {
    if (err) {
      console.error('There were errors booting.')
    } else {
      // No problems booting, so start a new Flobot...
      services.flobots.startNewFlobot(
        'tutorial_helloWorld_1_0', // flowId
        {}, // Flobot options
        function (err, flobot) {
          if (err) {
            console.error('There were errors running the Flobot')
          }
        }
      )
    }
  }
  
  • As before, if everything goes as expected during the boot process, FlobotJS will now offer some services
  • Several services are returned to the callback function, including flobots that we’re using here
  • The flobots service offers an API with a few methods including startNewFlobot. The minimum required to call startNewFlobot (as seen in this example) is a flowId - here we’re using the flowId tutorial_helloWorld_1_0.
  • These flowIds are conjured by combining the name of the blueprint’s namespace (tutorial), the flow’s name (helloWorld - which has been inferred from the /flows/hello-world.json filename) and the version number of the flow (as defined in the /flows/hello-world.json file).

…once the replacement callback function is in-place, re-run:

$ node index.js

Boom! You should now see Hello World! printed on the console.

In this first tutorial we’ve used some of the major components of the framework (blueprints, flows, states and flobots). The good news is that the distance from this point to running more complex flows only requires the introduction of a few more components.