A handshake

In the previous tutorial we created our first Live Contract and tested it with lctest. The scenario only defined a single actor. In most workflows (especially decentralized once), multiple actors participate on the process.
Create a new handshake subdirectory and copy scenario.yml from the basic directory.
Adding the recipient actor
Let's expand the scenario for a process where two actors greet each other. We start with our previous scenario and add the recipient actor.
YAML
JSON
1
schema: https://specs.letsflow.io/v0.3.0/scenario
2
title: A handshake
3
​
4
actors:
5
  initiator:
6
    title: Initiator
7
  recipient:
8
    title: Recipient
9
​
10
actions:
11
  complete:
12
    actor: initiator
13
​
14
states:
15
  initial:
16
    on: complete
17
    goto: (success)
Copied!
1
{
2
    "schema": "https://specs.letsflow.io/v0.3.0/scenario",
3
    "title": "A handshake",
4
    "actors": {
5
        "initiator": {
6
            "title": "Initiator"
7
        },
8
        "recipient": {
9
            "title": "Recipient"
10
        }
11
    },
12
    "actions": {
13
        "complete": {
14
            "title": "Complete the process",
15
            "actor": "initiator"
16
        }
17
    },
18
    "states": {
19
        "initial": {
20
            "on": "complete",
21
            "goto": "(success)"
22
        }
23
    }
24
}
Copied!
Greeting each other
We want the two actors to interact in the form of a simple greeting:
Initiator: Hi, how are you?
Recipient: Fine. How about you?
Initiator: Fine
The initiator will still complete the process, but from the initial state it will first do a greeting, expecting a reply. We'll add these 2 actions and subsequently the states where these can be performed. First the initiator waits on the recipient and then visa versa.
YAML
JSON
1
schema: https://specs.letsflow.io/v0.3.0/scenario
2
title: A handshake
3
​
4
actors:
5
  initiator:
6
    title: Initiator
7
  recipient:
8
    title: Recipient
9
​
10
actions:
11
  greet:
12
    actor: initiator
13
  reply:
14
    actor: recipient
15
  complete:
16
    actor: initiator
17
​
18
states:
19
  initial:
20
    on: greet
21
    goto: wait_on_recipient
22
  wait_on_recipient:
23
    on: reply
24
    goto: wait_on_initiator
25
  wait_on_initiator:
26
    on: complete
27
    goto: (success)
Copied!
1
{
2
    "schema": "https://specs.letsflow.io/v0.3.0/scenario",
3
    "title": "Basic user",
4
    "actors": {
5
        "initiator": {
6
            "title": "Initiator"
7
        },
8
        "recipient": {
9
            "title": "Recipient"
10
        }
11
    },
12
    "actions": {
13
        "greet": {
14
            "title": "Greet the recipient",
15
            "actor": "initiator"
16
        },
17
        "reply": {
18
            "title": "Reply to the greeting",
19
            "actor": "recipient"
20
        },
21
        "complete": {
22
            "title": "Finish the conversation",
23
            "actor": "initiator"
24
        }
25
    },
26
    "states": {
27
        "initial": {
28
            "on": "greet",
29
            "goto": "wait_on_recipient"
30
        },
31
        "wait_on_recipient": {
32
            "on": "reply",
33
            "goto": "wait_on_initiator"
34
        },
35
        "wait_on_initiator": {
36
            "on": "complete",
37
            "goto": "(success)"
38
        }
39
    }
40
}
Copied!
We see that we transition from the initial state to wait_on_recipient, than wait on initiator and finally to a successful completion of the proces.
Running the test
As before, we want to create a run a test to make sure the process runs as expected.
main.feature
1
Feature: Two actors greet each other
2
​
3
  Background:
4
    Given a chain is created by "Joe"
5
    Given "Joe" creates the "main" process using the "handshake" scenario
6
    And   "Joe" is the "initiator" actor of the "main" process
7
    And   "Jane" is the "recipient" actor of the "main" process
8
​
9
  Scenario:
10
    When "Joe" runs the "greet" action of the "main" process
11
    Then the "main" process is in the "wait_on_recipient" state
12
    When "Jane" runs the "reply" action of the "main" process
13
    Then the "main" process is in the "wait_on_initiator" state
14
    When "Joe" runs the "complete" action of the "main" process
15
    Then the "main" process is completed
Copied!
Choose to ignore
While it's nice to reply, the recipient may also choose to ignore the greeting. In this the process will be cancelled. Let's add an ignore action and make is possible to either reply or ignore in the wait on recipient state.
YAML
JSON
1
schema: https://specs.letsflow.io/v0.3.0/scenario
2
title: A handshake
3
​
4
actors:
5
  initiator:
6
    title: Initiator
7
  recipient:
8
    title: Recipient
9
​
10
actions:
11
  greet:
12
    actor: initiator
13
  reply:
14
    actor: recipient
15
  ignore:
16
    actor: recipient
17
  complete:
18
    actor: initiator
19
​
20
states:
21
  initial:
22
    on: greet
23
    goto: wait_on_recipient
24
  wait_on_recipient:
25
    transitions:
26
      - on: reply
27
        goto: wait_on_initiator
28
      - on: ignore
29
        goto: :cancelled
30
  wait_on_initiator:
31
    on: complete
32
    goto: (success)
Copied!
1
{
2
    "schema": "https://specs.letsflow.io/v0.3.0/scenario",
3
    "title": "Basic user",
4
    "actors": {
5
        "initiator": {
6
            "title": "Initiator"
7
        },
8
        "recipient": {
9
            "title": "Recipient"
10
        }
11
    },
12
    "actions": {
13
        "greet": {
14
            "actor": "initiator"
15
        },
16
        "reply": {
17
            "actor": "recipient"
18
        },
19
        "ignore": {
20
            "actor": "recipient"
21
        },
22
        "complete": {
23
            "actor": "initiator"
24
        }
25
    },
26
    "states": {
27
        "initial": {
28
            "on": "greet",
29
            "goto": "wait_on_recipient"
30
        },
31
        "wait_on_recipient": {
32
            "transitions": [
33
                {
34
                    "on": "reply",
35
                    "goto": "wait_on_initiator"
36
                },
37
                {
38
                    "on": "ignore",
39
                    "goto": "(cancelled)"
40
                }
41
            ]
42
        },
43
        "wait_on_initiator": {
44
            "on": "complete",
45
            "goto": "(success)"
46
        }
47
    }
48
}
Copied!
Rather than a single action property, the wait_on_recipient state now has an actions property that contains an array with the actions that be performed. The transition property has been replaced with a transitions property, defining the transition for each action.
Testing the scenario
We can add a new Scenario section in our test file to test the path in the process where the recipient "Jane" ignores the greeting.
main.feature
1
Feature: Two actors greet each other
2
​
3
  Background:
4
    Given a chain is created by "Joe"
5
    Given "Joe" creates the "main" process using the "handshake" scenario
6
    And   "Joe" is the "initiator" actor of the "main" process
7
    And   "Jane" is the "recipient" actor of the "main" process
8
​
9
  Scenario:
10
    When "Joe" runs the "greet" action of the "main" process
11
    Then the "main" process is in the "wait_on_recipient" state
12
    When "Jane" runs the "reply" action of the "main" process
13
    Then the "main" process is in the "wait_on_initiator" state
14
    When "Joe" runs the "complete" action of the "main" process
15
    Then the "main" process is completed
16
​
17
  Scenario:
18
    When "Joe" runs the "greet" action of the "main" process
19
    Then the "main" process is in the "wait_on_recipient" state
20
    When "Jane" runs the "ignore" action of the "main" process
21
    Then the "main" process is cancelled
Copied!
You can have multiple Scenario sections. The Background runs once and than make a backup of the databases. After each scenario the data in the database is reverted, to run the next scenario.
A conversation
In this process Jane (the recipient) can only ignore the greeting or respond with "fine". But unfortunately it's not always sunshine and rainbows. It's possible to define different responses for an action.
Up until now, we've created the scenario first and added a test later. It's recommended to take a TDD style approach, where you start with a test and then write or modify your scenario.
Jane might answer with "not so good", asking for sympathy from Joe. He might still end the conversation (complete) by answering with "Sorry to hear that" and move on. A nicer thing to is is to ask "What's the matter?" upon which Jane can give a response.
Testing the scenario
We could add a new Scenario section to our main.feature test file, but instead we'll create a new test file recipient-not-good.feature specifically for the use case where the greeting turns into a bigger conversation.
We already have two paths we want to test. One where Joe brushes Jane off and one where he's genuinely interested. We'll expand the background to the point where Jane give her response.
recipient-not-good.feature
1
Feature: Two actors meet. The recipient is not doing well.
2
​
3
  Background:
4
    Given a chain is created by "Joe"
5
    Given "Joe" creates the "main" process using the "handshake" scenario
6
    And   "Joe" is the "initiator" actor of the "main" process
7
    And   "Jane" is the "recipient" actor of the "main" process
8
    When "Joe" runs the "greet" action of the "main" process
9
    Then the "main" process is in the "wait_on_recipient" state
10
​
11
  Scenario:
12
    When "Jane" runs the "reply" action of the "main" process giving a "not_good" response
13
    Then the "main" process is in the "expect_sympathy" state
14
    When "Joe" runs the "complete" action of the "main" process
15
    Then the "main" process is completed
16
​
17
  Scenario:
18
    When "Jane" runs the "reply" action of the "main" process giving a "not_good" response
19
    Then the "main" process is in the "expect_sympathy" state
20
​
21
    When "Joe" runs the "sympathize" action of the "main" process
22
    Then the "main" process is in the "recipient_can_elaborate" state
23
    When "Jane" runs the "elaborate" action of the "main" process with:
24
      | reason | My cat is stealing my boyfriend. She pnly cuddles with him. |
25
    Then the "main" process is in the "wait_on_initiator" state
26
​
27
    When "Joe" runs the "complete" action of the "main" process
28
    Then the "main" process is completed
Copied!
When the recipient elaborates, she'll send the reason as additional response data. In the tutorial "A proper introduction" we'll see how to use the response data in the process.
The scenario
When we run this test we can see that it fails. The not good response hasn't been defined. We also need to define the sympathize and elaborate actions and the expect sympathy and recipient can elaborate states.
YAML
JSON
1
schema: https://specs.letsflow.io/v0.3.0/scenario
2
title: A handshake
3
​
4
actors:
5
  initiator:
6
    title: Initiator
7
  recipient:
8
    title: Recipient
9
​
10
actions:
11
  greet:
12
    actor: initiator
13
  reply:
14
    actor: recipient
15
    responses:
16
      ok:
17
      not_good:
18
  ignore:
19
    actor: recipient
20
  sympathize:
21
    actor: initiator
22
  elaborate:
23
    actor: recipient
24
  complete:
25
    actor: initiator
26
​
27
states:
28
  initial:
29
    on: greet
30
    goto: wait_on_recipient
31
  wait_on_recipient:
32
    transitions:
33
      - on: reply.ok
34
        goto: wait_on_initiator
35
      - on: reply.not_good
36
        goto: expect_sympathy
37
      - on: ignore
38
        goto: (cancelled)
39
  expect_sympathy:
40
    transitions:
41
      - on: sympathize
42
        goto: recipient_can_elaborate
43
      - on: complete
44
        goto: (success)
45
  recipient_can_elaborate:
46
    on: elaborate
47
    goto: wait_on_initiator
48
  wait_on_initiator:
49
    on: complete
50
    goto: (success)
Copied!
1
{
2
    "schema": "https://specs.letsflow.io/v0.3.0/scenario",
3
    "title": "A handshake",
4
    "actors": {
5
        "initiator": {
6
            "title": "Initiator"
7
        },
8
        "recipient": {
9
            "title": "Recipient"
10
        }
11
    },
12
    "actions": {
13
        "greet": {
14
            "actor": "initiator"
15
        },
16
        "reply": {
17
            "actor": "recipient",
18
            "responses": {
19
                "ok": {},
20
                "not_good": {}
21
            }
22
        },
23
        "ignore": {
24
            "actor": "recipient"
25
        },
26
        "sympathize": {
27
            "actor": "initiator"
28
        },
29
        "elaborate": {
30
            "actor": "recipient"
31
        },
32
        "complete": {
33
            "actor": "initiator"
34
        }
35
    },
36
    "states": {
37
        "initial": {
38
            "action": "greet",
39
            "transition": "wait_on_recipient"
40
        },
41
        "wait_on_recipient": {
42
            "actions": [
43
                "reply",
44
                "ignore"
45
            ],
46
            "transitions": [
47
                {
48
                    "action": "reply",
49
                    "response": "ok",
50
                    "transition": "wait_on_initiator"
51
                },
52
                {
53
                    "action": "reply",
54
                    "response": "not_good",
55
                    "transition": "expect_sympathy"
56
                },
57
                {
58
                    "action": "ignore",
59
                    "transition": ":cancelled"
60
                }
61
            ]
62
        },
63
        "expect_sympathy": {
64
            "actions": [
65
                "sympathize",
66
                "complete"
67
            ],
68
            "transitions": [
69
                {
70
                    "action": "sympathize",
71
                    "transition": "recipient_can_elaborate"
72
                },
73
                {
74
                    "action": "complete",
75
                    "transition": ":success"
76
                }
77
            ]
78
        },
79
        "recipient_can_elaborate": {
80
            "action": "elaborate",
81
            "transition": "wait_on_initiator"
82
        },
83
        "wait_on_initiator": {
84
            "action": "complete",
85
            "transition": ":success"
86
        }
87
    }
88
}
Copied!
The default response has the key "ok" by default. If we define a set of responses without "ok", we also need to set the default_response property of the action.
Keeping the conversation going
Instead of asking "What's the matter?", Joe could say "Sorry to hear that. Please tell me more". By repeating the sympathize action, Joe can keep the conversation going.
recipient-not-good.feature
1
Feature: Two actors meet. The recipient is not doing well.
2
​
3
  Background:
4
    Given a chain is created by "Joe"
5
    Given "Joe" creates the "main" process using the "handshake" scenario
6
    And   "Joe" is the "initiator" actor of the "main" process
7
    And   "Jane" is the "recipient" actor of the "main" process
8
    When "Joe" runs the "greet" action of the "main" process
9
    Then the "main" process is in the "wait_on_recipient" state
10
​
11
  Scenario:
12
    When "Jane" runs the "reply" action of the "main" process giving a "not_good" response
13
    Then the "main" process is in the "expect_sympathy" state
14
    When "Joe" runs the "complete" action of the "main" process
15
    Then the "main" process is completed
16
​
17
  Scenario:
18
    When "Jane" runs the "reply" action of the "main" process giving a "not_good" response
19
    Then the "main" process is in the "expect_sympathy" state
20
​
21
    When "Joe" runs the "sympathize" action of the "main" process
22
    Then the "main" process is in the "recipient_can_elaborate" state
23
    When "Jane" runs the "elaborate" action of the "main" process with:
24
      | reason | My cat is stealing my boyfriend. |
25
    Then the "main" process is in the "expect_sympathy" state
26
​
27
    When "Joe" runs the "complete" action of the "main" process
28
    Then the "main" process is completed
29
​
30
  Scenario:
31
    When "Jane" runs the "reply" action of the "main" process giving a "not_good" response
32
    Then the "main" process is in the "expect_sympathy" state
33
​
34
    When "Joe" runs the "sympathize" action of the "main" process
35
    Then the "main" process is in the "recipient_can_elaborate" state
36
    When "Jane" runs the "elaborate" action of the "main" process with:
37
      | reason | My cat is stealing my boyfriend. |
38
    Then the "main" process is in the "expect_sympathy" state
39
​
40
    When "Joe" runs the "sympathize" action of the "main" process
41
    Then the "main" process is in the "recipient_can_elaborate" state
42
    When "Jane" runs the "elaborate" action of the "main" process with:
43
      | reason | She always comes in to cuddle with him. |
44
    Then the "main" process is in the "expect_sympathy" state
45
​
46
    When "Joe" runs the "sympathize" action of the "main" process
47
    Then the "main" process is in the "recipient_can_elaborate" state
48
    When "Jane" runs the "elaborate" action of the "main" process with:
49
      | reason | Misty has a mean purr. I know it's to taunt me. |
50
    Then the "main" process is in the "expect_sympathy" state
51
​
52
    When "Joe" runs the "complete" action of the "main" process
53
    Then the "main" process is completed
Copied!
Modifying the scenario
To do so, we just need to modify the recipient can elaborate state to transition to expect sympathy. Since the initiator can also complete the process from that state, it doesn't affect our existing use cases.
Previous tests should be, of course, also modified.
YAML
JSON
1
  recipient_can_elaborate:
2
    on: elaborate
3
    goto: expect_sympathy
Copied!
1
        "recipient_can_elaborate": {
2
            "on": "elaborate",
3
            "goto": "expect_sympathy"
4
        },
Copied!
Instructions and titles
As briefly show in the previous tutorial, actors and actions can have a title. We can also provide a title for states and responses. These titles won't affect the process, but can be used in a UI to display to the end users. Additionally it will make the scenario a bit less cryptic.
The title should tell what we're waiting on. The title of the action describes what an actor will do, while the title of the response describes what the actor has done (or has said in this example).
Instructions for a specific actor can be defined for each state. Again, this doesn't influence the process, but can be used in a UI.
YAML
JSON
1
schema: https://specs.letsflow.io/v0.3.0/scenario
2
title: A handshake
3
​
4
actors:
5
  initiator:
6
    title: Initiator
7
  recipient:
8
    title: Recipient
9
​
10
actions:
11
  greet:
12
    actor: initiator
13
    title: Greet the person you're meeting
14
    responses:
15
      ok:
16
        title: Hi, how are you?
17
  reply:
18
    actor: recipient
19
    title: Respond to the greeting
20
    responses:
21
      ok:
22
        title: Fine. How about you?
23
      not_good:
24
        title: Not so good.
25
  ignore:
26
    actor: recipient
27
    title: Ignore the greeting
28
  sympathize:
29
    actor: initiator
30
    title: Ask further
31
    responses:
32
      ok:
33
        title: Sorry to hear that. Please tell me more.
34
  elaborate:
35
    actor: recipient
36
    title: Tell what's the matter.
37
  complete:
38
    actor: initiator
39
    title: End the conversation
40
​
41
states:
42
  initial:
43
    action: greet
44
    transition: wait_on_recipient
45
  wait_on_recipient:
46
    title: Waiting on the recipient to respond.
47
    instructions:
48
      recipient: Respond or, if you're feeling rude, ignore it.
49
    actions:
50
      - reply
51
      - ignore
52
    transitions:
53
      - action: reply
54
        response: ok
55
        transition: wait_on_initiator
56
      - action: reply
57
        response: not_good
58
        transition: expect_sympathy
59
      - action: ignore
60
        transition: :cancelled
61
  expect_sympathy:
62
    title: Waiting on the initiator to respond.
63
    instructions:
64
      initiator: Ask further or end the conversation politely.
65
    actions:
66
      - sympathize
67
      - complete
68
    transitions:
69
      - action: sympathize
70
        transition: recipient_can_elaborate
71
      - action: complete
72
        transition: :success
73
  recipient_can_elaborate:
74
    title: Waiting on the recipient to elaborate.
75
    instructions:
76
      recipient: Please explain why it's not going well.
77
    action: elaborate
78
    transition: expect_sympathy
79
  wait_on_initiator:
80
    title: Waiting on the initiator to respond.
81
    action: complete
82
    transition: :success
Copied!
1
{
2
    "schema": "https://specs.letsflow.io/v0.3.0/scenario",
3
    "title": "A handshake",
4
    "actors": {
5
        "initiator": {
6
            "title": "Initiator"
7
        },
8
        "recipient": {
9
            "title": "Recipient"
10
        }
11
    },
12
    "actions": {
13
        "greet": {
14
            "actor": "initiator",
15
            "title": "Greet the person you're meeting",
16
            "responses": {
17
                "ok": {
18
                    "title": "Hi, how are you?"
19
                }
20
            }
21
        },
22
        "reply": {
23
            "actor": "recipient",
24
            "title": "Respond to the greeting",
25
            "responses": {
26
                "ok": {
27
                    "title": "Fine. How about you?"
28
                },
29
                "not_good": {
30
                    "title": "Not so good."
31
                }
32
            }
33
        },
34
        "ignore": {
35
            "actor": "recipient",
36
            "title": "Ignore the greeting"
37
        },
38
        "sympathize": {
39
            "actor": "initiator",
40
            "title": "Ask further",
41
            "responses": {
42
                "ok": {
43
                    "title": "Sorry to hear that. Please tell me more."
44
                }
45
            }
46
        },
47
        "elaborate": {
48
            "actor": "recipient",
49
            "title": "Tell what's the matter."
50
        },
51
        "complete": {
52
            "actor": "initiator",
53
            "title": "End the conversation"
54
        }
55
    },
56
    "states": {
57
        "initial": {
58
            "action": "greet",
59
            "transition": "wait_on_recipient"
60
        },
61
        "wait_on_recipient": {
62
            "title": "Waiting on the recipient to respond.",
63
            "instructions": {
64
                "recipient": "Respond or, if you're feeling rude, ignore it."
65
            },
66
            "actions": [
67
                "reply",
68
                "ignore"
69
            ],
70
            "transitions": [
71
                {
72
                    "action": "reply",
73
                    "response": "ok",
74
                    "transition": "wait_on_initiator"
75
                },
76
                {
77
                    "action": "reply",
78
                    "response": "not_good",
79
                    "transition": "expect_sympathy"
80
                },
81
                {
82
                    "action": "ignore",
83
                    "transition": ":cancelled"
84
                }
85
            ]
86
        },
87
        "expect_sympathy": {
88
            "title": "Waiting on the initiator to respond.",
89
            "instructions": {
90
                "initiator": "Ask further or end the conversation politely."
91
            },
92
            "actions": [
93
                "sympathize",
94
                "complete"
95
            ],
96
            "transitions": [
97
                {
98
                    "action": "sympathize",
99
                    "transition": "recipient_can_elaborate"
100
                },
101
                {
102
                    "action": "complete",
103
                    "transition": ":success"
104
                }
105
            ]
106
        },
107
        "recipient_can_elaborate": {
108
            "title": "Waiting on the recipient to elaborate.",
109
            "instructions": {
110
                "recipient": "Please explain why it's not going well."
111
            },
112
            "action": "elaborate",
113
            "transition": "expect_sympathy"
114
        },
115
        "wait_on_initiator": {
116
            "title": "Waiting on the initiator to respond.",
117
            "action": "complete",
118
            "transition": ":success"
119
        }
120
    }
121
}
Copied!
Adding titles and instructions is optional. While it makes the scenario less cryptic. It also substantially increase lines of code of the scenario.
We didn't specify a title for the complete action. That's because the response that would giving in the wait on initiator state would would "Fine". In the state where we expect sympathy from initiator would the response for the same action would be "Sorry, to hear that".
We could define a new action, but there are better ways to handle this. We'll discuss that in the next tutorial.
Now you!
The initiator can still only reply with "Fine" when the recipient ask "How about you?". We should change that, so the initiator could also reply with "Could be better". To keep it simple, this will not resort in a conversation.
Keep the structure so that it's still up to the initiator to complete the process. The recipient can only respond with "Sorry to hear that", after which we transition to the state where we wait on the initiator to end the process.
In other words; The initiator can respond with no good, after witch the process transitions to a new state where we expect an acknowledgement from the recipient.
1.Create a new test file named initiator-not-good.feature
2.The Before section should go through the process all the way to the state where we wait on the the initiator.
3.The initiator should then respond with no good, after witch the process transitions to a new state where we expect an acknowledgement from the recipient.
4.Create a new test Scenario section for this use case.
5.Modify the scenario so the new test succeeds.
Tutorials - Previous
The basics
Next - Tutorials
A proper introduction
Last modified 2yr ago
Copy link
Contents
Adding the recipient actor
Keeping the conversation going
Modifying the scenario
Instructions and titles
Now you!