Getting Started

Now that you hopefully know the key concepts (read here for a refresher) behind Tymly it would be a good idea to put them into use. What better way is there than a Hello World example?

Before you begin first make sure you have Node.js installed. Tymly requires at least v8.5.0.

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

All functionality in Tymly is delivered via a state machine and state machines are defined inside blueprints. So, to get ‘Hello World!’ onto the screen, we’re going to need ourselves a blueprint.

Firstly create a directory with a /state-machines sub-directory and a /blueprint.json file:

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

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 other’s components. The rest of the blueprint.json is meta tinsel.
Now we need to define a state machine for Tymly to execute

Create a /state-machines/hello-world.json file:

…and edit its content to:

That’s the blueprint finished!

• The keys of the ‘States’ object are the unique names for each state in the State Machine. So in this example we’re working with one state with the name HelloWorld
• The ‘StartsAt’ property is mandatory: it indicates the first state which to run when the State Machine is executed
• Please see the Amazon States Language specification for further information about how to conjure a State Machine

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

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

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

execute-hello-world / node_modules / index.js

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:

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

• This is a relatively exciting moment! Tymly has booted, consumed the demo blueprint and offered 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.

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

• As before, if everything goes as expected during the boot process, Tymly will offer some services
• Several services are returned to the callback function, including statebox that we’re using here
• The statebox service offers an API with a few methods including startExecution. The minimum required to call startExecution (as seen in this example) is a state machine name – here we’re using tutorial_helloWorld_1_0.
• These unique names are conjured by combining the blueprint’s namespace (tutorial), the state machines’s name (helloWorld – which has been inferred from the /state-machines/hello-world.json filename) and the version number of the state machine (as defined in the /state-machines/hello-world.json file).

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

Hooray! You should now see ‘Hello World!’ printed on the console.

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