The basics

Setup a node and run your first workflow.

Project directory structure

Create a directory named letsflow-tutorial with a subdirectory basic.

$ mkdir letsflow-tutorial
$ mkdir letsflow-tutorial/basic
$ cd letsflow-tutorial

Creating a scenario

A Live Contract must contain of one or more scenarios that describes the process(es) we're automating. We can write a scenario in either JSON or YAML.

Create file scenario.yml (or scenario.json) in the basic directory.

YAML

schema: "https://specs.letsflow.io/v0.2.0/scenario/schema.json#"
title: The basics

JSON

scenario.json

{
    "$schema": "https://specs.letsflow.io/v0.2.0/scenario/schema.json#",
    "title": "The basics"
}

Defining actors

Actors are organizations or individuals play a role in the process. The scenario needs to define which actors (may) exist.

YAML

$schema: "https://specs.letsflow.io/v0.2.0/scenario/schema.json#"
title: The basics

actors:
  initiator:
    title: Initiator

JSON

{
    "$schema": "https://specs.letsflow.io/v0.2.0/scenario/schema.json#",
    "title": "The basics",
    "actors": {
        "initiator": {
            "title": "Initiator"
        }
    }
}

We've defined a single actor for the process; the initiator. Normally a process contains 2 or more actors.

The key initiator is used to reference the actor. The title must be defined, but only exists for displaying purposes.

Defining actions

All actions that any actor can perform within the process must be defined at forehand in the scenario.

YAML

$schema: "https://specs.letsflow.io/v0.2.0/scenario/schema.json#"
title: My first Live Contract

actors:
  initiator:
    title: Initiator

actions:
  complete:
    title: Complete the process
    actor: initiator

JSON

{
    "$schema": "https://specs.letsflow.io/v0.2.0/scenario/schema.json#",
    "title": "The basics",
    "actors": {
        "initiator": {
            "title": "Initiator"
        }
    },
    "actions": {
        "complete": {
            "title": "Complete the process",
            "actor": "initiator"
        }
    }
}

The complete action can be performed by the initiator actor. The intend of this action is to complete the process. However that transition need to be defined in the state.

The initial state

When a process is started, it's in the initial state. From this state in can transition to other states, until the process is completed.

YAML

$schema: "https://specs.letsflow.io/v0.2.0/scenario/schema.json#"
title: My first Live Contract

actors:
  initiator:
    title: Initiator

actions:
  complete:
    title: Complete the process
    actor: initiator

states:
  initial:
    action: complete
    transition: :success

JSON

{
    "$schema": "https://specs.letsflow.io/v0.2.0/scenario/schema.json#",
    "title": "Basic user",
    "actors": {
        "initiator": {
            "title": "Initiator"
        }
    },
    "actions": {
        "complete": {
            "title": "Complete the process",
            "actor": "initiator"
        }
    },
    "states": {
        "initial": {
            "action": "complete",
            "transition": ":success"
        }
    }
}

While in the initial state, only the complete action can be performed. Once the action is performed, the process will transition to the :success end state, meaning the process has been completed successfully.

Running a test

To ensure the Live Contract behaves as expected, we need to create and run tests. Tests must be defined using the Gherkin syntax. The Live Contracts test suite that comes with the full node, defines the steps that can be used in the test.

Create file main.feature in the basic directory.

main.feature

Feature: Run a simple process that is completed in one step

  Background:
    Given a chain is created by "Joe"
    Given "Joe" creates the "main" process using the "basic" scenario
    And   "Joe" is the "initiator" actor of the "main" process

  Scenario:
    When "Joe" runs the "complete" action of the "main" process
    Then the "main" process is completed

We have a single identity named "Joe". The name is arbitrary, but used to keep the identities apart.

Joe initializes the Live Contract by creating a new chain and using our basic scenario. The process name "main" is also arbitrary and used to reference a specific process. It's possible to run multiple processes may be running for a Live Contract, but in our case only a single process exists.

We need to specify which role Joe is going to have in the process. In this case he's the initiator of the process.

In the Scenario section (this is unrelated to the workflow scenario), we state that will Joe performs the complete action. As defined in our workflow scenario, the process should transition from initial to :success, which means the process has been completed successfully.

Running the Live contract tester

lctest is a command line tool to test workflows described in a Live Contract. It requires PHP7+ with the yaml and mongodb PECL extensions. For more installation, please read the installation guide.

$ wget "https://github.com/legalthings/workflow-tester/raw/master/lctest.phar"
$ php lctest.phar basic

Congratulations!

You've successfully created and tested your first workflow.