Invitation by e-mail

In our previous tutorials, only users interacted with the process. An important feature of Live Contract is the ability to interact with both people and systems.
This tutorial will start after the introduction and exchange of the recipients e-mail address. The initiator is organizing a meetup and wants to invite the people he met at the conference via e-mail.
Create a new subdirectory named invitation and copy main.feature and scenario.yml from the condition subdirectory.
We'll only focus on the situation where the recipient gives her e-mail address and the process is completed successfully.
1
Feature: Initiator invites the recipient to a meetup.
2
​
3
  Background:
4
    Given a chain is created by "Joe"
5
    Given "Joe" creates the "main" process using the "invitation" 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 "introduce" action of the "main" process with:
11
      | name         | Joe Smith     |
12
      | organization | LTO Network   |
13
    Then the "initiator" actor of the "main" process has:
14
      | name         | Joe Smith     |
15
      | organization | LTO Network   |
16
    And the "main" process is in the "initial" state
17
​
18
    When "Jane" runs the "introduce" action of the "main" process with:
19
      | name         | Jane Wong     |
20
      | organization | Acme Inc      |
21
    Then the "recipient" actor of the "main" process has:
22
      | name         | Jane Wong     |
23
      | organization | Acme Inc      |
24
    And the "main" process is in the "wait_on_initiator" state
25
​
26
    When "Joe" runs the "request_email" action of the "main" process
27
    Then the "main" process is in the "wait_on_recipient" state
28
​
29
    When "Jane" runs the "reply" action of the "main" process with:
30
      | email        | [email protected] |
31
    Then the "recipient" actor of the "main" process has:
32
      | name         | Jane Wong             |
33
      | organization | Acme Inc              |
34
      | email        | [email protected] |
35
    And the "main" process is in the "pending_invitation" state
36
​
37
    When "Joe" runs the "invite" action of the "main" process
38
    Then the "main" process is completed
Copied!
In that case Joe needs to manually invite Jane (and all other invitees) by e-mail. Luckily, the workflow engine supports running actions in an automated manner.
The invite action
An important aspect of a Live Contract is that it only defines what should be done and not how it must be done. In this case we'll define that the initiator should send an e-mail. The way that's done is up to the actor that performs the action.
YAML
JSON
1
actions:
2
  introduce:
3
    actors:
4
      - initiator
5
      - recipient
6
    condition: !eval current.actor.name == null
7
    update: current.actor
8
  request_email:
9
    actor: initiator
10
  reply:
11
    actor: recipient
12
    update: actors.recipient
13
  invite:
14
    $schema: http://exmple.com/schemas/invite/schema.json#
15
    actor: initiator
16
    invitee: !ref actors.recipient
17
    message: Please come to great Meetup next week.
18
​
19
states:
20
  initial:
21
    action: introduce
22
    transitions:
23
      - transition: wait_on_initiator
24
        condition: !eval actors.initiator.name != null && actors.recipient.name != null
25
  wait_on_initiator:
26
    action: request_email
27
    transition: wait_on_recipient
28
  wait_on_recipient:
29
    action: reply
30
    transitions:
31
      - transition: pending_invitation
32
        condition: !eval actors.recipient.email != null
33
      - transition: :cancelled
34
        condition: !eval actors.recipient.email == null
35
  pending_invitation:
36
    action: invite
37
    transition: :success
Copied!
1
{
2
    "actions": {
3
        "introduce": {
4
            "actors": [
5
                "initiator",
6
                "recipient"
7
            ],
8
            "condition": {
9
                "<eval>": "current.actor.name == null"
10
            },
11
            "update": "current.actor"
12
        },
13
        "request_email": {
14
            "actor": "initiator"
15
        },
16
        "reply": {
17
            "actor": "recipient",
18
            "update": "actors.recipient"
19
        },
20
        "invite": {
21
            "$schema": "http://exmple.com/schemas/invite/schema.json#",
22
            "actor": "initiator",
23
            "invitee": "actors.recipient",
24
            "message": "Please come to great Meetup next week."
25
        }
26
    },
27
    "states": {
28
        "initial": {
29
            "action": "introduce",
30
            "transitions": [
31
                {
32
                    "transition": "wait_on_initiator",
33
                    "condition": {
34
                        "<eval>": "actors.initiator.name != null && actors.recipient.name != null"
35
                    }
36
                }
37
            ]
38
        },
39
        "wait_on_initiator": {
40
            "action": "request_email",
41
            "transition": "wait_on_recipient"
42
        },
43
        "wait_on_recipient": {
44
            "action": "reply",
45
            "transitions": [
46
                {
47
                    "transition": "pending_invitation",
48
                    "condition": {
49
                        "<eval>": "actors.recipient.email != null"
50
                    }
51
                },
52
                {
53
                    "transition": ":cancelled",
54
                    "condition": {
55
                        "<eval>": "actors.recipient.email == null"
56
                    }
57
                }
58
            ]
59
        },
60
        "pending_invitation": {
61
            "action": "invite",
62
            "transition": ":success"
63
        }
64
    }
65
}
Copied!
JSON Schema for actions
Up until now, we've only used the default schema for an action. Actions that may be automated should contain all information required to run them. The structure of such an action must be defined in a custom JSON Schema.
The invite action uses a custom JSON Schema, specified with $schema. The schema may be publicly available at the specified URL or can be distributed as part of the Live Contract.
http://exmple.com/schemas/invite/schema.json
JavaScript
1
{
2
    "$schema": "http://json-schema.org/draft-04/schema#",
3
    "type": "object",
4
    "properties": {
5
        "actor": {
6
            "type": "string"
7
        },
8
        "invitee": {
9
            "type": "object",
10
            "properties": {
11
                "name": {
12
                    "type": "string"
13
                },
14
                "email": {
15
                    "type": "string",
16
                    "format": "email"
17
                }
18
            }
19
        },
20
        "subject": {
21
            "type": "string"
22
        },
23
        "message": {
24
            "type": "string"
25
        }
26
    }
27
}
Copied!
1
{
2
    "title": "JSON schema for invite action",
3
    "$schema": "http://json-schema.org/draft-07/schema#",
4
    "type": "object",
5
    "properties": {
6
        "actor": {
7
            "type": "string"
8
        },
9
        "invitee": {
10
            "type": "object",
11
            "properties": {
12
                "name": {
13
                    "type": "string"
14
                },
15
                "email": {
16
                    "type": "string"
17
                }
18
            }
19
        },
20
        "subject": {
21
            "type": "string"
22
        },
23
        "message": {
24
            "type": "string"
25
        }        
26
    }
27
}
Copied!
It's recommended, though not required, that every actor in the process has a copy of the JSON Schema. Actors that may perform the action do require the schema.
Mailgun e-mail service
For this tutorial we'll send an e-mail through Mailgun using their REST API.
Visit https://www.mailgun.com/ and sign up. Mailgun is free up to 10.000 e-mails per month.
On the 'Sending' page, select your sandbox URL.
Add your e-mail address to 'Authorized Recipients' and verify it.
Could not load image
This tutorial uses sandbox000.mailgun.org as endpoint, a dummy API key and [email protected] as e-mail address. Replace that with the (long) sandbox URL, your Mailgun API key and your own e-mail address.
Trigger
A node can define a trigger for an action schema. If an actor on the node is allowed to perform the action the workflow engine will automatically do so.
Triggers are defined through the configuration of the workflow engine. In order to use a custom configuration, please stop docker and than create and link a new directory workflow-settings.
1
$ docker-compose stop
Copied!
In the workflow-settings directory, create a settings.yml file with custom configuration settings. In that file, we'll define a custom trigger for the invite schema.
1
triggers:
2
  invite:
3
    type: http
4
    $schema: http://exmple.com/schemas/invite/schema.json#
5
    url: sandbox000.mailgun.org
6
    method: POST
7
    auth: 
8
      username: api
9
      password: key-00000000000000000000000000000000
10
    headers:
11
      Content-Type: application/x-www-form-urlencoded
12
    data:
13
      from: [email protected]
14
      subject: You are invited to our Meetup
15
    projection: "{ data: { to: join('', [invitee.name, ' <', invitee.email, '>']), text: message } }"
Copied!
The projection is a JMESPath expression that converts the action into an object that's expected by the HTTP trigger.
The data will be encoded and send as request body. The data parameters are described by the Mailgun API. The data in the trigger is merged with the data from the projection.
Triggers are configured by each party on their own node. This node will be configured to send an e-mail using Mailgun, but any other service could be used or an entirely different action could be taken to invite the recipient.
Testing the HTTP request
Enable outgoing capturing HTTP requests in workflow-settings/settings.yml by adding the following setting
1
http_request_log: true
Copied!
In the test, we can check if the workflow engine has send a specific HTTP request.
1
Feature: Initiator invites the recipient to a meetup.
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 "introduce" action of the "main" process with:
11
      | name         | Joe Smith     |
12
      | organization | LTO Network   |
13
    Then the "initiator" actor of the "main" process has:
14
      | name         | Joe Smith     |
15
      | organization | LTO Network   |
16
    And the "main" process is in the "initial" state
17
​
18
    When "Jane" runs the "introduce" action of the "main" process with:
19
      | name         | Jane Wong     |
20
      | organization | Acme Inc      |
21
    Then the "recipient" actor of the "main" process has:
22
      | name         | Jane Wong     |
23
      | organization | Acme Inc      |
24
    And the "main" process is in the "wait_on_initiator" state
25
​
26
    When "Joe" runs the "request_email" action of the "main" process
27
    Then the "main" process is in the "wait_on_recipient" state
28
​
29
    When "Jane" runs the "reply" action of the "main" process with:
30
      | email        | [email protected] |
31
    Then the "recipient" actor of the "main" process has:
32
      | name         | Jane Wong             |
33
      | organization | Acme Inc              |
34
      | email        | [email protected] |
35
    And a "POST" request has been send to "https://api.mailgun.net/v3/sandbox000.mailgun.org/messages" with:
36
      | from    | [email protected]                       |
37
      | to      | Jane Wong <[email protected]>      |
38
      | subject | You are invited to our Meetup          |
39
      | text    | Please come to great Meetup next week. |
40
    And that request received a "200" response with:
41
      | message | Queued. Thank you.                     |
42
​
43
    Then the "main" process is completed
Copied!
The workflow engine can only capture outbound HTTP requests. It can't mock requests, but needs to work with an actual service or you need to setup a custom mocked service yourself.
Tutorials - Previous
Under one condition
Next - REST API
Authentication
Last modified 2yr ago
Copy link
Contents
The invite action
JSON Schema for actions
Mailgun e-mail service
Trigger
Testing the HTTP request